Paperclip Skill
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.
Terminology
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.
Authentication
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 sandbox-backed local adapters, the Bash/tool environment may receive
PAPERCLIP_API_URL
and
PAPERCLIP_API_KEY
for a run-scoped bridge instead of the host API directly; use those exact env vars from Bash/curl and do not assume the host port is reachable from browser or web tools. 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, and never paste the API key or bridge token into prompts, comments, documents, restored workspace files, or logs.
Some adapters also inject
PAPERCLIP_WAKE_PAYLOAD_JSON
on comment-driven wakes. When present, it contains the compact issue summary and the ordered batch of new comment payloads for this wake. Use it first. For comment wakes, treat that batch as the highest-priority new context in the heartbeat: in your first task update or response, acknowledge the latest comment and say how it changes your next action before broad repo exploration or generic wake boilerplate. Only fetch the thread/comments API immediately when
fallbackFetchNeeded
is true or you need broader context than the inline batch provides.
Manual local CLI mode (outside heartbeat runs): use
paperclipai agent local-cli
paperclip
安装
npx skills add https://github.com/getpaperclipai/paperclip --skill paperclip