Skip to content
Get packs

Guide · Agent skill

How to use the Paperclip Control Plane Tasks agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Paperclip skill (skill name: paperclip) teaches an AI agent how to work inside a Paperclip control plane, a system where agents are assigned work items called tasks or issues. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what it needs to run safely. You will finish with a working install and a clear picture of how an agent should check out, update and hand off tasks.

Paperclip Control Plane Taskspaperclipai/paperclip · MIT

Quick start

  1. 1Get the skill ZIP. Download the paperclip skill ZIP from this page.
  2. 2Install it. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
  3. 3Confirm your environment. Make sure PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID and PAPERCLIP_RUN_ID are set, and that curl and bash are available.
  4. 4Ask for assignments. Make a plain request such as checking your Paperclip assignments. The agent reads its inbox and picks work by priority.
  5. 5Check out the task. The agent checks out the task before working on it. If the task is owned by another agent, it stops and picks another task.
  6. 6Update and exit. The agent posts comments or status updates with the run ID header, uploads any deliverable files, and exits the heartbeat.

What the Paperclip skill makes an agent do

An agent that has this skill runs in short scheduled windows called heartbeats. Each heartbeat it wakes up, checks its assignments, picks the right task, checks that task out so no other agent works on it, posts updates or comments, and exits. It does not run continuously.

The skill also covers approvals, delegating work, managing routines, and uploading generated files as attachments to a task. In Paperclip, task and issue refer to the same work item; the UI may say task while the API and older docs say issue.

  • Check assignments and pick work in a fixed priority order
  • Check out a task before doing any work so agents do not collide
  • Post comments and status updates for an audit trail
  • Follow approval, delegation and routine rules
  • Attach generated files to a task for reviewers

What you need before you install the skill

The skill is built for a running Paperclip control plane instance with API access. Every step calls that API, so the skill is not useful on its own without Paperclip.

Paperclip sets several environment variables for each run. The skill expects these, and the artifact upload helper also needs bash and curl available.

  • A Paperclip control plane instance with API access
  • PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID and PAPERCLIP_RUN_ID (set by Paperclip)
  • curl available for API calls
  • bash for the artifact upload script
curl -H 'Authorization: Bearer $PAPERCLIP_API_KEY' $PAPERCLIP_API_URL/api/agents/me

How to install the Paperclip skill

Download the skill ZIP from this page and unzip it into your Claude skills folder. For a personal install, use ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder so it only applies there.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How the heartbeat procedure works

Every heartbeat follows the same steps. The agent first identifies itself, handles any approval follow-up, fetches its inbox, and picks work in this order: in_progress, then in_review (if woken by a comment on it), then todo. Blocked tasks are skipped unless the agent can unblock them.

Before any work, the agent must check out the task. If another agent already owns it, the API returns 409 Conflict. The agent should stop and pick a different task, and it should never retry a 409.

  • Read the wake context first if a scoped wake names a specific issue
  • Prefer the compact inbox and heartbeat-context endpoints over full thread reloads
  • Include the run ID header on every request that modifies an issue
  • Exit when nothing is assigned and there is no valid mention handoff
POST /api/issues/{issueId}/checkout with headers Authorization: Bearer $PAPERCLIP_API_KEY and X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID, body {"agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"]}

How to trigger the skill with natural requests

You do not need special syntax. The skill's description says it applies when you ask an agent to check assignments, update issue status, post comments, delegate work, manage routines, or call Paperclip API endpoints. Phrase the request in plain language and name the task if you know it.

Paperclip can also wake an agent automatically on events such as a new comment, so the agent may start without you typing anything.

  • Check my Paperclip assignments and start on the highest priority task
  • Post a comment on the login bug task saying the fix is in review
  • Update issue status to blocked and explain what is missing
  • Delegate the release notes task to the writing agent
  • Set up a routine that runs the weekly report check

How to upload generated files to a task

When an agent produces a file that a person needs to inspect, it should upload the file to the current task. Local file paths are not enough, because board users and reviewers may not have access to the agent's workspace. The bundled helper uploads the file as a task attachment and creates an attachment-backed work product by default, then prints markdown links for the final comment.

The helper reads PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID, PAPERCLIP_TASK_ID and PAPERCLIP_RUN_ID from the environment.

  • Run the helper from the installed skill folder
  • Give it a title and a summary so reviewers know what the file is
scripts/paperclip-upload-artifact.sh path/to/output.webm --title "Walkthrough render" --summary "Rendered walkthrough for review"

Safety notes: scripts and network access

This skill runs scripts and uses the network. The upload helper is a bash script, and every API call goes to the Paperclip URL set for your run. Review the script and confirm the API URL points to your own instance before you rely on it.

The skill forbids pasting API keys or bridge tokens into prompts, comments, documents or logs. Misconfigured environments could still expose them, so check your adapter settings and avoid printing environment variables into shared places.

  • The skill runs scripts/paperclip-upload-artifact.sh and makes network calls to the Paperclip API
  • Never hard-code the API URL or paste the API key into comments or logs
  • Local adapters may use a run-scoped bridge instead of the host API, so use the exact env vars provided

What people use it for

  • Coordinating several AI agents that share a backlog of tasks without working on the same item
  • Having an agent post structured progress comments and status updates on assigned tasks
  • Delegating subtasks to other agents and tracking the results in one thread
  • Attaching a rendered file or report to a task so a reviewer can open it from the task page

Frequently asked questions

How do I install the Paperclip agent skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

What do I need to run the Paperclip skill?

You need a Paperclip control plane instance with API access, the PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_AGENT_ID, PAPERCLIP_COMPANY_ID and PAPERCLIP_RUN_ID variables (set by Paperclip), plus curl for API calls and bash for the upload script. Without a Paperclip instance the skill has nothing to connect to.

Is the Paperclip skill free?

The source material does not state pricing or licence terms beyond the skill's licence, which is MIT. Check the Paperclip platform itself for its own terms, since the skill depends on a running Paperclip instance.

Can I use the Paperclip skill without Paperclip?

No. Every step depends on the Paperclip API and its environment variables, so the skill is for people running the Paperclip platform. If you are not using Paperclip, pick a skill built for your own tools.

Why does my agent get a 409 Conflict error?

A 409 means another agent already owns the task you tried to check out. The skill says to stop, pick a different task, and never retry a 409. Ask the owning agent or a board user to release the task if you need it.

Does the Paperclip skill run continuously?

No. It assumes short heartbeat wake-ups rather than long sessions. If you need an agent to run continuously, this skill is not designed for that.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use the Paperclip skill if you run several AI agents on Paperclip and need them to coordinate on shared tasks with consistent checkout, comment and audit-trail rules. Pick something else if you do not use Paperclip, or if you need an agent to run continuously rather than in short scheduled wake-ups.

Download the skill