skills to all

2026-03-10 11:24:50 -04:00
parent 95b2c8da01
commit 2be39885f4
29 changed files with 3264 additions and 47 deletions
--- a/skills/paperclip-create-agent/SKILL.md
+++ b/skills/paperclip-create-agent/SKILL.md
@@ -0,0 +1,139 @@
+---
+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, escalate to your CEO or board.
+
+## Workflow
+
+1. Confirm identity and company context.
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/agents/me" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+2. Discover available adapter configuration docs for this Paperclip instance.
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration.txt" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+3. Read adapter-specific docs (example: `claude_local`).
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/llms/agent-configuration/claude_local.txt" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+4. Compare existing agent configurations in your company.
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-configurations" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+5. Discover allowed agent icons and pick one that matches the role.
+
+```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; use one from `/llms/agent-icons.txt`)
+- reporting line (`reportsTo`)
+- adapter type
+- adapter and runtime config aligned to this environment
+- capabilities
+- run prompt in adapter config (`promptTemplate` where applicable)
+- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
+
+7. 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",
+    "adapterType": "codex_local",
+    "adapterConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
+    "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}},
+    "sourceIssueId": "<issue-id>"
+  }'
+```
+
+8. Handle governance state:
+- if response has `approval`, hire is `pending_approval`
+- monitor and discuss on 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 approval resolved the request, or
+- comment in markdown with links to the approval and next actions.
+
+## Quality Bar
+
+Before sending a hire request:
+
+- Reuse proven config patterns from related agents where possible.
+- Set a concrete `icon` from `/llms/agent-icons.txt` so the new hire is identifiable in org and task views.
+- Avoid secrets in plain text unless required by adapter behavior.
+- Ensure reporting line is correct and in-company.
+- Ensure prompt is role-specific and operationally scoped.
+- If board requests revision, update payload and resubmit through approval flow.
+
+For endpoint payload shapes and full examples, read:
+`skills/paperclip-create-agent/references/api-reference.md`
--- a/skills/paperclip-create-agent/references/api-reference.md
+++ b/skills/paperclip-create-agent/references/api-reference.md
@@ -0,0 +1,95 @@
+# Paperclip Create Agent API Reference
+
+## Core Endpoints
+
+- `GET /llms/agent-configuration.txt`
+- `GET /llms/agent-configuration/:adapterType.txt`
+- `GET /llms/agent-icons.txt`
+- `GET /api/companies/:companyId/agent-configurations`
+- `GET /api/agents/:agentId/configuration`
+- `POST /api/companies/:companyId/agent-hires`
+- `GET /api/agents/:agentId/config-revisions`
+- `POST /api/agents/:agentId/config-revisions/:revisionId/rollback`
+- `POST /api/issues/:issueId/approvals`
+- `GET /api/approvals/:approvalId/issues`
+
+Approval collaboration:
+
+- `GET /api/approvals/:approvalId`
+- `POST /api/approvals/:approvalId/request-revision` (board)
+- `POST /api/approvals/:approvalId/resubmit`
+- `GET /api/approvals/:approvalId/comments`
+- `POST /api/approvals/:approvalId/comments`
+- `GET /api/approvals/:approvalId/issues`
+
+## `POST /api/companies/:companyId/agent-hires`
+
+Request body matches agent create shape:
+
+```json
+{
+  "name": "CTO",
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "uuid-or-null",
+  "capabilities": "Owns architecture and engineering execution",
+  "adapterType": "claude_local",
+  "adapterConfig": {
+    "cwd": "/absolute/path",
+    "model": "claude-sonnet-4-5-20250929",
+    "promptTemplate": "You are CTO..."
+  },
+  "runtimeConfig": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalSec": 300,
+      "wakeOnDemand": true
+    }
+  },
+  "budgetMonthlyCents": 0,
+  "sourceIssueId": "uuid-or-null",
+  "sourceIssueIds": ["uuid-1", "uuid-2"]
+}
+```
+
+Response:
+
+```json
+{
+  "agent": {
+    "id": "uuid",
+    "status": "pending_approval"
+  },
+  "approval": {
+    "id": "uuid",
+    "type": "hire_agent",
+    "status": "pending"
+  }
+}
+```
+
+If company setting disables required approval, `approval` is `null` and the agent is created as `idle`.
+
+## Approval Lifecycle
+
+Statuses:
+
+- `pending`
+- `revision_requested`
+- `approved`
+- `rejected`
+- `cancelled`
+
+For hire approvals:
+
+- approved: linked agent transitions `pending_approval -> idle`
+- rejected: linked agent is terminated
+
+## Safety Notes
+
+- Config read APIs redact obvious secrets.
+- `pending_approval` agents cannot run heartbeats, receive assignments, or create keys.
+- All actions are logged in activity for auditability.
+- Use markdown in issue/approval comments and include links to approval, agent, and source issue.
+- After approval resolution, requester may be woken with `PAPERCLIP_APPROVAL_ID` and should reconcile linked issues.