CONCEPT The directory layout
A skill is a directory with SKILL.md as its required entrypoint. Every other file is optional and
exists to keep the main file focused while pushing detail to disk, where it's read only on demand:
my-skill/ ├── SKILL.md # required — frontmatter + instructions (the only mandatory file) ├── reference.md # detailed API docs — read when needed ├── examples.md # example outputs / expected format ├── template.md # a template for Claude to fill in └── scripts/ └── helper.py # executed via bash, not loaded into context
Each bundled file plays to a different strength: markdown references for flexible guidance
and factual lookup, scripts for deterministic, reliable operations. Crucially you must
reference supporting files from SKILL.md so Claude knows what each contains and
when to load it — an unreferenced file is invisible to the model. Keep SKILL.md itself under about
500 lines and move heavy detail into separate files.
For complete API details, see
[reference.md](reference.md). Claude follows the link and reads the file only when the task calls for it.CONCEPT The frontmatter reference
All frontmatter fields are optional; only description is recommended. The most commonly tested
fields:
| Field | Purpose |
|---|---|
name | Display name in listings. Defaults to the directory name. ≤ 64 chars, lowercase/digits/hyphens, no anthropic/claude. |
description | What the skill does & when to use it — Claude matches on this. Non-empty, ≤ 1024 chars. |
disable-model-invocation | true = only you can invoke it (manual /name only). |
user-invocable | false = hide from the / menu; Claude can still auto-invoke. |
allowed-tools | Tools Claude may use without a permission prompt while the skill is active. |
disallowed-tools | Tools removed from the pool while the skill is active (clears on your next message). |
argument-hint / arguments | Autocomplete hint and named positional args for $name substitution. |
context / agent | context: fork runs the skill in a subagent; agent picks the subagent type. |
model / effort | Override the model / effort level while the skill is active. |
paths | Glob patterns that limit auto-activation to matching files. |
allowed-tools does not restrict the tool pool — every tool
stays callable and your permission settings still apply. It only pre-approves the listed tools so
Claude won't prompt for them. For project skills it takes effect only after you accept the workspace trust
dialog. Review project skills before trusting a repo — a skill can grant itself broad access.DIAGRAM How the parts fit together
name · description · allowed-tools · …"] SM --> BODY["Markdown body
(instructions)"] FM --> META["🟢 Level-1 metadata
always in context"] BODY --> LINK{"Body links to
bundled files?"} LINK -->|"[reference.md]"| REF["📄 reference / examples
read on demand"] LINK -->|"scripts/helper.py"| RUN["⚙️ run via bash
output only enters context"] RUN --> DIR["Path uses \${CLAUDE_SKILL_DIR}
so it resolves anywhere"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class META ok; class REF gate; class RUN gate; class DIR gate;
CODE A skill that bundles and runs a script
The allowed-tools line pre-approves the python call so Claude runs it without a prompt. The
script path uses ${CLAUDE_SKILL_DIR} — the directory holding this SKILL.md — so it
resolves whether the skill is installed personally, in a project, or via a plugin.
# File: ~/.claude/skills/codebase-visualizer/SKILL.md --- name: codebase-visualizer description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or finding large files. allowed-tools: Bash(python3 *) --- # Codebase Visualizer Run the visualization script from your project root: python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py . This creates codebase-map.html in the current directory and opens it in the browser. ## Additional resources - For output-format details, see [reference.md](reference.md)
TRADE-OFFS Inline instructions vs. bundled resources
✅ Move detail into bundled files
SKILL.mdstays short and readable (< 500 lines)- Large refs load only for the tasks that need them
- Scripts give deterministic results, zero code-in-context
⚠️ Cram everything into SKILL.md
- The whole body loads every time the skill triggers
- Long reference material inflates every invocation
- Harder to maintain and review
EXAM TRAPS
SKILL.md body references it and the task needs it. Unreferenced files are
never seen.allowed-tools limits which tools the skill can use." → It
pre-approves (grants without prompting); it does not restrict. Use disallowed-tools or deny
rules to actually remove tools.${CLAUDE_SKILL_DIR} so the path resolves regardless of the current working directory or where the
skill is installed.SKILL.md is optional if you have other files." → SKILL.md
is the required entrypoint. Everything else is optional.PRACTICE
Q1 · What's the one required file in a skill directory, and what must you do so Claude uses the others?
SKILL.md is required. For any other bundled file to be used, you must
reference it from SKILL.md (e.g. a markdown link to reference.md) so Claude knows it exists
and when to read it.
Q2 · What does allowed-tools actually do?
It pre-approves the listed tools while the skill is active, so Claude uses them without a permission prompt. It does not restrict the tool pool — all tools remain callable and your permission settings still govern the rest. For project skills it applies only after the workspace trust dialog is accepted.
Q3 · Why reference a bundled script with ${CLAUDE_SKILL_DIR}?
It expands to the directory containing this SKILL.md, so the script path is correct
whether the skill lives in ~/.claude/skills/, a project's .claude/skills/, or a plugin
— regardless of the current working directory.