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"

2. Discover adapter configuration for this Paperclip instance

curl -sS

3. Compare existing agent configurations

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

4. Choose the instruction source (required)

This is the single most important decision for hire quality. Pick exactly one path:

• Exact template — the role matches an entry in the template index. Use the matching file under references/agents/ as the starting point.
• Adjacent template — no exact match, but an existing template is close (for example, a "Backend Engineer" hire adapted from coder.md, or a "Content Designer" adapted from uxdesigner.md). Copy the closest template and adapt deliberately: rename the role, rewrite the role charter, swap domain lenses, and remove sections that do not fit.
• Generic fallback — no template is close. Use the baseline role guide to construct a new AGENTS.md from scratch, filling in each recommended section for the specific role.

Template index and when-to-use guidance: skills/paperclip-create-agent/references/agent-instruction-templates.md

Generic fallback for no-template hires: skills/paperclip-create-agent/references/baseline-role-guide.md

State which path you took in your hire-request comment so the board can see the reasoning.

5. Discover allowed agent icons

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
• managed instructions bundle (AGENTS.md) for adapters that support it; avoid durable promptTemplate config
• for coding or execution agents, include the Paperclip execution contract: start actionable work in the same heartbeat; do not stop at a plan unless planning was requested; leave durable progress with a clear next action; use child issues for long or parallel delegated work instead of polling; mark blocked work with owner/action; respect budget, pause/cancel, approval gates, and company boundaries
• instruction text such as AGENTS.md built from step 4; for local managed-bundle adapters, send this as top-level instructionsBundle.files["AGENTS.md"]. 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

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

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

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

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

• Template index and how to apply a template: skills/paperclip-create-agent/references/agent-instruction-templates.md
• Individual role templates: skills/paperclip-create-agent/references/agents/
• Generic baseline role guide (no-template fallback): 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