Master the 14+ SKILL.md Metadata Fields for Claude Agents

Basic Specification

The official specification defines six fields. Two are required ( name, description) and four are optional ( license, compatibility, metadata, allowed-tools).

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.
license: Apache-2.0
compatibility: Requires Python 3.10+ and pdfplumber
metadata:
  author: your-org
  version: "1.2"
  color: "#4A90E2"
  allowed-tools: Read, Bash
---

name

Must match the directory name: only lowercase letters, numbers, and hyphens, up to 64 characters, no consecutive hyphens, and cannot start or end with a hyphen.

description

The most important field. It is loaded at skill startup (≈100 tokens) and is read by the Agent to decide whether to activate the skill. Use third‑person phrasing; the description is injected into the system prompt, so first‑person breaks matching.

# Wrong
description: I can help you process Excel files
# Right
description: Processes Excel files and generates reports

Answer two questions: what the skill does and when it should be used. Most descriptions only cover the first question.

# Too vague
description: Helps with PDFs.
# Works
description: Extracts text and tables from PDF files, fills forms, and merges PDFs. Use when the user mentions PDFs, forms, or document extraction.

The field is limited to 1,024 characters; if a skill does not trigger as expected, the description is the first place to check.

license

Short string: standard SPDX identifier such as Apache-2.0 or MIT, or a reference to a bundled license file.

license: Proprietary. LICENSE.txt has complete terms.

compatibility

Specifies any environment requirements. Most skills do not need this, but it is useful when a skill depends on a specific runtime version or network access.

compatibility: Requires Python 3.14+ and uv
compatibility: Requires git, docker, and internet access

metadata

Arbitrary key‑value map for anything the core spec does not cover, such as author, version, or UI hints like color. Whether a client reads these values depends on the implementation.

metadata:
  author: your-org
  version: "1.0"
  color: "#4A90E2"

allowed-tools

Restricts which tools the Agent may use when the skill is activated. It is experimental in the spec but reliable in Claude Code. Omitting it means no restriction.

allowed-tools: Read, Grep, Glob, Bash

Useful for read‑only workflows or security‑sensitive contexts. You can also limit individual Bash commands:

allowed-tools: Bash(git add*), Bash(git commit*), Bash(git status*)

Claude Code Extensions

when_to_use

Supplement to description that appears after the description in the skill list. It separates “what” from “when” without crowding a single paragraph.

description: Analyzes BigQuery data across sales, finance, and product tables.
when_to_use: Use when the user asks about revenue metrics, pipeline data, API usage, or any SQL question.

model and effort

model

selects the Claude model used when the skill runs. effort sets inference depth: low, medium, high, xhigh, or max.

model: haiku
effort: low

These fields help match tasks to appropriate compute; formatting or lookup skills do not need the same performance as heavy analysis.

disable-model-invocation

Set to true to prevent Claude from automatically activating the skill. The skill will only run when you explicitly type /skill-name. This is useful for side‑effect operations (deployment, commits, messaging) where you want full control. When enabled, the description is removed from Claude’s context, so the skill will not be suggested.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

user-invocable

Set to false to hide the skill from the / menu while still allowing Claude to auto‑activate it. Useful for background knowledge skills that should not be invoked directly by the user.

Interaction summary: disable-model-invocation: true → only the user can invoke. user-invocable: false → only Claude can invoke.

paths

Limits automatic activation to files matching specific glob patterns. Example:

paths: "**/*.sql, **/migrations/**"

Prevents a skill from interfering with unrelated work in other languages or domains.

context and agent

Setting context: fork runs the skill in an isolated sub‑Agent instead of inline. agent specifies the sub‑Agent type (e.g., Explore, Plan, or a custom agent defined under .claude/agents/).

---
name: deep-research
description: Research a topic thoroughly across the codebase.
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Skills in Sub‑Agents

Skills do not automatically propagate to sub‑Agents. When a sub‑Agent is started, it begins with a clean slate. To make a skill available, list it in the sub‑Agent’s AGENT.md under the skills field.

---
name: report-agent
description: Generates structured reports from raw data.
skills:
  - pdf-processing
  - data-analysis
---
You are a specialized reporting agent.
When extracting source data, use the PDF and analysis skills.

If the skill is omitted, the sub‑Agent will not know about it, leading to slower, less consistent behavior.

Progressive Disclosure and Scripts

When a skill is triggered, the full SKILL.md body enters the context window. Keep it under 500 lines and move detailed references to support files so Claude loads them only when needed.

my-skill/
SKILL.md
references/
scripts/
assets/

Conditionally reference support files from SKILL.md:

For architecture questions, read `references/architecture-guide.md`.
For routine tasks, proceed directly.

Maintain a single level of reference depth; deeper nesting may cause Claude to preview rather than fully read the file, missing content. Scripts can be executed without loading their source code; only the output consumes tokens. Instruct Claude to run a script rather than read it.

Which Fields Do You Really Need?

For most skills, the essential fields are: description (always needed)

Optionally when_to_use If you need restrictions, add allowed-tools Other fields are for special cases such as sub‑Agent workflows, side‑effect automation, or large/domain‑specific skills.

Three Situations Requiring Full Field Lists

Building sub‑Agent workflows – verify context and agent, and list required skills in the sub‑Agent’s AGENT.md.

Creating automation with side effects – use disable-model-invocation: true to keep control.

Large or domain‑specific skills – use paths to limit activation scope and keep SKILL.md concise.