Multi-File Skills with Schemas and Templates

When builders first learn to write Claude skills, they start with a single file: `SKILL.md`. That works well for short, five-step workflows. But as your procedures grow to include JSON output schemas, long reference tables, markdown report templates, and validation checklists, cramming everything into one file becomes counterproductive.

A 600-line SKILL.md file floods the context window the moment it triggers. Worse, it creates instruction drift, where the model gets confused trying to balance procedural steps with template examples in the same document. The professional solution is progressive disclosure: keeping SKILL.md concise and bundling supporting files into dedicated subdirectories.

The multi-file directory layout

Because a skill is a folder, anything your workflow needs can travel with it. The standard multi-file architecture organizes resources by function:

Progressive disclosure in practice

Progressive disclosure means loading information only when the immediate task demands it. Your `SKILL.md` contains the high-level roadmap and directs Claude when to open each supporting file.

---
name: spec-writer
description: Use when drafting a technical product specification or PRD for a new system feature.
---

# Spec writer

When invoked:
1. Interview the user to clarify the core requirements and constraints.
2. Read .claude/skills/spec-writer/templates/prd-template.md.
3. Populate each template section based on the user's answers.
4. If the feature involves database changes, consult .claude/skills/spec-writer/references/field-definitions.md.
5. Output the completed specification file to docs/specs/<feature-name>.md.

Notice the efficiency of this model: when Claude decides whether to use the skill, it reads only the description. When the skill triggers, it reads only `SKILL.md`. The template is loaded only when drafting begins, and the reference glossary is opened only if database changes exist. Context stays lean at every step.

Bundling JSON schemas for strict output verification

If your skill outputs structured data (such as API payloads or configuration files), bundle a JSON schema. Instruct Claude to validate its output against the schema before reporting completion.

Document templates and skeleton files

Asking an LLM to "format as a clean PRD" produces different headings every time. By bundling an exact markdown template in `templates/prd-template.md`, you guarantee uniform headings, required callouts, and consistent section order across every specification your team produces.

Keeping relative file paths portable

Always specify file paths relative to the project root (such as `.claude/skills/spec-writer/templates/prd-template.md`). Never use hard-coded user paths like `/Users/jeremy/...`, which will immediately fail when a teammate clones your repository.