Paperclip Create Agent

Paperclip Create Agent Skill

Use this skill when you are asked to hire/create an agent.

Preconditions

You need either:

• board access, or
• agent permission can_create_agents=true in your company

If you do not have this permission, escalate to your CEO or board.

Workflow

1. Confirm identity and company context.

curl -sS "$PAPERCLIP_API_URL/api/agents/me" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

1. Discover available adapter configuration docs for this Paperclip instance.

curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration.txt" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

1. Read adapter-specific docs (example: claude_local).

curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration/claude_local.txt" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

1. Compare existing agent configurations in your company.

curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-configurations" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

1. Discover allowed agent icons and pick one that matches the role.

curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

1. Draft the new hire config:

• role/title/name
• icon (required in practice; use one from /llms/agent-icons.txt)
• reporting line (reportsTo)
• adapter type
• optional desiredSkills from the company skill library when this role needs installed skills on day one
• adapter and runtime config aligned to this environment
• capabilities
• run prompt in adapter config (promptTemplate where applicable)
• source issue linkage (sourceIssueId or sourceIssueIds) when this hire came from an issue

1. Submit hire request.

curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-hires" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CTO",
    "role": "cto",
    "title": "Chief Technology Officer",
    "icon": "crown",
    "reportsTo": "",
    "capabilities": "Owns technical roadmap, architecture, staffing, execution",
    "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
    "adapterType": "codex_local",
    "adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
    "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}},
    "sourceIssueId": ""
  }'

1. Handle governance state:

• if response has approval, hire is pending_approval
• monitor and discuss on approval thread
• when the board approves, you will be woken with PAPERCLIP_APPROVAL_ID; read linked issues and close/comment follow-up

curl -sS "$PAPERCLIP_API_URL/api/approvals/" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals//comments" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"## CTO hire request submitted\n\n- Approval: [](/approvals/)\n- Pending agent: [](/agents/)\n- Source issue: [](/issues/)\n\nUpdated prompt and adapter config per board feedback."}'

If the approval already exists and needs manual linking to the issue:

curl -sS -X POST "$PAPERCLIP_API_URL/api/issues//approvals" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approvalId":""}'

After approval is granted, run this follow-up loop:

curl -sS "$PAPERCLIP_API_URL/api/approvals/$PAPERCLIP_APPROVAL_ID" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

curl -sS "$PAPERCLIP_API_URL/api/approvals/$PAPERCLIP_APPROVAL_ID/issues" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

For each linked issue, either:

• close it if approval resolved the request, or
• comment in markdown with links to the approval and next actions.

Quality Bar

Before sending a hire request:

• if the role needs skills, make sure they already exist in the company library or install them first using the Paperclip company-skills workflow
• Reuse proven config patterns from related agents where possible.
• Set a concrete icon from /llms/agent-icons.txt so the new hire is identifiable in org and task views.
• Avoid secrets in plain text unless required by adapter behavior.
• Ensure reporting line is correct and in-company.
• Ensure prompt is role-specific and operationally scoped.
• If board requests revision, update payload and resubmit through approval flow.

For endpoint payload shapes and full examples, read: skills/paperclip-create-agent/references/api-reference.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IncomeStreamSurfer
• Source: IncomeStreamSurfer/paperclip-surfers
• License: MIT

Install and usage instructions live in the source repository linked above.