diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 69a13988379..b1d1a840f5c 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -1,10 +1,10 @@ --- name: paperclip description: > - Use for Paperclip-managed tasks and heartbeats: reading task context, delivering - task documents or files, updating completion or blockers, coordinating or - delegating work, and following company governance. Includes control plane API - operations for assignments, comments, approvals, and routines. + Interact with the Paperclip control plane API for task coordination and + governance. Use when checking assignments, updating issue status, posting + comments, delegating work, managing routines, or calling Paperclip API + endpoints. --- # Paperclip Skill @@ -15,7 +15,7 @@ You run in **heartbeats** — short execution windows triggered by Paperclip. Ea In Paperclip, **task** and **issue** refer to the same work item. The UI may use "task" while APIs, database fields, route names, and older docs may still say "issue"; treat them as the same entity unless a local context explicitly distinguishes them. -**Task documents (API runtimes).** When asked for a task document, save it on the Paperclip issue with `PUT /api/issues/{issueId}/documents/{key}`, unless the requester specifies another destination. Confirm the returned document's saved revision and add a clickable Markdown link before reporting completion; read [references/issue-documents.md](references/issue-documents.md) for the payload and revision-safe updates. Downloadable files follow [Generated Artifacts and Work Products](#generated-artifacts-and-work-products). +**Task documents (API runtimes).** When asked for a task document, save it on the Paperclip issue with `PUT /api/issues/{issueId}/documents/{key}`, unless the requester specifies another destination. Confirm the returned document's saved revision and link it before reporting completion; read [references/issue-documents.md](references/issue-documents.md) for the payload and revision-safe updates. Downloadable files follow [Generated Artifacts and Work Products](#generated-artifacts-and-work-products). ## Authentication diff --git a/skills/paperclip/references/issue-documents.md b/skills/paperclip/references/issue-documents.md index f41fe3f2d5a..88050a6732b 100644 --- a/skills/paperclip/references/issue-documents.md +++ b/skills/paperclip/references/issue-documents.md @@ -32,10 +32,10 @@ with the saved document JSON. Check its `key`, `body`, and `latestRevisionId` before claiming delivery. This receipt is sufficient; another GET is unnecessary when it confirms the intended content and a saved revision. -Add a clickable Markdown link in the completion comment or response: -Saved [Task report](/PAP/issues/PAP-123#document-report). -Use the prefix from the current issue identifier and the key from the write receipt; -a locked document can redirect an agent's write to a new document. +Link the returned document key in the completion comment or response: +`//issues/#document-`. +Use the returned key because a locked document can redirect an agent's write +to a new document. ## Update or resolve an unclear write diff --git a/tests/runner-e2e/opencode-skill-routing-comparison.json b/tests/runner-e2e/opencode-skill-routing-comparison.json new file mode 100644 index 00000000000..345b1254ff2 --- /dev/null +++ b/tests/runner-e2e/opencode-skill-routing-comparison.json @@ -0,0 +1,26 @@ +{ + "schema": "paperclip.opencode-skill-routing.baseline/v1", + "candidateSha": "fe9dc1e3c518825242ed889ab9c8352986f8c2ed", + "priorSkillSha": "b85668c4065d66e08026218a6bd48a3d22ddd4c9", + "expectedCellsPerVariant": 2, + "expectedProviderTurnsPerVariant": 2, + "heldConstant": [ + "tiny manual/shared prompts", + "native Codex additive base fix", + "future explicit clickable UI-link fixture and calibrated grader", + "models/effort/auth/permissions/tools/budgets", + "all other tracked repository source bytes" + ], + "onlyChangedProductionSources": [ + { + "path": "skills/paperclip/SKILL.md", + "candidateSha256": "6ca593effe18704f8014ac4e8155f7513c0701aa3c61d3cf0b96d3366c92f0e1", + "baselineSha256": "768522e081c1ec43dee4a5794539f7b597ee3708c634d05e388c874df283cc53" + }, + { + "path": "skills/paperclip/references/issue-documents.md", + "candidateSha256": "a6141e8ba4510b683418197d58598d5a14db2641c49c869ae8aca4e2b05aca97", + "baselineSha256": "353845a406b1b4948487c348c86eb7b8c89a55ae67afe203100eee10aee46336" + } + ] +}