## Context

The packaged CLI guide (`templates/skill.md`) reached 764 lines / ~11.8k tokens.
Anthropic's skill-authoring guidance puts the eagerly-loaded SKILL.md body under
**500 lines** and budgets that level at **under 5k tokens**; bundled files cost
nothing until read. docir's guide was 2.4x over, and every session that triggered
the skill paid all of it to learn how to run `docir context`.

The rules that constrain a split, from the same guidance:

- references must be **one level deep** from SKILL.md — a file reached through
  another referenced file gets previewed (`head -100`), not read;
- a reference file over 100 lines needs a **table of contents**, so a partial
  read still shows its scope;
- group **by task**, because the link text is what the assistant routes on.

## Decision

A skill is a **directory**, not a file: `templates/<name>/SKILL.md` plus the
reference files it links. `TemplateProvider.template` returns every `.md` keyed
by its path relative to the skill directory, and `AgentTarget.directory` is what
the skill owns outright.

The CLI guide splits into an entry point (~255 lines) carrying the everyday loop
— when to use, core loop, read, write, hard rules, types — and six task-grouped
files under `reference/`: setup, retrieval, schema, maintenance, publishing,
troubleshooting. Six rather than five because getting the entry point under
budget requires lifting `--expr`, `--also` and `--explain` out of the read
section, and those are one task, not a remainder.

**Installing a skill regenerates its directory.** Every packaged file is written
and every `.md` under that directory the build does not ship is deleted. This is
the rule `docir build` already applies to `--out`, for the same reason: a
reference file a release renamed would otherwise stay on disk, linked from
nothing, and still answer. Stale instructions are worse than absent ones.

## Consequences

- The sweep is bounded by the skill's own directory, so a second skill and
  anything else in the tree are untouched. It is reported in `InstalledFile.removed`,
  because it is the one part of an install that destroys something.
- `action` aggregates over the directory: a release that only adds a reference
  file is `updated`, though `SKILL.md` differs by nothing but its stamp. A
  per-file answer would report `unchanged` for a skill that gained a chapter.
- One row per target, not per file — seven rows repeating one version transition
  would bury the answer the caller wants.
- Every file carries the version stamp, so a hand-edited reference is
  distinguishable from a shipped one.
- The guide-vs-CLI sweep joins the template's files into one text: a command
  moved from the entry point into `reference/` has not stopped being documented.
- Cost: sibling cross-references (setup -> schema) are a second hop. They are
  tolerable only because every reference file is also linked from SKILL.md, so
  nothing is reachable *only* by nesting; a guard asserts that.

## Verified

The single-file → directory migration was exercised end to end: a repo carrying the
765-line v0.18 `SKILL.md` and no `reference/` runs `docir self upgrade --no-package`
and ends with a 256-line entry point, six reference files and a 0.18.0 → 0.19.0
transition. Pinned by `test_it_grows_a_single_file_skill_into_a_directory`.

That run also found the defect this change had shipped: `self upgrade` and `docir agent
update` each serialized `InstalledFile` themselves, so the upgrade reported the install
without naming the reference files it wrote. There is now one `_setup_file`, and
`test_upgrade_reports_an_install_the_same_way_agent_update_does` compares the two
commands' JSON keys.