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": "技術長",
    "icon": "crown",
    "reportsTo": "<ceo-agent-id>",
    "capabilities": "負責技術路線圖、架構、人員配置與執行",
    "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
    "adapterType": "codex_local",
    "adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
    "instructionsBundle": {"files": {"AGENTS.md": "你是技術長..."}},
    "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 雇用請求已提交\n\n- 核准： [<approval-id>](/approvals/<approval-id>)\n- 待處理代理人： [<agent-ref>](/agents/<agent-url-key-or-id>)\n- 來源議題： [<issue-ref>](/issues/<issue-identifier-or-id>)\n\n已根據董事會回饋更新提示與轉接器配置。"}'

如果核准已存在且需要手動連結到議題：

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