D3 · Claude Code › Cluster 5 · Skills

5.3 · Skill Structure & Bundled Resources

Frontmatter · scripts · references

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.

Point at bundled files with plain markdown links, e.g. 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:

FieldPurpose
nameDisplay name in listings. Defaults to the directory name. ≤ 64 chars, lowercase/digits/hyphens, no anthropic/claude.
descriptionWhat the skill does & when to use it — Claude matches on this. Non-empty, ≤ 1024 chars.
disable-model-invocationtrue = only you can invoke it (manual /name only).
user-invocablefalse = hide from the / menu; Claude can still auto-invoke.
allowed-toolsTools Claude may use without a permission prompt while the skill is active.
disallowed-toolsTools removed from the pool while the skill is active (clears on your next message).
argument-hint / argumentsAutocomplete hint and named positional args for $name substitution.
context / agentcontext: fork runs the skill in a subagent; agent picks the subagent type.
model / effortOverride the model / effort level while the skill is active.
pathsGlob 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

flowchart TD SM["SKILL.md"] --> FM["YAML frontmatter
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)
🔑 The script's Python source never enters context — Claude runs it via bash and sees only its printed output. That makes bundled scripts far cheaper and more reliable than having Claude regenerate equivalent code inline.

TRADE-OFFS Inline instructions vs. bundled resources

✅ Move detail into bundled files

  • SKILL.md stays 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

Trap: "Bundled files load automatically with the skill." → No — Claude reads a bundled file only when the SKILL.md body references it and the task needs it. Unreferenced files are never seen.
Trap: "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.
Trap: "Reference the script with a relative path." → Use ${CLAUDE_SKILL_DIR} so the path resolves regardless of the current working directory or where the skill is installed.
Trap: "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.