Project profile
The .onplate/profile.json file sits next to the code and answers “what this
project needs”: which skills, MCP servers and subagents whoever works on it
should have.
onplate writes it, and people read it in the diff of a pull request. That is its main value: the agreement about what the team uses is discussed where everything else about the project is discussed — not in a chat thread that will be forgotten.
The project profile is part of the Projects section, where you also see what this code already has installed and what it actually used.
Not to be confused with the team profile: that one answers “who I am in the company”, lives in a separate registry repository and installs globally.
What is in the repository
.onplate/
profile.json ← the list: name, version, checksum, targets
README.md ← “what this folder is” for people without onplate
files/skills/go-review/SKILL.md ← the body as ordinary markdown
files/agents/db-migrator.md
Skill bodies live in separate files, not as strings inside JSON: otherwise the diff is unreadable, and a readable diff is the whole point. An MCP server is the exception: it has no free-form text, only ten lines of config, so it travels inside the manifest.
Where the profile lives
The profile is committed together with the code, so its place is decided not by the shape of the project but by one question: where can this be sent as a pull request.
| Project shape | How many profiles | Where it is written |
|---|---|---|
| a single code folder | one | the repository root |
| a monorepo | one | the root; entries can name parts |
| a workspace folder with several clones | one per clone | the root of each repository |
In a workspace folder the project page shows a “Profiles of parts” block — a list of places with the state of each. A folder without its own repository is not a place for a profile, and onplate explains why it does not offer to write there.
In a monorepo there is still one profile, but an entry can name a part: the
migrations skill goes to backend rather than to the root. Such a file declares
the second schema version and an older onplate build will honestly reject it —
better than installing everything into the root while pretending it understood. A
profile without parts stays at the first version and is read by already released
builds.
Building a profile
On the project page, in the The project profile and this machine block → Create profile (in a workspace folder — “Create profile” next to the part you need).
- Pick the project in the «Projects» group of the sidebar. If the folder is not there yet, add it — onplate suggests the ones you already worked in.
- Tick what you are sharing. The list is split into three groups: already in this project (ticked in advance), installed globally on your machine, and the rest of your storage under a search box. “Installed globally” is the usual first step: a personal setup becomes a team one.
- At the bottom is the token total: “the profile adds N tokens to everyone’s context”. That is what the set will weigh for every colleague on every request. A good profile is 5–10 entries, not everything you own.
- Show what we will write — the JSON itself, before it is written.
- Write into the repository.
onplate shows the path and the command:
git add .onplate && git commit -m "onplate: project profile"
A person commits and pushes, not onplate. From there it is an ordinary pull request.
Applying a profile
A colleague runs git pull. On the next onplate launch a “A project profile is
waiting” card appears on the dashboard with that folder.
The project page itself shows the same thing in its «Project readiness» block,
with a count of changes waiting to be reviewed.
onplate only checks the folders it already knows — Claude Code projects and the scan roots from your settings. It does not walk your disk looking for repositories.
The Review button opens the plan — what will happen, before anything changes:
| Class | What it means | Default action |
|---|---|---|
| you do not have it | neither in storage nor in the project | install |
| the profile has a newer one | you have an older version | update |
| matches | everything is as it should be | nothing |
| yours is newer | your version is fresher | never roll back |
| divergence | same version, different content | keep yours |
| the same thing | different origin, identical bytes | merge |
| name taken | a different thing under the same name | rename yours |
| cannot be applied | the required AI is missing, the record is in the trash | skip |
The install goes into this project, not globally. The targets are narrowed to
your machine: if you only have Codex, a “claude + codex” entry will not hang
around as an eternal shortfall. A profile can also name .agents as a target —
the shared folder read by both Codex and Cursor: one entry instead of two, but a
weaker promise than installing into a named tool.
Three decisions worth knowing
A newer local version is never rolled back. A rollback on somebody else’s button takes away work you have just done. Instead you are offered to send yours into the profile.
A divergence arrives as the next version. If you edited a skill and the profile has the same version with different content, “take from the profile” adds 1.3.1 instead of overwriting 1.3.0. Your body stays in the history and the divergence becomes visible instead of quietly disappearing.
Nothing dangerous is applied silently. The class stays honest, but the default action is to skip. You include the record yourself, after seeing the justification its author wrote into the file.
Your refusal is remembered: the next git pull will not ask again.
Secrets and trust
Only the names of secrets travel into the file. A value in which the scanner sees credentials, onplate refuses to write — it substitutes a required secret and explains what and why. A token accidentally typed into an ordinary environment variable is the easiest way to hurt yourself with a feature like this, so here it is a ban, not a piece of advice.
A profile cannot carry anything executable: only skills, MCP servers and subagents. No hooks, no commands, no post-install scripts.
What it does not do
- It does not delete what is installed in the project beyond the profile — it only highlights it.
- It does not apply itself: writing into somebody’s AI configs takes a person.
- It does not follow links: entries whose source is a git repo or a platform are read and shown, but applied as “cannot be applied”. Everything written inside the team travels by value — and that is the main case.