When SKILL.md isn't enough

Here's the folder for the very skill that wrote this book — book-builder:

SKILL.md is the front door. The rest of the folder is yours to design — but the convention is so well-established that breaking it costs more than following it. Three sibling folders, three different jobs:

• templates/ — stencils to fill in
• references/ — knowledge to look up
• scripts/ — code to run

The rest of this chapter takes each one in turn.

A template is a file with named slots that Claude fills in before using. The slots are usually written {{LIKE_THIS}} — placeholders, in the literal sense.

SKILL.md says something like: "fill in templates/build-chapter.md with the user's inputs, then dispatch it to an agent." Claude reads the template, replaces every {{PLACEHOLDER}} with the actual value from the conversation, and uses the result.

The book-builder skill's templates/build-chapter.md is the agent prompt template used to spawn every chapter you're reading — a roughly 200-line stencil with slots for chapter number, palette, content outline, and required widgets. SKILL.md is short; the heavy prompt engineering lives in the template.

References are longer docs the skill consults occasionally — decision tables, examples galleries, project conventions. Anything Claude needs to read sometimes but not always.

SKILL.md cites them by relative path, like a footnote: "see references/voice-rule.md for the inviolable voice rule". Claude reads the file only when the work in front of it actually needs that knowledge — building a new chapter triggers a read; answering a meta-question about the skill probably doesn't.

The book-builder skill keeps two references: voice-rule.md (the plain-English-first constraint that makes the family feel accessible) and palette-registry.md (which color schemes are already taken, so new books don't clash). Both are 100-200 lines — way too big to inline in SKILL.md, perfectly sized for a reference.

Scripts are runnable files — shell, Python, Node, whatever. SKILL.md says "run scripts/verify.mjs" and Claude executes it via the Bash tool. The output goes back into the conversation, and Claude uses it.

The book-builder skill ships a single script: scripts/verify.mjs, a Playwright check that launches the rendered HTML book, screenshots it, scans for empty regions and JavaScript errors, and prints a verdict. SKILL.md links to it from the "Verification" section; chapters get verified by running it.

Scripts are how a skill becomes more than just instructions — they let the skill do real work. If a step is deterministic, scriptable, and you'd rather not have Claude reinvent it every time, that step belongs in a script.

Here's the part that makes the whole system work.

Claude doesn't read every file in the skill folder. It reads SKILL.md, and then reads supporting files only when SKILL.md instructs it to.

At session start, Claude sees the description of every available skill — a one-line summary in the frontmatter. That's it. The body of SKILL.md isn't even loaded yet.

When something triggers the skill — a slash command, or a description match — Claude reads the body of SKILL.md. Inside the body, Claude finds instructions like "see references/voice-rule.md" or "run scripts/verify.mjs". Those are read-on-demand cues. Claude follows the cue and pulls the supporting file into context, but only at the moment it's needed.

This is why SKILL.md can stay small while the skill is rich. The skill folder might contain 2,000 lines of templates, references, and scripts. None of that weight enters Claude's context until SKILL.md explicitly says "now load this one." The skill folder is a library; SKILL.md is the index.

Supporting files are referenced relative to the skill folder, not the user's current working directory. When SKILL.md says templates/build-chapter.md, Claude resolves that to ~/.claude/skills/book-builder/templates/build-chapter.md — wherever the skill itself lives.

This matters because the user might be working in any directory when the skill fires. ~/projects/my-book/, /tmp/scratch/, anywhere. Relative paths in SKILL.md always anchor to the skill's own home, so they stay portable.

When you need to reach outside the skill folder — like pointing at a canonical style reference somewhere else on disk — use an absolute path. The book-builder skill's SKILL.md, for example, contains an absolute path to /Users/daffy/claudeHome/categoryTheory/index.html because that's the family-wide source of truth. Absolute paths sacrifice portability for precision — fine for personal skills, brittle for shared ones.

When SKILL.md changes its workflow, the templates and references it points to usually need to change too. A new step in the recipe might need a new placeholder in the template. A revised decision might invalidate half of references/decisions.md.

The clean way to handle this: treat the whole skill folder as one versioned unit. Put it in git. Commit SKILL.md and its supporting files together. When you bump the skill, you bump everything in lockstep.

This sounds obvious. It's not. The temptation is to edit SKILL.md without checking whether the template still matches, then ship the change and find out the next chapter build breaks because the agent prompt template still asks for an old field. Skills aren't single files — they're folders. Version them as folders.

Three widgets, each isolating one idea from above: the file-tree explorer (what's actually in a skill folder), the loading order visualizer (when each file enters context), and the template filler (what a stencil looks like in practice).

Folder shape mirrors job shape. A skill that orchestrates and templates ends up with all three subfolders. A skill that does one thing with one script can get away with much less.