Paperclip
Integrate coding agents with the Paperclip control-plane API for identity, budgets, org chain-of-command, and company-scoped import/export packages.
Overview
Paperclip is an agent skill most often used in Build (also Operate) that documents the Paperclip control-plane REST API for agent identity, budgets, escalation chains, and company-scoped imports and exports.
Install
npx skills add https://github.com/paperclipai/paperclip --skill paperclipWhat is this skill?
- Agent record schema: role, capabilities, status, monthly budget vs spend, and chainOfCommand for escalation
- Company-scoped safe import/export preview and apply routes with collision rules
- CEO and board-only portability constraints; safe imports reject collisionStrategy replace
- Companion to main SKILL.md heartbeat procedure and critical operational rules
- JSON API reference for `/api/agents/me` and company package routes
Adoption & trust: 2k installs on skills.sh; 69.6k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Paperclip-backed agents need correct API shapes, caller permissions, and safe import rules instead of guessing endpoints during heartbeats.
Who is it for?
Indie builders or small labs operating multi-role Paperclip agents who embed heartbeat and company ops in Claude Code, Cursor, or Codex.
Skip if: Builders with no Paperclip deployment who only need a single chat assistant without org budgets or company import/export.
When should I use this skill?
You are building or operating Paperclip-connected agents that must call control-plane APIs for identity, budgets, chain of command, or company import/export with documented safety rules.
What do I get? / Deliverables
Agents call documented routes with proper CEO/board gates, budget checks, and portable company packages without unsafe collision strategies.
- Correct API request/response usage in agent code
- Safe company package import or export flows
- Escalation paths derived from chainOfCommand
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Paperclip wiring is done while assembling multi-agent product infrastructure, which is primarily Build-phase agent tooling. The skill documents REST control-plane endpoints agents call during heartbeats and company operations—not end-user app frontend.
Where it fits
Implement GET /api/agents/me parsing for budget and escalation in a backend engineer agent.
Wire company-scoped export preview before cloning org config to a new environment.
Audit spentMonthlyCents against budgetMonthlyCents when agents spike usage.
Adjust safe import apply flows after collision previews without using replace strategy.
How it compares
Control-plane API reference for Paperclip agents, not a general multi-agent brainstorming or planning skill.
Common Questions / FAQ
Who is paperclip for?
Developers wiring autonomous agents to Paperclip who need authoritative endpoint, schema, and governance details during implementation and ops.
When should I use paperclip?
In Build when implementing agent-tooling heartbeats and company routes, and in Operate when debugging budget spend, escalations, or safe import/export of org packages.
Is paperclip safe to install?
The skill describes privileged CEO and board APIs—review the Security Audits panel on this Prism page and enforce your own auth, budget caps, and staging tests before production imports.
SKILL.md
READMESKILL.md - Paperclip
# Paperclip API Reference Detailed reference for the Paperclip control plane API. For the core heartbeat procedure and critical rules, see the main `SKILL.md`. --- ## Response Schemas ### Agent Record (`GET /api/agents/me` or `GET /api/agents/:agentId`) ```json { "id": "agent-42", "name": "BackendEngineer", "role": "engineer", "title": "Senior Backend Engineer", "companyId": "company-1", "reportsTo": "mgr-1", "capabilities": "Node.js, PostgreSQL, API design", "status": "running", "budgetMonthlyCents": 5000, "spentMonthlyCents": 1200, "chainOfCommand": [ { "id": "mgr-1", "name": "EngineeringLead", "role": "manager", "title": "VP Engineering" }, { "id": "ceo-1", "name": "CEO", "role": "ceo", "title": "Chief Executive Officer" } ] } ``` Use `chainOfCommand` to know who to escalate to. Use `budgetMonthlyCents` and `spentMonthlyCents` to check remaining budget. ### Company Portability CEO-safe package routes are company-scoped: - `POST /api/companies/:companyId/imports/preview` - `POST /api/companies/:companyId/imports/apply` - `POST /api/companies/:companyId/exports/preview` - `POST /api/companies/:companyId/exports` Rules: - Allowed callers: board users and the CEO agent of that same company - Safe import routes reject `collisionStrategy: "replace"` - Existing-company safe imports only create new entities or skip collisions - `new_company` safe imports are allowed and copy active user memberships from the source company - Export preview defaults to `issues: false`; add task selectors explicitly when needed - Use `selectedFiles` on export to narrow the final package after previewing the inventory Example safe import preview: ```json POST /api/companies/company-1/imports/preview { "source": { "type": "github", "url": "https://github.com/acme/agent-company" }, "include": { "company": true, "agents": true, "projects": true, "issues": true }, "target": { "mode": "existing_company", "companyId": "company-1" }, "collisionStrategy": "rename" } ``` Example new-company safe import: ```json POST /api/companies/company-1/imports/apply { "source": { "type": "github", "url": "https://github.com/acme/agent-company" }, "include": { "company": true, "agents": true, "projects": true, "issues": false }, "target": { "mode": "new_company", "newCompanyName": "Imported Acme" }, "collisionStrategy": "rename" } ``` Example export preview without tasks: ```json POST /api/companies/company-1/exports/preview { "include": { "company": true, "agents": true, "projects": true } } ``` Example narrowed export with explicit tasks: ```json POST /api/companies/company-1/exports { "include": { "company": true, "agents": true, "projects": true, "issues": true }, "selectedFiles": [ "COMPANY.md", "agents/ceo/AGENTS.md", "skills/paperclip/SKILL.md", "tasks/pap-42/TASK.md" ] } ``` ### Issue with Ancestors (`GET /api/issues/:issueId`) Includes the issue's `project` and `goal` (with descriptions), plus each ancestor's resolved `project` and `goal`. This gives agents full context about where the task sits in the project/goal hierarchy. The response also includes `blockedBy` and `blocks` arrays showing first-class dependency relationships: ```json { "id": "issue-99", "title": "Implement login API", "parentId": "issue-50", "projectId": "proj-1", "goalId": null, "blockedBy": [ { "id": "issue-80", "identifier": "PAP-80", "title": "Design auth schema", "status": "in_progress", "priority": "high", "assigneeAgentId": "agent-55", "assigneeUserId": null } ], "blocks": [], "project": { "id": "proj-1", "name": "Auth System", "description": "End-to-end authentication and authorization", "status": "active", "goalId": "goal-1", "primaryWorkspace": { "id": "ws-1", "name": "auth-repo", "cwd": "/Users/me/work/auth", "repoUrl": "https://github.com/acme/auth", "repoRef":