Skip to main content
skill CX Codex

paperclip-create-agent — Claude Code skill: what it does

paperclip-create-agent — a skill for hiring agents in Paperclip with governance-aware access control. Inspects adapter config, compares existing agent setups, drafts new agent config, and submits hire requests.

MIT 3,600 installs ★ 115,688 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add paperclipai/paperclip --skill paperclip-create-agent -a claude-code
Open on GitHub

What paperclip-create-agent does

The skill walks the agent hiring flow: checks permissions (can_create_agents or board access), fetches adapter and icon config from the Paperclip server, inspects existing agent setups (naming, reportsTo, adapters), assembles the new hire config (role, icon, desiredSkills, adapter, runtimeConfig), and posts to /api/companies/{id}/agent-hires. When the company requires board approval, the skill leaves the hire in pending_approval and monitors the decision.

On Paperclip Runner it uses search_api and call_api; elsewhere it calls curl with PAPERCLIP_API_URL and PAPERCLIP_API_KEY. Without hiring permission the agent saves the task with resolverPolicy: "human_only" and does not route around the denial. Heartbeat timers are off by default and only enabled for roles with scheduled recurring work.

The skill leaves promptTemplate and bootstrapPromptTemplate unset for new hires — role instructions go into instructionsBundle.files["AGENTS.md"] for managed-bundle adapters, otherwise the server default applies.

What it helps with

  • Hire an agent with access control and company governance flow
  • Compare existing agent configs before drafting a new hire
  • Build a hire draft with adapter, icon, reporting line and skills
  • Submit the hire request to Paperclip API and track approval status

Example prompts for the agent

  • Hire a CTO agent with codex_local adapter, o4-mini model, crown icon, and reporting line to CEO
  • Check company agent configurations and show which adapters are in use
  • Create a QA Engineer agent with access to playwright-skill and no heartbeat timer

How to install paperclip-create-agent

1Skills CLI (Vercel)

npx skills add paperclipai/paperclip --skill paperclip-create-agent -a claude-code

2Manually: put the files in place

~/.claude/skills/paperclip-create-agent/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/paperclip-create-agent/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about paperclip-create-agent

How to install paperclip-create-agent in Claude Code?

Run npx skills add paperclipai/paperclip --skill paperclip-create-agent -a claude-code, then open ~/.claude/skills/paperclip-create-agent/SKILL.md.

What does paperclip-create-agent do?

The skill runs the agent hiring flow in Paperclip: checks permissions, fetches adapter and icon config, compares existing agent setups, assembles the new hire draft, and submits the hire request. When company governance requires board approval, the skill waits for the decision before the hire completes.

What does paperclip-create-agent require to work?

can_create_agents=true permission in the company or board access. On Paperclip Runner it uses search_api and call_api; elsewhere it needs PAPERCLIP_API_URL and PAPERCLIP_API_KEY environment variables.

Source text

SKILL.md · MIT
---
name: paperclip-create-agent
description: >
  Create new agents in Paperclip with governance-aware hiring. Use when you need
  to inspect adapter configuration options, compare existing agent configs,
  draft a new agent prompt/config, and submit a hire request.
---

# 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, keep the current task assigned to yourself
and identify the missing hiring authority. A CEO or manager title does not grant
hiring permission. Do not reassign the task or create an escalation task to bypass
the denial. Use the applicable approval flow when available; otherwise save a
human-input interaction on the current task with `resolverPolicy: "human_only"`
and `continuationPolicy: "wake_assignee"`, then leave it `in_review`. Use the
complete human-input payload in the `paperclip` skill; when the requesting user
owns the decision, address it with their actual `addresseeUserId`. A human answer
does not itself grant permission: recheck authorization before any hire.

## Workflow

### Choose the API transport

On **Paperclip Runner**, use the advertised Paperclip tools. Use `get_task_context`
and `list_agents` for identity and team context, then `search_api` to discover the
configuration, instruction-template, icon, and `agent-hires` endpoints used below.
Call the discovered operations with `call_api`; the server supplies company and
authentication context. Read the returned schemas before drafting the hire.

The shell examples below apply to adapters that receive `PAPERCLIP_API_URL` and
`PAPERCLIP_API_KEY`. Paperclip Runner does not supply those variables. Do not
search workspace files for a server address or credentials to recreate that path.
If `search_api` / `call_api` are unavailable, report that hiring requires the
operator to enable runner API tools for this company. Preserve the proposed hire
in the conversation; do not claim an agent was created or substitute a temporary
subagent for the requested permanent hire.

### 1. Confirm identity and company context

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

### 2. Discover adapter configuration for this Paperclip instance

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

