Add company skill assignment to agent create and hire flows

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-20 20:40:38 +09:00 · 2026-03-18 13:18:48 -05:00 · 2026-03-18 13:18:48 -05:00 · 480174367d
commit 480174367d
parent 099c37c4b4
12 changed files with 699 additions and 35 deletions
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@ -124,6 +124,17 @@ Access control:

 4. After OpenClaw submits the join request, monitor approvals and continue onboarding (approval + API key claim + skill install).

+## Company Skills Workflow
+
+Authorized managers can install company skills independently of hiring, then assign or remove those skills on agents.
+
+- Install and inspect company skills with the company skills API.
+- Assign skills to existing agents with `POST /api/agents/{agentId}/skills/sync`.
+- When hiring or creating an agent, include optional `desiredSkills` so the same assignment model is applied on day one.
+
+Keep the detailed workflow out of this hot-path file. For concrete commands and examples, read:
+`skills/paperclip/references/company-skills.md`
+
 ## Critical Rules

 - **Always checkout** before working. Never PATCH to `in_progress` manually.
@ -254,6 +265,10 @@ PATCH /api/agents/{agentId}/instructions-path
 | Set instructions path                 | `PATCH /api/agents/:agentId/instructions-path`                                             |
 | Release task                          | `POST /api/issues/:issueId/release`                                                        |
 | List agents                           | `GET /api/companies/:companyId/agents`                                                     |
+| List company skills                   | `GET /api/companies/:companyId/skills`                                                     |
+| Import company skills                 | `POST /api/companies/:companyId/skills/import`                                             |
+| Scan project workspaces for skills    | `POST /api/companies/:companyId/skills/scan-projects`                                      |
+| Sync agent desired skills             | `POST /api/agents/:agentId/skills/sync`                                                    |
 | Dashboard                             | `GET /api/companies/:companyId/dashboard`                                                  |
 | Search issues                         | `GET /api/companies/:companyId/issues?q=search+term`                                       |
 | Upload attachment (multipart, field=file) | `POST /api/companies/:companyId/issues/:issueId/attachments`                           |
--- a/skills/paperclip/references/company-skills.md
+++ b/skills/paperclip/references/company-skills.md
@ -0,0 +1,151 @@
+# Company Skills Workflow
+
+Use this reference when a board user, CEO, or manager asks you to find a skill, install it into the company library, or assign it to an agent.
+
+## What Exists
+
+- Company skill library: install, inspect, update, and read imported skills for the whole company.
+- Agent skill assignment: add or remove company skills on an existing agent.
+- Hire/create composition: pass `desiredSkills` when creating or hiring an agent so the same assignment model applies immediately.
+
+The canonical model is:
+
+1. install the skill into the company
+2. assign the company skill to the agent
+3. optionally do step 2 during hire/create with `desiredSkills`
+
+## Permission Model
+
+- Company skill reads: any same-company actor
+- Company skill mutations: board, CEO, or an agent with the effective `agents:create` capability
+- Agent skill assignment: same permission model as updating that agent
+
+## Core Endpoints
+
+- `GET /api/companies/:companyId/skills`
+- `GET /api/companies/:companyId/skills/:skillId`
+- `POST /api/companies/:companyId/skills/import`
+- `POST /api/companies/:companyId/skills/scan-projects`
+- `POST /api/companies/:companyId/skills/:skillId/install-update`
+- `GET /api/agents/:agentId/skills`
+- `POST /api/agents/:agentId/skills/sync`
+- `POST /api/companies/:companyId/agent-hires`
+- `POST /api/companies/:companyId/agents`
+
+## Install A Skill Into The Company
+
+Import from GitHub, a local path, or a `skills.sh`-style source string:
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/import" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "https://github.com/vercel-labs/agent-browser"
+  }'
+```
+
+You can also use a source string such as:
+
+- `npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser`
+- `vercel-labs/agent-browser/agent-browser`
+
+If the task is to discover skills from the company project workspaces first:
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/scan-projects" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## Inspect What Was Installed
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+Read the skill entry and its `SKILL.md`:
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/<skill-id>" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/<skill-id>/files?path=SKILL.md" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+## Assign Skills To An Existing Agent
+
+`desiredSkills` accepts:
+
+- exact company skill key
+- exact company skill id
+- exact slug when it is unique in the company
+
+The server persists canonical company skill keys.
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/agents/<agent-id>/skills/sync" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "desiredSkills": [
+      "vercel-labs/agent-browser/agent-browser"
+    ]
+  }'
+```
+
+If you need the current state first:
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/agents/<agent-id>/skills" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+## Include Skills During Hire Or Create
+
+Use the same company skill keys or references in `desiredSkills` when hiring or creating an agent:
+
+```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": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+For direct create without approval:
+
+```sh
+curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agents" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+## Notes
+
+- Built-in Paperclip runtime skills are still added automatically when required by the adapter.
+- If a reference is missing or ambiguous, the API returns `422`.
+- Prefer linking back to the relevant issue, approval, and agent when you comment about skill changes.