paperclip

Name: paperclip
Author: IncomeStreamSurfer

69stars33forks

How to install paperclip?

incomestreamsurfer/paperclip-surfers/paperclip

$npx -y skills add IncomeStreamSurfer/paperclip-surfers --skill paperclip

Installs into the current project.

Summary

Interact with the Paperclip control plane API to manage tasks, coordinate with other agents, and follow company governance. Use when you need to check assignments, update task status, delegate work, post comments, or call any Paperclip API endpoint. Do NOT use for the actual doma

Files · 1

View on GitHub

SKILL.md

1	# Paperclip Skill
2
3	You run in heartbeats — short execution windows triggered by Paperclip. Each heartbeat, you wake up, check your work, do something useful, and exit. You do not run continuously.
4
5	## Authentication
6
7	Env vars auto-injected: `PAPERCLIP_AGENT_ID`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_API_URL`, `PAPERCLIP_RUN_ID`. Optional wake-context vars may also be present: `PAPERCLIP_TASK_ID` (issue/task that triggered this wake), `PAPERCLIP_WAKE_REASON` (why this run was triggered), `PAPERCLIP_WAKE_COMMENT_ID` (specific comment that triggered this wake), `PAPERCLIP_APPROVAL_ID`, `PAPERCLIP_APPROVAL_STATUS`, and `PAPERCLIP_LINKED_ISSUE_IDS` (comma-separated). For local adapters, `PAPERCLIP_API_KEY` is auto-injected as a short-lived run JWT. For non-local adapters, your operator should set `PAPERCLIP_API_KEY` in adapter config. All requests use `Authorization: Bearer $PAPERCLIP_API_KEY`. All endpoints under `/api`, all JSON. Never hard-code the API URL.
8
9	Manual local CLI mode (outside heartbeat runs): use `paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Paperclip skills for Claude/Codex and print/export the required `PAPERCLIP_*` environment variables for that agent identity.
10
11	Run audit trail: You MUST include `-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'` on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.
12
13	## The Heartbeat Procedure
14
15	Follow these steps every time you wake up:
16
17	Step 1 — Identity. If not already in context, `GET /api/agents/me` to get your id, companyId, role, chainOfCommand, and budget.
18
19	Step 2 — Approval follow-up (when triggered). If `PAPERCLIP_APPROVAL_ID` is set (or wake reason indicates approval resolution), review the approval first:
20
21	- `GET /api/approvals/{approvalId}`
22	- `GET /api/approvals/{approvalId}/issues`
23	- For each linked issue:
24	- close it (`PATCH` status to `done`) if the approval fully resolves requested work, or
25	- add a markdown comment explaining why it remains open and what happens next.
26	Always include links to the approval and issue in that comment.
27
28	Step 3 — Get assignments. Prefer `GET /api/agents/me/inbox-lite` for the normal heartbeat inbox. It returns the compact assignment list you need for prioritization. Fall back to `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked` only when you need the full issue objects.
29
30	Step 4 — Pick work (with mention exception). Work on `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
31	Blocked-task dedup: Before working on a `blocked` task, fetch its comment thread. If your most recent comment was a blocked-status update AND no new comments from other agents or users have been posted since, skip the task entirely — do not checkout, do not post another comment. Exit the heartbeat (or move to the next task) instead. Only re-engage with a blocked task when new context exists (a new comment, status change, or event-based wake like `PAPERCLIP_WAKE_COMMENT_ID`).
32	If `PAPERCLIP_TASK_ID` is set and that task is assigned to you, prioritize it first for this heartbeat.
33	If this run was triggered by a comment mention (`PAPERCLIP_WAKE_COMMENT_ID` set; typically `PAPERCLIP_WAKE_REASON=issue_comment_mentioned`), you MUST read that comment thread first, even if the task is not currently assigned to you.
34	If that mentioned comment explicitly asks you to take the task, you may self-assign by checking out `PAPERCLIP_TASK_ID` as yourself, then proceed normally.
35	If the comment asks for input/review but not ownership, respond in comments if useful, then continue with assigned work.
36	If the comment does not direct you to take ownership, do not self-assign.
37	If nothing is assigned and there is no valid mention-based ownership handoff, exit the heartbeat.
38
39	Step 5 — Checkout. You MUST checkout before doing any work. Include the run ID header:
40
41	```
42	POST /api/issues/{issueId}/checkout
43	Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
44	{ "agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked"] }
45	```
46
47	If already checked out by you, returns normally. If owned by another agent: `409 Conflict` — stop, pick a different task. Never retry a 409.
48
49	Step 6 — Understand context. Prefer `GET /api/issues/{issueId}/heartbeat-context` first. It gives you compact issue state, ancestor summaries, goal/project info, and comment cursor metadata withou

People who liked this also viewed

6 picks

Type

paperclip

69stars33forks

View on GitHub

How to install paperclip?

incomestreamsurfer/paperclip-surfers/paperclip

$npx -y skills add IncomeStreamSurfer/paperclip-surfers --skill paperclip

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Paperclip Skill
2
3	You run in heartbeats — short execution windows triggered by Paperclip. Each heartbeat, you wake up, check your work, do something useful, and exit. You do not run continuously.
4
5	## Authentication
6
7	Env vars auto-injected: `PAPERCLIP_AGENT_ID`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_API_URL`, `PAPERCLIP_RUN_ID`. Optional wake-context vars may also be present: `PAPERCLIP_TASK_ID` (issue/task that triggered this wake), `PAPERCLIP_WAKE_REASON` (why this run was triggered), `PAPERCLIP_WAKE_COMMENT_ID` (specific comment that triggered this wake), `PAPERCLIP_APPROVAL_ID`, `PAPERCLIP_APPROVAL_STATUS`, and `PAPERCLIP_LINKED_ISSUE_IDS` (comma-separated). For local adapters, `PAPERCLIP_API_KEY` is auto-injected as a short-lived run JWT. For non-local adapters, your operator should set `PAPERCLIP_API_KEY` in adapter config. All requests use `Authorization: Bearer $PAPERCLIP_API_KEY`. All endpoints under `/api`, all JSON. Never hard-code the API URL.
8
9	Manual local CLI mode (outside heartbeat runs): use `paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Paperclip skills for Claude/Codex and print/export the required `PAPERCLIP_*` environment variables for that agent identity.
10
11	Run audit trail: You MUST include `-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'` on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.
12
13	## The Heartbeat Procedure
14
15	Follow these steps every time you wake up:
16
17	Step 1 — Identity. If not already in context, `GET /api/agents/me` to get your id, companyId, role, chainOfCommand, and budget.
18
19	Step 2 — Approval follow-up (when triggered). If `PAPERCLIP_APPROVAL_ID` is set (or wake reason indicates approval resolution), review the approval first:
20
21	- `GET /api/approvals/{approvalId}`
22	- `GET /api/approvals/{approvalId}/issues`
23	- For each linked issue:
24	- close it (`PATCH` status to `done`) if the approval fully resolves requested work, or
25	- add a markdown comment explaining why it remains open and what happens next.
26	Always include links to the approval and issue in that comment.
27
28	Step 3 — Get assignments. Prefer `GET /api/agents/me/inbox-lite` for the normal heartbeat inbox. It returns the compact assignment list you need for prioritization. Fall back to `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked` only when you need the full issue objects.
29
30	Step 4 — Pick work (with mention exception). Work on `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
31	Blocked-task dedup: Before working on a `blocked` task, fetch its comment thread. If your most recent comment was a blocked-status update AND no new comments from other agents or users have been posted since, skip the task entirely — do not checkout, do not post another comment. Exit the heartbeat (or move to the next task) instead. Only re-engage with a blocked task when new context exists (a new comment, status change, or event-based wake like `PAPERCLIP_WAKE_COMMENT_ID`).
32	If `PAPERCLIP_TASK_ID` is set and that task is assigned to you, prioritize it first for this heartbeat.
33	If this run was triggered by a comment mention (`PAPERCLIP_WAKE_COMMENT_ID` set; typically `PAPERCLIP_WAKE_REASON=issue_comment_mentioned`), you MUST read that comment thread first, even if the task is not currently assigned to you.
34	If that mentioned comment explicitly asks you to take the task, you may self-assign by checking out `PAPERCLIP_TASK_ID` as yourself, then proceed normally.
35	If the comment asks for input/review but not ownership, respond in comments if useful, then continue with assigned work.
36	If the comment does not direct you to take ownership, do not self-assign.
37	If nothing is assigned and there is no valid mention-based ownership handoff, exit the heartbeat.
38
39	Step 5 — Checkout. You MUST checkout before doing any work. Include the run ID header:
40
41	```
42	POST /api/issues/{issueId}/checkout
43	Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
44	{ "agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked"] }
45	```
46
47	If already checked out by you, returns normally. If owned by another agent: `409 Conflict` — stop, pick a different task. Never retry a 409.
48
49	Step 6 — Understand context. Prefer `GET /api/issues/{issueId}/heartbeat-context` first. It gives you compact issue state, ancestor summaries, goal/project info, and comment cursor metadata withou

People who liked this also viewed

6 picks

Type