From 2cfbb3e4c54c154ec65c815dc0a62062c57619cf Mon Sep 17 00:00:00 2001 From: Dotta Date: Thu, 6 Aug 2026 14:35:46 +0000 Subject: [PATCH] docs(skills): require explicit assignment modes Update shipped and operational skill-sync examples for the required merge-mode contract. Co-Authored-By: Paperclip --- .../bundled/paperclip-operations/reflection-coach/SKILL.md | 2 +- skills/paperclip/SKILL.md | 2 +- skills/paperclip/references/company-skills.md | 7 +++++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md b/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md index b5167838920..205a12494e4 100644 --- a/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md @@ -176,7 +176,7 @@ Server-enforced mutation target keys: When the interaction resolves **accepted**, apply the change in a *separate* run: - **AGENTS.md** — update the target's managed instruction file exactly as the accepted diff specified. -- **Skill** — install/update the skill in the company library, then `POST /api/agents//skills/sync` when the target should receive it. +- **Skill** — install/update the skill in the company library, then `POST /api/agents//skills/sync` with `{"mode":"add","desiredSkills":[""]}` when the target should receive it. Use `remove` only for the named assignments. Use `replace` only after explicit confirmation to overwrite the complete desired skill set. - **Tool description** — update the target agent's description/profile field that the accepted diff named. The server rejects Reflection Coach mutations unless the accepted `request_confirmation` was created by Reflection Coach in a previous run, has a displayed diff, and is bound to the resource by one of the target keys above. If the interaction was rejected or is still pending, apply nothing. If you were asked to apply without a reviewed diff and an accepted interaction, refuse and name the gate — no-same-run-apply is load-bearing. diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 981afa05f26..728395f5bac 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -421,7 +421,7 @@ or linking cases through the agent-facing cases API. Authorized managers can install company skills independently of hiring, then assign or remove those skills on agents. - Install and inspect company skills with the company skills API. -- Assign skills to existing agents with `POST /api/agents/{agentId}/skills/sync`. +- Assign skills to existing agents with `POST /api/agents/{agentId}/skills/sync` and an explicit `add`, `remove`, or `replace` mode. Prefer `add`; `replace` overwrites the complete desired skill set. - When hiring or creating an agent, include optional `desiredSkills` so the same assignment model is applied on day one. If you are asked to install a skill for the company or an agent you MUST read: diff --git a/skills/paperclip/references/company-skills.md b/skills/paperclip/references/company-skills.md index 37ba590ab8f..696653cb9d1 100644 --- a/skills/paperclip/references/company-skills.md +++ b/skills/paperclip/references/company-skills.md @@ -188,11 +188,18 @@ curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills//skills/sync" \ -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ + "mode": "add", "desiredSkills": [ "vercel-labs/agent-browser/agent-browser" ]