Immutable. This exact content is served forever at /api/v1/blob/cc321e0704bc1b2a.
---
name: book-to-skill
description: 'Use when the user names one book, course, paper, or source document and asks to distill it into a reusable skill. Classifies the source as procedure or reference, writes an attributed SKILL.md, and proves its routing. Not for a folder of sources — use map-corpus.'
---
# Book to skill
## Contract
| Field | Bound contract |
|---|---|
| Trigger | The user names one book, course, paper, or comparable single source document and asks to distill it into a reusable skill. |
| Authority | Reversible local write. Writes only the chosen target skill directory (SKILL.md and optional references/). Rollback is deleting that directory. No source file is mutated or copied wholesale. |
| Side effect | Creates files under the chosen target directory only; never copies the source document into the skill. |
| Done | A SKILL.md that parses as YAML, carries an attribution line, passes four validation checks, and routes correctly on at least two positive and two negative probe prompts. |
## Inputs
- The named source document, accessible as a file the agent can open. A document the agent cannot open stops the run.
- Optional: a write target directory, defaulting to `.claude/skills/<name>/`.
- A folder of multiple sources is out of scope; that belongs to corpus mapping, not this skill.
## Procedure
1. **Read the source.** List its chapters, top-level headings, or sections, whichever structure the document provides. Show one line per unit with its heading slug where one exists. Done when: an inventory covering every top-level unit is shown.
2. **Classify.** Ask whether three or more ordered actions can be named, each with a checkable done-state. Three or more is **procedure** (a sequence the agent can follow). Fewer is **reference** (distinctions and rules consulted on demand). If both are present, use a procedure spine with judgment material in `references/`. Done when: the classification is stated with the three actions named, or with the statement that fewer than three exist.
3. **Extract into four buckets.** Sort what you read into coined terms and leading words; constraints and prohibitions; procedures with their completion criteria; and deep material destined for `references/`. Done when: every inventoried unit has contributed to a bucket or is marked out of scope for the skill.
4. **Name it.** Kebab-case matching `^[a-z0-9]+(-[a-z0-9]+)*$`, at most 64 characters, identical to the directory name. Done when: the name matches the directory to be written to.
5. **Write the frontmatter.** `description` at most 1024 characters, front-loaded, one trigger per genuinely distinct branch, phrased positively. Redirect rather than forbid: "for X, use skill Z" rather than "do not use for X". Done when: the `description` parses as single-quoted YAML and is within the limit.
6. **Write the body in the shape its classification selects.** Include one attribution line naming title, author, and year. Paraphrase throughout; quote only a coined term or named law where the exact phrasing is the idea. The two shapes:
- Procedure shape:
```
# {Skill name}
{One-paragraph attribution: title, author, year.}
## When to use
{One trigger per branch, positively phrased.}
## Steps
1. {Action} — done when {checkable condition}
2. {Action} — done when {checkable condition}
## Rules
- {Constraint or guardrail}
```
- Reference shape:
```
# {Skill name}
{One-paragraph attribution: title, author, year.}
## When to use
{One trigger per branch, positively phrased.}
## Reference
{Definitions, distinctions, or judgment material consulted on demand. No ordered steps.}
## Rules
- {Constraint or guardrail}
```
- A source with both gets the procedure shape with judgment material in `references/`. Every step ends on a checkable done condition; a reference shape carries no steps. The frontmatter `description` is the only place the trigger is worded for dispatch; the body restates the when as prose but does not re-word the trigger for dispatch. Done when: the body follows its shape and carries the attribution.
7. **Disclose.** Material only some branches reach moves to `references/<topic>.md`, linked one level deep from the body. Keep the body under 500 lines. Done when: branch-specific material lives behind a pointer and the body line count is under the cap.
8. **Validate.** Check four conditions: `name` equals the directory name; the frontmatter parses as YAML; `description` is within 1024 characters; every relative link resolves on disk. Run `yaml.safe_load` on the frontmatter and `test -f` on each link target. Done when: all four pass.
9. **Probe and place.** Author three to five probe prompts — at least two that must fire the skill and at least two out-of-scope prompts that must not — and run each in a subagent. Adjust the `description` until every probe lands correctly. Then ask for the write target, defaulting to `.claude/skills/<name>/`, and re-run step 8 there. Done when: probe results are reported and the checks are green at the target.
One skill per run; another source is another run. Paraphrase the source; do not paste it. The skill, not the book, is the source of truth when the skill runs — keep it runnable without the source in context.
## Failure and recovery
- Source unopenable. A file the agent cannot open stops the run; name the file. This skill owns no converter and does not invent content for a source it cannot read.
- Fewer than three ordered actions. Not a failure — classify as reference and proceed with the reference shape.
- Validation check fails. Fix the offending field or link and re-run step 8. Do not claim done while any check is red.
- Probe lands wrong. Adjust the `description` and re-probe. Never mark done with a misrouting probe; a wrong negative probe is as blocking as a wrong positive one.
- Partial result. If the run stops mid-procedure, the written files are incomplete. Either complete the procedure or delete the target directory as rollback. Do not leave a half-written skill that parses as valid.
- Rollback. Delete the target skill directory. No artifact outside that directory is touched, so deletion is a complete recovery.
## Output
A self-contained `SKILL.md` (and optional `references/<topic>.md`) under the chosen target directory, carrying an attribution line and passing all four validation checks and the probe set — the report states the classification, chosen name, target path, validation results, and probe results (positive and negative).