paperclip/skills/paperclip/references/company-skills.md

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:

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:

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

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:

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.

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:

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:

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:

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.