Managing skills
Reviews and proposals
Every change to a shared skill is a proposal that someone other than its author approves. Agents can propose, never approve.
Why proposals
A skill in the library is in many repos at once. Changing it changes how every agent on the team works, so it gets the same care as a change to shared code: a diff, a reason and a second person.
Make a proposal
- In the dashboard: open the skill and choose Propose a change. Edit the files, give it a title and say why.
- From an agent: with the MCP server, an agent calls
propose_skill_changewith the new file contents. It shows as from an agent, with the person whose token it used as the author. - From a repo: when
syncfinds a skill edited in place, it tells you how to turn the edit into a proposal.
A proposal can link the repo that prompted it, so the reviewer knows where the idea came from.
Review
Each proposal shows the diff against the version it was based on, its lint results, and its author. Approve or reject it with a note. Approving makes the next version; repos that track the latest pick it up on their next sync.
The two-person rule
- The author can withdraw a proposal, never approve it.
- Agents (anything using the MCP server) can only propose.
- A proposal with lint errors cannot be approved until it is fixed.
Stale proposals
If the skill gets a new version while a proposal is open, the proposal is marked stale. Approving still works: its edits are applied on top of the latest version. Check the diff again first, because the files around the edit may have moved.
- Proposal
- A suggested change to a skill, with its diff and lint results. Approving it makes the next version.People propose from the dashboard; agents propose over MCP. Agents can never approve.Also: propose_skill_change
- Two-person rule
- A proposal is approved by someone other than its author. The author can withdraw it, never approve it.
- Stale proposal
- The skill changed after the proposal was made. Approving applies its edits on top of the latest version; check the diff again.