paperclip-create-agent

Paperclip 创建 Agent 技能

当有人要求你聘用／创建 Agent 时，使用此技能。

前提条件

你需要具备以下任一权限：

• 看板访问权限，或
• 在你的公司中拥有 can_create_agents=true 的 Agent 权限

如果你没有此权限，请让当前任务继续分配给自己，并指出缺少聘用授权。CEO 或经理头衔并不代表拥有聘用权限。不要重新分配任务，也不要创建升级任务来绕过拒绝。如果有适用的审批流程，请使用该流程；否则，在当前任务上保存一条人工输入交互，并设置 resolverPolicy: "human_only" 和 continuationPolicy: "wake_assignee"，然后将任务留在 in_review 状态。请使用 paperclip 技能中的完整人工输入负载；如果作出决定的是提出请求的用户，请使用其实际的 addresseeUserId 联系对方。人工答复本身并不会授予权限：任何聘用操作之前都要重新核实授权。

工作流

选择 API 传输方式

在 Paperclip Runner 上，使用其提供的 Paperclip 工具。使用 get_task_context 和 list_agents 获取身份和团队上下文，然后使用 search_api 查找下文将用到的配置、指令模板、图标和 agent-hires 端点。使用 call_api 调用找到的操作；服务器会提供公司和身份验证上下文。在起草聘用方案之前，请先阅读返回的架构。

以下 shell 示例适用于可接收 PAPERCLIP_API_URL 和 PAPERCLIP_API_KEY 的适配器。Paperclip Runner 不会提供这些变量。不要搜索工作区文件来查找服务器地址或凭据，以此重建该路径。如果无法使用 search_api／call_api，请说明公司需要由操作员启用 Runner API 工具才能进行聘用。在对话中保留拟议的聘用方案；不要声称已创建 Agent，也不要用临时子 Agent 替代所请求的长期聘用。

1. 确认身份和公司上下文

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

2. 查找此 Paperclip 实例的适配器配置

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. 比较现有 Agent 配置

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

注意公司已有的命名、图标、汇报关系和适配器惯例。

4. 描述角色

用一段简短的角色描述介绍新 Agent 的身份及其负责的工作。角色示例可作为可选起点；对于其他角色，请使用基准角色指南。

请求者提供的公司特定指令优先。不要将角色描述扩展成通用操作手册。运行环境会提供 Paperclip 协调、技能发现和任务生命周期指导；仓库指令和已安装的技能则规定适用的工作流程。避免在聘用说明中添加心跳指引、执行契约、每次交互都必须发表评论的要求、固定的审核人路径或领域概念目录。

将汇报关系写入 reportsTo，将能力写入 capabilities，并将技能写入 desiredSkills。只有当某项具体的公司或角色要求未由这些字段、任务、仓库指令或已安装技能表达时，才添加指令细节。

5. 查找允许使用的 Agent 图标

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

6. 起草新员工配置

• 角色 / 职位 / 名称
• 图标（实际上必填；从 /llms/agent-icons.txt 中选择）
• 汇报对象（reportsTo）
• 适配器类型
• 当此角色需要在第一天安装技能时，从公司技能库中选择 desiredSkills
• 如果任何 desiredSkills 或适配器设置会扩大浏览器访问权限、外部系统访问范围、文件系统范围或机密处理能力，请在聘用说明中逐项说明理由
• 适配器和运行时配置应与此环境相匹配
• 默认关闭定时心跳；只有当该角色确实需要按计划执行周期性工作，或用户明确提出要求时，才设置 runtimeConfig.heartbeat.enabled=true 和 intervalSec
• 如果该角色可能处理私密通告或敏感信息披露，请先确认存在保密工作流（专用技能或有文档记录的手动流程）
• 能力
• 如果要提供第 4 步中的角色指令，对于托管捆绑包适配器，请将其作为顶层的 instructionsBundle.files["AGENTS.md"] 发送。否则使用服务默认值。不要为新 Agent 设置 adapterConfig.promptTemplate 或 bootstrapPromptTemplate。
• 来源问题关联（当此聘用请求来自某个问题时，使用 sourceIssueId 或 sourceIssueIds）

7. 根据质量检查清单审核草稿

提交前，逐项完成草稿审核检查清单，并修复所有未通过的项目： skills/paperclip-create-agent/references/draft-review-checklist.md

8. 提交聘用请求

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. 处理治理状态

• 如果响应中包含 approval，则聘用状态为 pending_approval
• 在审批讨论串中跟进并参与讨论
• 董事会批准后，你将收到 PAPERCLIP_APPROVAL_ID 并被唤醒；读取关联问题并完成后续处理或评论

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."}'

如果审批已存在，且需要手动关联到问题：

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>"}'

审批通过后，执行以下后续处理流程：

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"

对于每个关联问题，请执行以下操作之一：

• 如果审批已解决请求，则关闭问题；或者
• 以 Markdown 格式发表评论，并附上审批链接和后续操作。

参考资料

• 可选角色示例：skills/paperclip-create-agent/references/agent-instruction-templates.md
• 单个角色模板：skills/paperclip-create-agent/references/agents/
• 简短角色起草指南：skills/paperclip-create-agent/references/baseline-role-guide.md
• 提交前草稿审核检查清单：skills/paperclip-create-agent/references/draft-review-checklist.md
• 端点负载结构和完整示例：skills/paperclip-create-agent/references/api-reference.md

框架与运行器选择

在 adapterType 中选择底层框架，例如 codex_local 或 claude_local。在受支持的执行目标上，新建的 Codex Agent 会自动使用 Paperclip Runner。新建的 Claude Code Agent 会在 Apple Silicon、Intel Mac、Linux x64 和采用受支持 glibc 的 Linux ARM64 上使用 Paperclip Runner。对于未知或不受支持的目标，则保留 Legacy。Darwin SSH 也默认使用 Legacy；原生执行需要明确选择运行器，并提供匹配的远程资产。原生 Claude 配置为 provider: acpx、acpxAgent: claude，普通模型为 claude-opus-5-5。 明确指定的模型和已保存的运行器会保持不变。因此，保存后的响应可能包含 adapterType: paperclip_runner 和已解析的 provider；后续读取和编辑时请使用返回的配置。

可选的创建字段 runner 接受 auto、paperclip 或 legacy。 当用户需要原生运行时无法支持的 CLI 设置时，请使用 legacy。 对于 Claude，这包括 Chrome、自定义命令和状态路径、热进程控制、隔离和轮次限制。原生 Claude 使用现有的 API 密钥和订阅连接。其配置的推理力度需要 provider 确认。设置和身份验证错误绝不会导致运行器静默切换。 对现有 Agent 进行无关编辑时，其已保存的执行方式会保持不变。经批准的招聘会使用董事会审阅过的配置。inheritRuntimeFrom: caller 会保留现有的运行时继承和凭证限制。

CLI 对应命令：paperclipai agent create --runner legacy --payload-json ... 和 paperclipai agent hire --runner legacy --payload-json ...。