Anatomy of a produced skill

When Phase 3 finishes, you have a new directory at .claude/skills/<slug>/ in your repo. This lesson walks through every file that lands there, what it contains, and when each one is included.

The directory tree

A maximal layout. Several entries are conditional. The smallest valid skill is the tree with everything optional removed.

.claude/skills/<slug>/
├── SKILL.md
├── AGENTS.md
└── references/
    ├── components/<name>.md        (one per component, when 10 or more components)
    │   OR
    ├── components.md                  (single file, when fewer than 10 components)
    ├── tokens.md                      (single file, when one token family)
    │   OR
    ├── tokens/<family>.md          (per-family file, when multiple families)
    ├── foundations/
    │   ├── index.md
    │   └── <page>.md               (one per accepted foundation URL)
    ├── examples/
    │   ├── index.md
    │   └── <name>.md               (one per composition exemplar lifted)
    ├── anti-patterns.md               (slug registry: shell + asset)
    └── design-craft.md                (always written, byte-for-byte from the meta-skill)

The conditional folders behave like this:

• foundations/ appears only when at least one [docs:foundation] URL was accepted at Phase 1.
• examples/ appears only when the reference project ships at least one composition exemplar.
• An empty directory with only an index.md is never written. The omission is part of the contract.

The top-level files

SKILL.md

always written

The orchestrator. Other agents read this file first when invoking the skill. It contains:

• Frontmatter: the skill's name and a description used by the dispatcher.
• Setup section: install instructions, provider mount, font setup, and verbatim Companion CSS blocks lifted from the reference project. The setup is paste-ready, not prose.
• Component slate: the confirmed list of components the skill covers, one bullet per component.
• Routing table: a "when you are doing X, load reference Y" map. Each row points at one file under references/.
• Hard rules: the universal [VERIFY] rule, the do-not-invent rule, and any shell-invariant rules lifted from the reference project's wiring.
• Final checks: a self-check paragraph the consuming agent reads before declaring a render done.

SKILL.md routes. It does not carry the manual.

AGENTS.md

always written

A short pointer file. Tools that look for AGENTS.md at the skill root find it here and follow it back to SKILL.md. Single source of truth lives in SKILL.md.

The components contract

references/components/<name>.md or references/components.md

always written, one section or file per component on the confirmed slate

The split depends on slate size. Ten or more components gets one file per component. Fewer than ten gets a single components.md with one ## ComponentName heading per component.

Each component contract carries eight required sections:

1. Public imports. The exact import statement a consumer writes.
2. When to use. One or two sentences on the component's purpose, distinct from sibling components.
3. Key props. The prop signatures that matter. Cited to the types file.
4. Accessibility. ARIA, keyboard, focus, label association.
5. Composition examples. Short code blocks that compile against the public API.
6. Source references. file:line cites that ground every claim above.
7. Common mistakes. What goes wrong with this component in practice.
8. Things to never invent. Props, variants, or sizes the component looks like it should have but does not.

A component with nothing distinctive to say still ships all eight sections. The empty-state bullet is "No special rules. Use the API as documented." Omitting a section reads as a gap. The explicit no-op reads as a verified absence.

The tokens layout

references/tokens.md or references/tokens/<family>.md

always written

One family (colour only, for example) gets a single tokens.md. Multiple families get a per-family split: tokens/color.md, tokens/space.md, tokens/type.md, tokens/motion.md.

Each token entry carries name, value, family, and a "use when" prose snippet. Prose rules that came from foundation pages (token-pairing, contrast minimums, mode-aware rules) do not live here. They live in references/foundations/<page>.md.

If the DS source was a [private-blocker] and the rendered-site recover probe ran, recovered tokens appear in a dedicated ## Probe-derived tokens [probe-derived] section at the bottom of the file. Never interleaved with cited entries.

Foundations (conditional)

references/foundations/<page>.md plus index.md

present only when a foundation URL was accepted at Phase 1

One file per accepted foundation URL (the root URL you passed and every depth-1 page the skill crawled within its path prefix). Each file holds the prose rules extracted from that page in one of five shapes:

• token-pairing: "use foreground token X on background token Y."
• mode-aware: "in dark mode, use token X instead of token Y."
• contrast-minimum: "this pair must meet WCAG AA, prefer AAA."
• semantic-role: "use the danger token for destructive actions."
• fallback-element: "when the component does not exist, use this primitive with this token."

index.md is a sub-index that lists every foundations/<page>.md file so the orchestrator can route to them by URL or topic.

When no foundation URL was passed at Phase 1, the entire foundations/ directory is omitted. The routing table in SKILL.md carries no foundation rows.

Examples (conditional)

references/examples/<name>.md plus index.md

present only when the reference project ships at least one exemplar

One file per composition exemplar lifted from the reference project. The lift covers two globs: app/**/page.tsx and components/showcase/*.tsx. Each example file shows the lifted code verbatim and adds per-file "what to copy" pattern bullets so the consuming agent knows which parts generalise.

If the reference project ships zero exemplars, the entire examples/ directory is omitted. The skill does not fabricate an example to fill the directory. The empty state is the correct state.

Anti-patterns (registry only)

references/anti-patterns.md

always written, but thin

Despite the name, this is a slug-resolution registry, not a generation reference. It contains exactly two things:

• Shell table. A Bad-Good-Why row for each shell invariant lifted from the reference project (unpainted body, missing mode attribute, missing provider wrap). Omitted when no wiring was lifted.
• Asset registry. One line per asset/* slug, naming the rule and pointing at the foundation page that holds the prose.

Component traps live in the per-component files. Token discipline lives in the tokens file. Do not expect this file to be a catch-all "things to avoid" document.

Design craft (always shipped verbatim)

references/design-craft.md

always written, unless you opted out at Phase 1

A DS-agnostic reference covering layout, hierarchy, typography, colour, spacing, motion, interactive states, and anti-slop restraint. It is generic taste guidance for the agent that later composes screens with the skill.

This file is not extraction output. scripts/scaffold.sh copies it byte-for-byte from the meta-skill's assets/design-craft.md. The skill never regenerates, paraphrases, or "adapts" it to the DS. Its own precedence header defers to the DS on every conflict. See Design craft, the shipped default for the full story.

What is intentionally not in the tree

The full-coverage rules

How the post-emit audit checks all of this

After Phase 3 writes, scripts/check-skill-docs.sh runs and asserts:

• Every routing table row in SKILL.md resolves to a file that exists.
• Every rule slug in the registry resolves to a citation in a reference file.
• Every component file ships all eight required sections.
• Every [VERIFY] marker is surfaced.
• Every file:line citation across every persisted file (including files carried over from earlier runs) still points at text that supports the claim.
• design-craft.md is a byte-for-byte copy of the meta-skill's original asset.

The script's exit code is the audit result. Exit 0 prints the closing message. Non-zero lists the failures and stops.

What to take away

1. The skill is a small, predictable directory you can read top to bottom.
2. SKILL.md routes. The references carry the manual.
3. Components, tokens, foundations, and examples each have a split rule (per-file or single-file) that depends on how much there is to say.
4. Some files are always present (SKILL.md, AGENTS.md, components, tokens, anti-patterns, design-craft). Foundations and examples are conditional. The empty state for an absent source is an absent file, not a stub.
5. Design craft is the only file that is not extraction output. It ships byte-for-byte from the meta-skill.

Primary source: .claude/skills/extract-ds-skill/references/persist.md (directory tree, split rules, materialization rules) and references/skill-template.md (per-file contracts). See primer-react for the produced version that ships in the starter.