paperclip-create-agent

Paperclip 创建代理技能

当被要求招聘/创建代理时使用此技能。

前置条件

Paperclip 必须已安装并运行。如果服务器未启动或 PAPERCLIP_API_URL 不可达，请先阅读 skills/paperclip/references/setup-installation.md。

你需要具备以下条件之一：

• 董事会访问权限，或
• 在你的公司中拥有代理权限 can_create_agents=true

如果你没有此权限，请上报给你的 CEO 或董事会。

工作流程

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"

# 然后是你计划使用的特定适配器，例如 claude_local：
curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration/claude_local.txt" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

3. 比较现有代理配置

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

注意公司已遵循的命名、图标、汇报线和适配器约定。

4. 选择指令来源（必需）

这是影响招聘质量的最重要决策。请选择且仅选择一条路径：

• 精确模板 — 角色与模板索引中的条目匹配。使用 references/agents/ 下的对应文件作为起点。
• 近似模板 — 没有精确匹配，但现有模板接近（例如，从 coder.md 改编的“后端工程师”招聘，或从 uxdesigner.md 改编的“内容设计师”）。复制最接近的模板并进行有意的调整：重命名角色、重写角色章程、交换领域视角、删除不合适的部分。
• 通用后备 — 没有接近的模板。使用基线角色指南从头构建新的 AGENTS.md，为特定角色填写每个推荐部分。

模板索引及使用时机指南：
skills/paperclip-create-agent/references/agent-instruction-templates.md

无模板招聘的通用后备：
skills/paperclip-create-agent/references/baseline-role-guide.md

在你的招聘请求评论中说明你选择了哪条路径，以便董事会了解推理过程。

5. 发现允许的代理图标

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
• 如果角色可能处理私人建议或敏感披露，请先确认存在保密工作流程（专用技能或记录的手动流程）
• 能力
• 对于支持托管指令包的适配器，使用托管指令包（AGENTS.md）；避免使用持久的 promptTemplate 配置
• 对于编码或执行代理，包含 Paperclip 执行契约：在同一心跳中开始可操作的工作；除非要求规划，否则不要止步于计划；留下持久的进展并明确下一步行动；对长时间或并行的委派工作使用子问题而非轮询；标记受阻的工作并注明负责人/行动；尊重预算、暂停/取消、审批关卡和公司边界
• 从步骤 4 构建的指令文本，如 AGENTS.md；对于本地托管包适配器，将其作为顶级 instructionsBundle.files["AGENTS.md"] 发送。不要为新代理设置 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