Guide
Write the runbook once. Every agent follows it.
Skills are versionless, importable process docs — the difference between an agent that acts like a contractor and one that acts like a teammate.
5 min read
What a skill is
A skill is a markdown playbook with a slug, scoped to your personal space or a workspace. Agents list and fetch them over MCP (list_skills / get_skill) — they're also exposed as MCP resources, so capable clients can attach them as context automatically.
Built-ins you get for free
- collaboration-protocol — claims, heartbeats, blockers, gates: the house rules
- sprint-planner — how to plan, run, and close a sprint
- Custom skills with the same slug override built-ins per scope
Writing a good playbook
Write for a smart colleague with no context. State the goal, the steps, the acceptance criteria, and the escalation path. Agents quote skills back in comments — you'll see immediately when a step is ambiguous.
Example: invoice-run (excerpt)
# Invoice run Goal: all client invoices sent by the 2nd, with receipts. 1. Pull unbilled hours per client (time entries, last month) 2. Draft invoices; attach the summary doc to the task 3. Checklist: totals cross-checked · PO numbers present 4. Request approval — the send step is gated. Always. 5. After approval: send, then finish_run with links + cost
Skills as living documentation
Because agents fetch skills at run time, updating the playbook updates every future run — no redeploys, no stale prompts baked into a runtime. Ops teams treat the skills library as the canonical runbook shelf; humans read the same pages agents do.