The frontmatter and multi-file patterns that separate Skills that trigger from Skills that sit there

Your first skill works. It loads, it matches, it does its job. But the longer you use it, the more you notice edges: the description triggers inconsistently, you want to stop Claude from writing files when this skill is active, and the instruction content is creeping past a thousand lines of reference material you're not sure belongs inline.

This lesson is about the configuration and organisation techniques that take a basic skill and make it production-ready. The agent skills open standard supports a handful of metadata fields beyond the required two, and there's a pattern for splitting large skills across multiple files without blowing up your context window.

The full metadata field set

Two fields are required, and the rest are optional but powerful.

name (required) — Identifies your skill. Lowercase letters, numbers, and hyphens only. Maximum 64 characters. Should match your directory name.

description (required) — Tells Claude when to use the skill. Maximum 1,024 characters. This is the most important field because it's what Claude uses for matching.

allowed-tools (optional) — Restricts which tools Claude can use when the skill is active. Useful for read-only workflows or security-sensitive operations.

model (optional) — Specifies which Claude model to use while the skill is active (e.g. sonnet).

Here's the full field set in use:

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

Writing descriptions that actually trigger

If someone told you "your job is to help with docs," you wouldn't know what to do. Claude doesn't either. Vague descriptions are the single most common reason skills don't trigger when expected.

A good description answers two questions explicitly:

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

Before: "Helps with code review."

After: "Reviews frontend React components for accessibility, performance, and state management issues. Use when reviewing a PR that touches components, hooks, or styling, or when the user asks for an accessibility audit."

The second version names the specific work (accessibility, performance, state), the context it applies to (React components, hooks, styling), and the trigger phrases a real user might say. Semantic matching has a lot more to bite on.

If your skill isn't triggering reliably, the fix is almost always the same: add more trigger phrases that match how you actually phrase requests. Test variations. Iterate on the description, not on the instructions.

Restricting tools with allowed-tools

Sometimes you want a skill that can only read files, never modify them. Security-sensitive review workflows are the obvious case — you don't want Claude "helpfully" editing code while it's auditing it.

The allowed-tools field enforces this at the skill level. When the skill is active, Claude can only use the tools you list. No editing, no writing, no shell commands — whatever you omit is off the table while the skill is loaded. Developers who've worked with principle-of-least-privilege IAM policies will recognise the pattern.

allowed-tools: Read, Grep, Glob, Bash

If you omit allowed-tools entirely, the skill doesn't restrict anything — Claude uses its normal permission model.

Progressive disclosure for larger skills

Skills share Claude's context window with the rest of your conversation. When Claude loads a skill's full content, that content consumes tokens for the rest of the session. A 20,000-line mega-skill with every reference inline is both wasteful and miserable to maintain.

Progressive disclosure is the pattern for handling this. Keep essential instructions in SKILL.md and put detailed reference material, examples, and scripts in separate files that Claude reads only when needed.

The open standard suggests organising your skill directory like this:

skill-name/
  SKILL.md
  scripts/        # Executable code
  references/     # Additional documentation
  assets/         # Images, templates, data files

In your SKILL.md, link to the supporting files with instructions about when to load them. "Read references/architecture.md when the user asks about system design." Claude reads that file only when the architecture question comes up. If the user asks where to add a component, it never loads at all.

It's like having a table of contents in the context window rather than the entire document.

A good rule of thumb: keep SKILL.md under 500 lines. If you're past that, it's a signal to split the content — probably into a reference file, possibly into multiple skills.

Scripts execute without loading

There's a second lever for keeping skills efficient: scripts. Scripts in your skill directory can run without loading their contents into context at all. The script executes, Claude sees only the output, and only the output consumes tokens.

The key instruction in your SKILL.md is to tell Claude to run the script, not read it. That distinction matters. If Claude reads the script file, its full contents enter context. If Claude runs the script, only the stdout does.

Use this pattern for:

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

A ten-kilobyte validation script that produces ten lines of output is a massive context win compared to reading those ten kilobytes into the conversation.