What are Claude Agent Skills | Minimal SKILL.md and How to Create One
Whether you're interested in extending Claude's capabilities or an engineer wanting to implement custom skills, the mechanics of SKILL.md are worth understanding. From placement to description format to why 100 skills won't balloon your context, we'll cover the details. The implementation section in the second half is designed so beginners can skip it and still understand the concept.
Agent Skills run on just YAML frontmatter + Markdown body, and placing a .claude/skills/<name>/SKILL.md file lets you specialize Claude in minutes. You can organize long guidelines into folders and reuse them, with Claude automatically loading them from context.
The key to implementation is writing triggers as verbs in the description. If you don't write specific activation conditions like "when adding new endpoints or modifying existing APIs," Claude won't notice the skill exists and your carefully written rules won't be loaded.
100 skills don't bloat context because Progressive Disclosure's 3-stage loading kicks in—metadata stays in memory while full text expands only when relevant. Store skills in your repository for Git-managed team sharing and immediate training cost reduction.
目次 (15)
- What are Agent Skills — Extending Claude to Specialized Agents Through Organized Folders
- Differences from Other Claude Extensions
- Which Products Support Agent Skills
- Minimal SKILL.md — YAML Frontmatter + Body Text Only
- Placement and Scope
- Progressive Disclosure — 3-Stage Loading Keeps Context Lean Even with 100 Skills
- Why Progressive Disclosure Matters
- Example: PDF Skill — Typical Structure with SKILL.md + reference.md + scripts/
- What Official Samples Teach
- Creating Custom Skills in 5 Steps — From SKILL.md Placement to Trigger Verification
- Confirming Triggers
- Hallmarks of Good Skills — Clear Activation in Description, ~100 Lines Body, Git-Managed
- Antipattern: Monolithic Skill with Everything
- Integrating into Operations
- Sources (Primary Information)
What are Agent Skills — Extending Claude to Specialized Agents Through Organized Folders
Agent Skills are organized instructions, scripts, and resources in a folder structure that Claude dynamically discovers and loads. They transform a general-purpose Claude into a specialized agent strong at specific tasks, representing the standard way to teach Claude domain knowledge, internal rules, and repetitive workflows. Think of it as extracting long guidelines you'd paste into prompts each time into a reusable folder structure.
Differences from Other Claude Extensions
Similar concepts include MCP (Model Context Protocol) servers and slash commands, but Agent Skills serve a different role. MCP handles connections to external systems (APIs, databases), and slash commands are explicit user-triggered routines. Agent Skills stand out because Claude itself judges from conversation context whether it needs the skill—users don't need to remember skill names each time.
Which Products Support Agent Skills
Agent Skills work across Claude.ai Pro/Max/Team/Enterprise plans, Claude Code, Claude Agent SDK, and Developer Platform. The same SKILL.md reuses across environments, so skills developed internally can be referenced from Claude.ai chats and headless CI runs alike.
Minimal SKILL.md — YAML Frontmatter + Body Text Only
A SKILL.md runs on YAML frontmatter + Markdown body in minimal form. The frontmatter needs just two items: name (skill identifier) and description (activation conditions), with rules or steps as Markdown in the body. Your first skill takes minutes to write—start by extracting repeatedly-explained internal rules like "API conventions" or "commit message standards" into a single file.
---
name: api-conventions
description: REST API design standards for this project
---
# API Standards
- URL paths use kebab-case
- JSON fields use camelCase
- List endpoints must include pagination
- API version goes in the URL path (e.g., /v1/users)
That's all Claude needs to load this skill at the right moment and answer API questions using your project's standards. Critically, how you write the description matters—without concrete "when and where" guidance, Claude won't notice the skill exists. Write it at the granularity of "apply when adding new endpoints, modifying existing APIs, or generating OpenAPI schemas" with verb-based triggers. That's the trick.
Placement and Scope
SKILL.md location depends on scope. In Claude Code, place project-wide shared skills at .claude/skills/<skill-name>/SKILL.md, personal ones at ~/.claude/skills/<skill-name>/SKILL.md. Repository placement means Git management and team-wide sharing, cutting internal rule training costs.
Progressive Disclosure — 3-Stage Loading Keeps Context Lean Even with 100 Skills
According to the source, Agent Skills use 3-stage disclosure for token efficiency:
| Stage | Content | Always Loaded? |
|---|---|---|
| Stage 1 | name / description (metadata only) |
Yes, always |
| Stage 2 | Full SKILL.md body |
When Claude judges it relevant |
| Stage 3+ | Referenced files (references, scripts) | On-demand during task execution |
※From official docs:
- Stage 1: "just enough information for Claude to know when each skill should be used"
- Stage 2: "If Claude thinks the skill is relevant to the current task, it will load the skill by reading its full SKILL.md into context."
- Stage 3+: "additional linked files ... which Claude can choose to navigate and discover only as needed."
This design means registering many skills doesn't bloat context. Even with 100 registered skills, only each skill's name and description (tens of tokens) stay in memory; body text, references, and scripts load only when the task calls for them. Compared to pasting all guidelines into prompts, context consumption stays dramatically lower.
Why Progressive Disclosure Matters
Claude's context window grows larger but remains finite. Large projects compress capacity just reading source code, tests, and design docs. Agent Skills' staged expansion implements a "expand only when needed" principle, letting you grow knowledge assets without linear cost increase. It's a shift from dumping the entire internal wiki into Claude, toward opening only necessary drawers—this framework makes that shift possible.
Source: Anthropic Engineering: Equipping agents for the real world with Agent Skills
Example: PDF Skill — Typical Structure with SKILL.md + reference.md + scripts/
Anthropic's published PDF Skill follows this structure:
pdf-skill/
├── SKILL.md # Rules for handling PDFs
├── reference.md # Details on form field extraction
└── scripts/
└── extract_form.py # Python script for PDF form extraction
When a PDF task arises, Claude first reads SKILL.md, then runs scripts/extract_form.py if needed. The SKILL.md body stays light—just basic PDF rules, available files, recommended flows—while finer details (form field extraction specifics) live in reference.md. This pattern of keeping the main file slim and branching to references when depth is needed is a learnable template for Progressive Disclosure.
What Official Samples Teach
Anthropic publishes practical skills (PDF, Excel, PowerPoint, Word) in the anthropics/skills repository. All share four traits: (1) description uses verbs to clarify activation, (2) SKILL.md body stays skeletal, (3) detailed specs and long lists move to separate files, (4) scripts appear only where automation is needed. Mimicking the public samples' structure as your initial template minimizes initial mistakes.
Creating Custom Skills in 5 Steps — From SKILL.md Placement to Trigger Verification
Here's a concrete workflow for deploying your first internal skill. Budget 5–10 minutes. Skip perfectionism; get it running, then refine the description and body—this pragmatic approach works best.
- Create
.claude/skills/<skill-name>/SKILL.md - Add
nameanddescriptionto YAML frontmatter (clarify which tasks use it) - Write concrete steps, rules, and prohibitions in the body
- Optionally add related files (
reference.md,templates/,scripts/) - Run in Claude Code and verify the skill triggers as intended
Confirming Triggers
After placing a skill, feed Claude a request that includes the exact activation terms from the description to confirm it fires. Ask something concrete like "Design a new /v1/orders endpoint," then check each rule—kebab-case URLs, pagination included, etc. If it doesn't trigger, your description is likely too abstract; rewrite with clearer verbs around "when, what, how" to fix it.
Hallmarks of Good Skills — Clear Activation in Description, ~100 Lines Body, Git-Managed
Running multiple internal skills eventually splits them into skills people reference and skills you wrote then forgot. Surviving skills share patterns—nail these and maintenance costs and real-world impact shift sharply.
descriptionclearly states when to use it- SKILL.md body fits ~100 lines (too long starves other skills)
- Includes runnable commands or concrete examples
- Version-controlled (Git)
Antipattern: Monolithic Skill with Everything
Avoid cramming multiple domains (API rules, test rules, deployment rules) into one SKILL.md. Body text exceeding 500 lines inflates Stage 2 load tokens, losing context fights with other skills and becoming less likely to load. Split by role, sharpen each description, and Claude finds it easier to judge while humans find it easier to maintain.
Integrating into Operations
Skills aren't write-and-forget—they're living assets updating with changing workflows. Internally, add "has this rule updated SKILL.md?" to PR review criteria, do monthly skill inventory reviews, and Claude's output quality stays stable. Since skills are Git-managed, audit trails let you trace changes.
Sources (Primary Information)
The primary sources directly referenced in this article are listed below. Always verify latest accurate information at the links.
