Move artifact upload details to skill reference

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 08:30:39 +09:00 · 2026-05-31 18:18:48 +00:00 · 2026-05-31 18:18:48 +00:00 · e080e4686a
commit e080e4686a
parent c4bb68c14b
3 changed files with 53 additions and 44 deletions
--- a/server/src/tests/paperclip-skill-utils.test.ts
+++ b/server/src/tests/paperclip-skill-utils.test.ts
@ -45,12 +45,16 @@ describe("paperclip skill utils", () => {

  it("documents artifact uploads in the installed Paperclip skill", async () => {
    const skillBody = await fs.readFile(path.resolve("skills/paperclip/SKILL.md"), "utf8");
+    const referenceBody = await fs.readFile(path.resolve("skills/paperclip/references/artifacts.md"), "utf8");

    expect(skillBody).toContain("Generated Artifacts and Work Products");
-    expect(skillBody).toContain("scripts/paperclip-upload-artifact.sh");
-    expect(skillBody).toContain("POST");
-    expect(skillBody).toContain("/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments");
-    expect(skillBody).toContain("/api/issues/$PAPERCLIP_TASK_ID/work-products");
+    expect(skillBody).toContain("references/artifacts.md");
+    expect(skillBody).not.toContain("/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments");
+    expect(referenceBody).toContain("Generated Artifacts and Work Products");
+    expect(referenceBody).toContain("scripts/paperclip-upload-artifact.sh");
+    expect(referenceBody).toContain("POST");
+    expect(referenceBody).toContain("/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments");
+    expect(referenceBody).toContain("/api/issues/$PAPERCLIP_TASK_ID/work-products");
    await expect(
      fs.access(path.resolve("skills/paperclip/scripts/paperclip-upload-artifact.sh")),
    ).resolves.toBeUndefined();
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@ -98,46 +98,7 @@ If `currentParticipant` does not match you, do not try to advance the stage —

 When work produces a user-inspectable file, upload it to the current issue before final disposition. Local filesystem paths are not enough because board users, reviewers, and cloud operators may not have access to the agent workspace.

-Use the helper bundled with this skill. From an installed `paperclip` skill directory, the helper lives at `scripts/paperclip-upload-artifact.sh`:
-
-```bash
-scripts/paperclip-upload-artifact.sh path/to/output.webm \
-  --title "Walkthrough render" \
-  --summary "Rendered walkthrough for review"
-```
-
-The helper uses `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_TASK_ID`, and `PAPERCLIP_RUN_ID`. It uploads the file as an issue attachment, creates an attachment-backed artifact work product by default, and prints issue-safe markdown links for your final comment.
-
-If the helper is unavailable, use the Paperclip API directly:
-
-```bash
-curl -sS -X POST \
-  "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -F 'file=@"path/to/output.webm";type=video/webm'
-```
-
-Then create a work product when the file is the deliverable. The server canonicalizes attachment-backed artifact metadata from the `attachmentId`:
-
-```bash
-curl -sS -X POST \
-  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/work-products" \
-  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-  -H "Content-Type: application/json" \
-  --data-binary '{
-    "type": "artifact",
-    "provider": "paperclip",
-    "title": "Walkthrough render",
-    "status": "ready_for_review",
-    "reviewState": "needs_board_review",
-    "isPrimary": true,
-    "metadata": { "attachmentId": "<uploaded-attachment-id>" }
-  }'
-```
-
-In your final issue comment, link the uploaded attachment or work product and describe what it contains. Do not leave artifact-producing work `in_progress` with only a local path or a `Remaining` note.
+For technical upload instructions, read `references/artifacts.md`.

 **Step 8 — Update status and communicate.** Always include the run ID header.
 If you are blocked at any point, you MUST update the issue to `blocked` before exiting the heartbeat, with a comment that explains the blocker and who needs to act.
--- a/skills/paperclip/references/artifacts.md
+++ b/skills/paperclip/references/artifacts.md
@ -0,0 +1,44 @@
+# Generated Artifacts and Work Products
+
+When work produces a user-inspectable file, upload it to the current issue before final disposition. Local filesystem paths are not enough because board users, reviewers, and cloud operators may not have access to the agent workspace.
+
+Use the helper bundled with this skill. From an installed `paperclip` skill directory, the helper lives at `scripts/paperclip-upload-artifact.sh`:
+
+```bash
+scripts/paperclip-upload-artifact.sh path/to/output.webm \
+  --title "Walkthrough render" \
+  --summary "Rendered walkthrough for review"
+```
+
+The helper uses `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_TASK_ID`, and `PAPERCLIP_RUN_ID`. It uploads the file as an issue attachment, creates an attachment-backed artifact work product by default, and prints issue-safe markdown links for your final comment.
+
+If the helper is unavailable, use the Paperclip API directly:
+
+```bash
+curl -sS -X POST \
+  "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues/$PAPERCLIP_TASK_ID/attachments" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -F 'file=@"path/to/output.webm";type=video/webm'
+```
+
+Then create a work product when the file is the deliverable. The server canonicalizes attachment-backed artifact metadata from the `attachmentId`:
+
+```bash
+curl -sS -X POST \
+  "$PAPERCLIP_API_URL/api/issues/$PAPERCLIP_TASK_ID/work-products" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+  -H "Content-Type: application/json" \
+  --data-binary '{
+    "type": "artifact",
+    "provider": "paperclip",
+    "title": "Walkthrough render",
+    "status": "ready_for_review",
+    "reviewState": "needs_board_review",
+    "isPrimary": true,
+    "metadata": { "attachmentId": "<uploaded-attachment-id>" }
+  }'
+```
+
+In your final issue comment, link the uploaded attachment or work product and describe what it contains. Do not leave artifact-producing work `in_progress` with only a local path or a `Remaining` note.