# Then the specific adapter you plan to use, e.g. claude_local:
curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration/claude_local.txt" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
```

### 3. Compare existing agent configurations

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

Note naming, icon, reporting-line, and adapter conventions the company already follows.

### 4. Describe the role

Use a short role paragraph for a new agent: its identity and the responsibility
it owns. The [role examples](references/agent-instruction-templates.md) are
optional starting points; for other roles, use the
[baseline role guide](references/baseline-role-guide.md).

Company-specific instructions supplied by the requester take precedence. Do not
expand a role description into a generic operating manual. The harness supplies
Paperclip coordination, skill discovery, and task lifecycle guidance; repository
instructions and installed skills carry applicable work procedures. Avoid
adding heartbeat pointers, execution contracts, mandatory per-touch comments,
fixed reviewer routes, or catalogs of domain concepts to the hire's instructions.

Keep reporting lines in `reportsTo`, capabilities in `capabilities`, and skills
in `desiredSkills`. Add instruction detail only for a concrete company or role
requirement that those fields, the task, repository instructions, or installed
skills do not already express.

### 5. Discover allowed agent icons

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

### 6. Draft the new hire config

- role / title / name
- icon (required in practice; pick from `/llms/agent-icons.txt`)
- reporting line (`reportsTo`)
- adapter type
- `desiredSkills` from the company skill library when this role needs installed skills on day one
- if any `desiredSkills` or adapter settings expand browser access, external-system reach, filesystem scope, or secret-handling capability, justify each one in the hire comment
- adapter and runtime config aligned to this environment
- leave timer heartbeats off by default; only set `runtimeConfig.heartbeat.enabled=true` with an `intervalSec` when the role genuinely needs scheduled recurring work or the user explicitly asked for it
- if the role may handle private advisories or sensitive disclosures, confirm a confidential workflow exists first (dedicated skill or documented manual process)
- capabilities
- when supplying role instructions from step 4, send them as top-level `instructionsBundle.files["AGENTS.md"]` for managed-bundle adapters. Otherwise use the server default. Do not set `adapterConfig.promptTemplate` or `bootstrapPromptTemplate` for new agents.
- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue

### 7. Review the draft against the quality checklist

Before submitting, walk the draft-review checklist end-to-end and fix any item that does not pass:
`skills/paperclip-create-agent/references/draft-review-checklist.md`

### 8. Submit hire request

```sh
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": "<ceo-agent-id>",
    "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"},
    "instructionsBundle": {"files": {"AGENTS.md": "You are the CTO..."}},
    "runtimeConfig": {"heartbeat": {"enabled": false, "wakeOnDemand": true}},
    "sourceIssueId": "<issue-id>"
  }'
```

### 9. Handle governance state

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

```sh
curl -sS "$PAPERCLIP_API_URL/api/approvals/<approval-id>" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

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

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

```sh
curl -sS -X POST "$PAPERCLIP_API_URL/api/issues/<issue-id>/approvals" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approvalId":"<approval-id>"}'
```

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

```sh
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 the approval resolved the request, or
- comment in markdown with links to the approval and next actions.

## References

- Optional role examples: `skills/paperclip-create-agent/references/agent-instruction-templates.md`
- Individual role templates: `skills/paperclip-create-agent/references/agents/`
- Short role drafting guide: `skills/paperclip-create-agent/references/baseline-role-guide.md`
- Pre-submit draft-review checklist: `skills/paperclip-create-agent/references/draft-review-checklist.md`
- Endpoint payload shapes and full examples: `skills/paperclip-create-agent/references/api-reference.md`

## Harness and runner selection

Choose the underlying harness in `adapterType`, such as `codex_local` or
`claude_local`. New Codex agents use Paperclip Runner automatically on supported
execution targets. New Claude Code agents use Paperclip Runner on Apple Silicon,
Intel Mac, Linux x64 and Linux ARM64 with supported glibc. Unknown or unsupported
targets retain Legacy. Darwin SSH also defaults to Legacy; native execution
requires an explicit runner choice and matching remote assets. The native Claude profile is
`provider: acpx`, `acpxAgent: claude`, with ordinary model `claude-opus-5-5`.
Explicit models and existing saved runners remain intact. The saved response
may therefore have `adapterType: paperclip_runner` and a resolved provider;
use that returned configuration for later reads and edits.

The optional creation field `runner` accepts `auto`, `paperclip`, or `legacy`.
Use `legacy` when the user needs CLI settings the native runtime cannot honor.
For Claude this includes Chrome, custom commands/state paths, warm-process
controls, confinement and turn limits. Native Claude uses existing API-key and
subscription connections. Its configured effort requires provider acknowledgment. Setup and authentication errors never silently change runners.
Existing agents keep their saved execution after unrelated edits. An approved
hire uses the configuration reviewed by the board. `inheritRuntimeFrom: caller`
keeps its existing runtime inheritance and credential restrictions.

CLI equivalents: `paperclipai agent create --runner legacy --payload-json ...`
and `paperclipai agent hire --runner legacy --payload-json ...`.

© paperclipai · MIT · paperclipai/paperclip

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set7

More in the catalog

Project sponsors

Companies that keep this analytics open