aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add company skill assignment to agent create and hire flows

Browse Source 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
dotta
2026-03-18 13:18:48 -05:00
parent 099c37c4b4
commit 480174367d
12 changed files with 699 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
skills/paperclip-create-agent/SKILL.md
View File

@@ -61,6 +61,7 @@ curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
- icon (required in practice; use one from `/llms/agent-icons.txt`)
- reporting line (`reportsTo`)
- adapter type
- optional `desiredSkills` from the company skill library when this role needs installed skills on day one
- adapter and runtime config aligned to this environment
- capabilities
- run prompt in adapter config (`promptTemplate` where applicable)
@@ -79,6 +80,7 @@ curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/agent-h
"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"},
"runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}},
@@ -128,6 +130,7 @@ For each linked issue, either:
Before sending a hire request:
- if the role needs skills, make sure they already exist in the company library or install them first using the Paperclip company-skills workflow
- 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.

12
skills/paperclip-create-agent/references/api-reference.md
View File

@@ -6,8 +6,12 @@
- `GET /llms/agent-configuration/:adapterType.txt`
- `GET /llms/agent-icons.txt`
- `GET /api/companies/:companyId/agent-configurations`
- `GET /api/companies/:companyId/skills`
- `POST /api/companies/:companyId/skills/import`
- `GET /api/agents/:agentId/configuration`
- `POST /api/agents/:agentId/skills/sync`
- `POST /api/companies/:companyId/agent-hires`
- `POST /api/companies/:companyId/agents`
- `GET /api/agents/:agentId/config-revisions`
- `POST /api/agents/:agentId/config-revisions/:revisionId/rollback`
- `POST /api/issues/:issueId/approvals`
@@ -34,6 +38,7 @@ Request body matches agent create shape:
"icon": "crown",
"reportsTo": "uuid-or-null",
"capabilities": "Owns architecture and engineering execution",
"desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
"adapterType": "claude_local",
"adapterConfig": {
"cwd": "/absolute/path",
@@ -64,13 +69,18 @@ Response:
"approval": {
"id": "uuid",
"type": "hire_agent",
"status": "pending"
"status": "pending",
"payload": {
"desiredSkills": ["vercel-labs/agent-browser/agent-browser"]
}
}
}
```
If company setting disables required approval, `approval` is `null` and the agent is created as `idle`.
`desiredSkills` accepts company skill ids, canonical keys, or a unique slug. The server resolves and stores canonical company skill keys.
## Approval Lifecycle
Statuses:

15
skills/paperclip/SKILL.md
View File

@@ -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` |

151
skills/paperclip/references/company-skills.md Normal file
View File

@@ -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.