151 lines
4.5 KiB
Markdown
151 lines
4.5 KiB
Markdown
# 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.
|