Skills Contract — V1

Skills are executor playbooks referenced by name in a project's .claude/project.yml. Source file: spec/v1/skills/README.md.

Core skills (V1)

Skill name	Description	Phase
core:dev-task	Implements a single Linear issue end-to-end: code, tests, PR	P0
core:write-feature	Writes a feature spec + design doc from a Linear issue	P1
core:write-story	Decomposes a feature spec into Linear user stories	P1
core:qa-task	Runs QA against a PR: test plan, findings, screenshots	P1 basic / P3 full
core:retrospective	Auto-generates a retrospective after a feature is Done	P3

How skills are resolved

Before launching an executor, the control plane's skill resolver copies (or symlinks) the referenced skills into the worktree. The playbook lives at packages/skills-core/<skill>/SKILL.md in this repo.

Custom project skills

Projects can also define project-scoped skills. Reference them with the project: prefix:

skills:
  - core:dev-task
  - project:my-custom-skill

Project skills live in the project repo at .claude/skills/my-custom-skill/.

Raw source (spec/v1/skills/README.md)

# Core Skills (versioned)

Each core skill has a corresponding markdown doc in this directory. The doc describes the skill's purpose, input/output contract, and prompt structure. The actual playbook (the prompt content the executor loads) lives in `packages/skills-core/<skill>/SKILL.md`.

| Skill | Doc | Implementation | Phase |
|---|---|---|---|
| `core:dev-task` | (TBD) | `packages/skills-core/dev-task/` | P0 |
| `core:write-feature` | (TBD) | `packages/skills-core/write-feature/` | P1 |
| `core:write-story` | (TBD) | `packages/skills-core/write-story/` | P1 |
| `core:qa-task` | (TBD) | `packages/skills-core/qa-task/` | P1 basic, P3 full |
| `core:retrospective` | (TBD) | `packages/skills-core/retrospective/` | P3 |

Projects reference skills by name in their `.claude/project.yml`:

```yaml
skills:
  - core:dev-task
  - core:write-feature
  - project:my-custom-skill
```

The control plane's skill resolver copies (or symlinks) the referenced skills into the worktree before launching the executor.