Skill vs. Playbook Doc: Decision Guide
Date: 2026-03-11
Owner: Engineering / AI Systems
Related rule: .cursor/rules/skill-vs-playbook.mdc
Why this matters
Before creating a Cursor skill (SKILL.md), ask whether the thing you’re building is actually a skill — or whether it’s a playbook doc, a reference file bundled inside a skill, or just an inline instruction. Creating unnecessary skill files wastes context window space and makes the agent scan a larger available_skills list.
The core distinction
A Cursor skill is designed to be invoked — either by a user trigger phrase matching the description, or by an orchestrating skill explicitly reading it. Its body is loaded into the agent’s context window at execution time and it executes a workflow.
A playbook doc is designed to be referenced — another skill or a human reads it to extract standards, data, or templates. It is not itself invoked; it does not execute anything.
USER TRIGGER
↓
SKILL.md ← orchestration, decisions, tool calls, produces output
↓
PLAYBOOK DOC / references/ ← standards, data, templates, read patterns
↓
MCP TOOLS ← actual API calls
Step 0 — Check for an existing skill first
Before running any other gate, scan .cursor/skills/ for an existing skill that already solves the same problem or has significant overlap. If one exists, tell the user what you found and ask: “Do you want to update the existing skill, merge this capability into it, or create a new separate skill?” Do not create a new skill until the user has confirmed a net-new one is needed and explained why the existing skill is insufficient.
Decision criteria
Create a SKILL.md when
| Signal | Why |
|---|---|
| A human would directly trigger this (“run X for [client]”, “create Y”, “audit Z”) | The description field is the triggering mechanism; it needs to match user phrases |
| It executes a workflow — makes decisions, calls tools, produces an output | Skills carry instructions the agent follows at execution time |
| It would be too large or complex to inline in a parent skill, but must be in context when running | Progressive disclosure: SKILL.md body is loaded on trigger |
| Multiple orchestrators will call it independently (each reads and follows it) | Justifies a standalone file rather than a references/ section inside one skill |
| It has side effects — writes to Linear, vault, Drive, Slack | Side-effect workflows need clear, scoped boundaries |
| You can write a meaningful test case for it — it produces a verifiable output | From the skill-creator guide: skills with no verifiable output are likely not skills |
Create a playbook doc instead when
| Signal | Why |
|---|---|
| It’s reference data or standards — a mapping, naming conventions, a template, a table of allowed values | Not a workflow; the agent reads it and extracts data |
| A human also needs to read and edit it directly | Playbook = team-maintained documentation, not agent instructions |
| It’s the single source of truth that multiple skills point to but never replace | e.g., client-vault-mapping.md, linear-mcp-tool-map.md |
| It describes what (rules, formats, allowed values) not how (decision steps, tool calls) | Standards and data belong in playbook; orchestration belongs in skills |
It has no allowed-tools and no workflow steps | If it has nothing to execute, it’s a doc, not a skill |
| It’s static lookup data that an agent reads in one step | A lookup table does not warrant a skill file; add it to an existing doc |
Sub-skill vs. bundled reference
When a skill needs helper instructions that another skill also uses, you have two options beyond “create a new skill”:
references/file bundled inside the skill — load only when the parent skill runs; keeps it out of the globalavailable_skillslist. Best for read patterns, output format templates, or step-by-step procedures used only within that skill family.- Inline in the parent skill — if the helper logic is short (< ~30 lines) and used in only one place.
Only elevate to a standalone skill if the helper has its own user-facing trigger or is called by three or more distinct orchestrators with no other shared home.
Diagnostic questions (run before creating a new skill)
- Can a human trigger this directly? If no — it has no user-facing trigger — it’s probably not a standalone skill.
- Does it call tools or produce an output? If it’s purely a lookup or a list of rules, it’s a playbook doc.
- Can I write a test case for it? If you can’t imagine a pass/fail test, it’s likely reference material.
- Is the content static data or dynamic execution? Static data → playbook. Dynamic execution → skill.
- Who else uses it? One consumer → inline or
references/. Multiple consumers with own triggers → skill. Multiple consumers, no trigger → shared playbook doc orreferences/file.
Real examples from this codebase
| Artifact | Classification | Reason |
|---|---|---|
client-engagement-kickoff/SKILL.md | Skill | User-triggered (“kick off new client”), executes multi-step workflow, writes to knowledge/Linear/Drive |
linear-status-sync/SKILL.md | Skill | User-triggered (“sync ticket statuses”), propagates state changes with confirms |
linear-project-milestone-health/SKILL.md | Skill | User-triggered (“run project audit for [client]”), computes health output, embedded in EP audit + weekly kick-off |
standards/04-prompts/client-vault-mapping.md | Playbook doc | Static lookup: client name → vault path + Linear team. Skills read it; no workflow |
standards/03-knowledge/engineering/setup/linear-mcp-tool-map.md | Playbook doc | Reference table: which MCP tools each skill uses. No execution |
| Canonical Initiative/Project naming map | Playbook doc | Static naming conventions. Skills read it to create/match idempotently |
| ”linear-resolve-team” (previously proposed skill) | Not a skill — inline step | One-line lookup (client-vault-mapping + list_teams). No independent trigger. Inline in each consuming skill |
| ”linear-read-projects-milestones” (previously proposed skill) | Not a skill — references/ file | Read-only pattern with no independent trigger; used as a bundled references/ file inside linear-project-milestone-health |
| ”linear-canonical-mapping” (previously proposed skill) | Not a skill — playbook doc | Pure reference data. Already belongs in the playbook canonical mapping doc (plan §3.2) |
linear-client-repo-pr-bridge/SKILL.md | Skill | User-triggered (“tie this PR to Linear,” “ticket the open PR”); runs Linear MCP + gh on client/app repos; parent/child issues, cycles, verified assignees (list_users), PR comment; bundled references/npm-lockfile-pr-checklist.md for install/CI |
npm lockfile / npm ci checklist alone | references/ inside linear-client-repo-pr-bridge (and pointer from fix-pr) | Short deterministic checklist; not its own skill unless it gains a standalone trigger |
Summary rule of thumb
If you can replace “create a SKILL.md” with “add a section to an existing playbook doc or bundle a
references/file inside the parent skill” without losing anything, do that instead.
Skills are for execution. Docs are for reference.
References
- Cursor rule:
.cursor/rules/skill-vs-playbook.mdc - Skill authoring guide:
.cursor/skills/anthropic-skills/skills/skill-creator/SKILL.md - Bite-sized Linear project skills plan:
.cursor/plans/bite-sized_linear_project_skills_82ec3741.plan.md