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.
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.
Building a profile
In the Team section → Share with the team.
- Pick the project folder. The list already holds the ones you 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.
There is deliberately no section in the menu: a section would require remembering
that the feature exists at all.
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.
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.