Notes
Claude
Introduction to Agent Skills
Configuration and Multi-File Skills

Configuration and Multi-File Skills

Note

TL;DR

  • name and description are required — allowed-tools and model are optional but powerful additions
  • A good description answers two questions: What does the skill do? When should Claude use it?
  • allowed-tools pre-approves the listed tools while the skill is active, so Claude can use them without asking, and it doesn’t limit Claude to those tools
  • Progressive disclosure: keep SKILL.md under 500 lines and link to supporting files (references, scripts, assets) that Claude reads only when needed
  • Tell Claude to execute scripts without loading their contents into context — only the output consumes tokens, keeping context efficient

Skill Metadata Fields

The agent skills open standard defines the core fields in the SKILL.md frontmatter, and Claude Code adds a few of its own (such as model).

FieldRequired?What it doesRules and tips
nameYesIdentifies the skill
  • Lowercase letters, numbers and hyphens only, up to 64 characters.
  • Should match the skill’s folder name.
    • descriptionYesTells Claude when to use the skill. The lesson calls this the most important field, because Claude matches requests against it.
  • Up to 1,024 characters.
  • Say what the skill does and when to use it, and include the words people actually use when asking for that task.
    • allowed-toolsNoLets Claude use the listed tools without asking permission while the skill is activeThe approval lasts for the turn that invoked the skill and ends with your next message. It doesn’t stop Claude from using other tools. Plain Bash approves all shell commands, so narrow it, e.g. Bash(git status *). If you leave the field out, nothing is pre-approved.
    modelNoPicks which Claude model runs the skillUse it when a skill needs a specific model.
    disallowed-toolsNo (a separate Claude Code field the lesson also mentions)Takes the listed tools away while the skill is activeThis is the opposite of allowed-tools: it actually removes tools.

    Writing Effective Descriptions

    Be explicit with your instructions.

    A good description answers two questions:

    1. What does the skill do?
    2. When should Claude use it?
    Tip

    If your skill isn’t triggering when you expect it to, try adding more keywords that match how you actually phrase your requests. The description is what Claude uses to decide whether a skill is relevant, so the language matters.

    Pre-Approving Tools with allowed-tools

    The allowed-tools field pre-approves the tools you list, so Claude can use them without a permission prompt for the rest of the turn that invoked the skill. The grant clears when you send your next message.

    Example
    ---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

    The allowed-tools field is set to Read, Grep, Glob, Bash. When this skill is active, Claude can use those four tools without asking permission. It doesn’t lose access to anything else: if the skill’s instructions lead Claude to edit or write a file, that goes through your normal permission settings like any other tool call.

    Caution

    Listing Bash on its own pre-approves shell commands in general, so reserve that for skills you trust, or narrow it to a pattern such as Bash(git status *).

    To take tools away while a skill is active, use a separate Claude Code frontmatter field, disallowed-tools, which removes the tools you list from the set Claude can use.s

    Progressive Disclosure

    Why progressive disclosure is necessary

    Skills share Claude’s context window with your conversation. When Claude activates a skill, it loads the contents of that SKILL.md into context. But sometimes you need references, examples, or utility scripts that the skill depends on.

    Cramming everything into one 2,000-line file has two problems: it takes up a lot of context window space, and it’s not fun to maintain.

    Progressive disclosure: Keep essential instructions in SKILL.md and put detailed reference material in separate files that Claude reads only when needed.

    The open standard suggests organizing your skill directory with:

    LocationContainsNotes
    SKILL.mdEssential instructions, plus links to the supporting files with clear guidance on when to load each oneA good rule of thumb: keep SKILL.md under 500 lines.
    scripts/Executable code
    references/Additional documentation
    assets/Images, templates, or other data files

    Example:

    my-skill/
├── SKILL.md          # short (<500 lines): what to do and when to read the other files. 
├── references/
│   └── architecture-guide.md
├── scripts/
│   └── check.py
└── assets/
    └── report-template.md

    Using Scripts Efficiently

    Key instruction to include in your SKILL.md: Tell Claude to run the script, not read it.

    • Scripts in your skill directory can run without loading their contents into context. The script executes and only the output consumes tokens.
    Python analogy
    In Python you call pd.read_csv(path) without pasting the pandas source into your notebook. You care about the result, not the 10,000 lines that produced it. A skill script works the same way for Claude.

    This is particularly useful for:

    • Environment validation
    • Data transformations that need to be consistent
    • Operations that are more reliable as tested code than generated code
    Example

    In a CV evaluation skill, SKILL.md could say:

    Run scripts/eval_metrics.py --pred preds.json --gt labels.json and summarize the mAP and per-class results.

    Claude executes your tested metric code and sees only a short results table, not the implementation. You get the same mAP calculation every run, instead of Claude improvising one.

    docs