SKILL.md File Structure Explained: Frontmatter to Disclosure

---

SKILL.md pairs YAML frontmatter with a Markdown body your team loads in stages, the same shape platforms like Atlan, Alation, Collibra, DataHub, and Informatica all ship today. What separates them is whether the data those bundled files point to is still accurate; a 238-skill arXiv study found over 99% of real-world skills already carry at least one authoring flaw.

Field	Detail
What it is	The required file, with a YAML frontmatter block, that defines an Agent Skill’s metadata, instructions, and bundled resources
Required fields	name (max 64 characters, lowercase letters, numbers, and hyphens, no “anthropic” or “claude”) and description (max 1,024 characters, states what the skill does and when to use it)
Optional structure	references/, scripts/, and assets/ subdirectories, loaded on demand
Loading model	Three-level progressive disclosure: metadata always loaded, body loaded on trigger, bundled resources loaded on access
Common failure mode	Over 99% of real-world SKILL.md files contain at least one “skill smell,” and most trace back to a vague description field
Best for	Stable, repeatable procedural knowledge, not data that changes between invocations

---

What is SKILL.md?

Permalink to “What is SKILL.md?” #

A skill is a folder, and SKILL.md is the one file every skill must have: a YAML frontmatter block followed by Markdown instructions that tell Claude what the skill does and how to carry it out. According to Anthropic’s Claude Platform Docs, this two-part structure, frontmatter plus body, is what turns a folder of files into something Claude can discover, trigger, and execute as a single unit. The lineage runs from prompt engineering through context engineering and harness engineering to skill engineering, and SKILL.md is the concrete artifact that lineage produces.

The format is no longer Claude-only. GitHub Copilot’s code review now supports custom agent skills alongside MCP connections in public preview, the 139,000-star langchain-ai/langchain repository has an open feature request for native support (issue #38170), and Arize ran a production-evaluation workshop on Agent Skills at the AI Engineer World’s Fair in June 2026. Independent commentators are naming “skill engineering” a distinct, newest rung above prompt and context engineering, a lineage what are Agent Skills traces in more depth.

---

How is a SKILL.md file structured?

Permalink to “How is a SKILL.md file structured?” #

A SKILL.md file has exactly two required parts, a YAML frontmatter block and a Markdown body, plus a small set of validation rules deciding whether Claude loads it at all.

The name field is capped at 64 characters, lowercase letters, numbers, and hyphens only, and cannot contain “anthropic” or “claude.” The description field is capped at 1,024 characters and must state both what the skill does and when to use it. Of the two, description is the more consequential field. Philipp Schmid, Staff Engineer for Developer Experience at Google DeepMind, put it directly: “The description in your SKILL.md is the trigger mechanism.” Practitioners report roughly a 50% improvement in trigger accuracy from tuning the description alone, no body changes needed. Description tuning is one of the practices Agent Skill best practices covers, and it’s where the discipline starts to diverge from what came before it: see skill engineering vs prompt engineering for how.

One security rule is easy to miss: no XML or angle-bracket tags, since these can inject unintended instructions into the system prompt before the skill runs, a risk both agentskills.io and Anthropic’s docs flag. The recurring practitioner complaint isn’t bad instructions, it’s that skills don’t trigger, and a vague description is almost always why.

Field	Max length	Allowed characters	Notes
name	64 characters	Lowercase letters, numbers, hyphens	Cannot contain “anthropic” or “claude”
description	1,024 characters	Any, no XML or angle-bracket tags	Must state what the skill does and when to use it

---

What are the three levels of progressive disclosure?

Permalink to “What are the three levels of progressive disclosure?” #

Progressive disclosure is the design principle that lets a skill be arbitrarily large without costing context tokens until a piece is actually needed.

Level 1: metadata, always loaded (about 100 tokens)

Permalink to “Level 1: metadata, always loaded (about 100 tokens)” #

The name and description fields load into every session, whether or not the skill gets used. This fixed cost is why description carries so much weight: it’s the only thing evaluated before Claude decides to load more.

Level 2: the SKILL.md body, loaded on trigger (under 5,000 tokens)

Permalink to “Level 2: the SKILL.md body, loaded on trigger (under 5,000 tokens)” #

Once description matches the task, the full Markdown body loads: instructions, steps, guidance. This is where authoring quality matters most, and where the “skill smell” research below becomes relevant, since body problems surface only once a skill triggers.

Level 3: bundled resources, loaded on demand (zero tokens until accessed)

Permalink to “Level 3: bundled resources, loaded on demand (zero tokens until accessed)” #

references/, scripts/, and assets/ files sit inside the skill folder but aren’t loaded automatically; Claude reads them only when a task requires it. Barry Zhang, Keith Lazuka, and Mahesh Murag of Anthropic Engineering describe why this matters: “Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable.” Because bundled files cost nothing until read, a skill’s Level 3 content is effectively unbounded, exactly why what’s inside those files deserves a closer look.

This model builds on work most teams have already done one rung down the stack. A skill’s instructions are one form of context engineering, and a skill typically runs inside an agent harness that supplies its own surrounding context, which is why context engineering for AI agents is worth reading alongside this page: the disciplines share a lineage, not a competition. Skip any of the three levels and a naive approach loads everything upfront, every session, whether or not the task uses it, the exact cost progressive disclosure exists to avoid.

---

Where does governed data fit into a skill’s bundled resources?

Permalink to “Where does governed data fit into a skill’s bundled resources?” #

Progressive disclosure answers when a skill loads a reference file or schema. It says nothing about whether that file is still true.

Every structural source on SKILL.md, Anthropic’s docs, its engineering post, agentskills.io, and the academic literature on skill authoring, treats Level 3 bundled resources as purely procedural cargo: a references/schema.md, a data dictionary, a lookup table a script queries. None asks whether that file is stale, deprecated, or uncertified. Anthropic’s own security guidance gets closest to a trust framing, and it’s still about authorship trust, not data trust: a well-authored skill can still act confidently on a table deprecated three quarters ago.

This applies to skills whose references/ or scripts/ bundle points at business context: schemas, glossary terms, lookup data. Plenty of skills, including Anthropic’s own pptx, xlsx, and docx skills, never touch business data, and this callout doesn’t apply to them. But for the ones that do, this is precisely the gap Atlan’s context layer is built to close: certifying, versioning, and keeping current the business context a skill’s Level 3 files point to, delivered over MCP so a skill reads from a governed source instead of a static file an author copy-pasted once.

The same gap shows up one rung down the stack, in data quality for AI agent harnesses and AI agent accuracy, and context freshness names it directly: a file that was accurate when written has silently stopped being true. It’s the same line data catalog vs context layer, MCP-connected data catalog, and context layer and harness engineering draw elsewhere in the stack. Governed context for Agent Skills makes the full case; this page names the question.

---

What does a real SKILL.md example look like?

Permalink to “What does a real SKILL.md example look like?” #

The clearest way to see how the pieces fit together is a real, shipped skill, not a toy example.

Anthropic explicitly recommends its own skill-creator skill, found in the anthropics/skills GitHub repository, as the best way to learn the format hands-on. Its directory layout shows all three levels at once:

skill-creator/
├── SKILL.md          # frontmatter + instructions (Levels 1-2)
├── references/
│   └── best-practices.md   # loaded only when needed (Level 3)
├── scripts/
│   └── init_skill.py       # executable, zero tokens until run (Level 3)
└── assets/
    └── template/            # files the skill scaffolds from (Level 3)

skill-creator’s frontmatter sets name: skill-creator and a description stating plainly what it does: interview the author and scaffold the structure. Anthropic’s own PDF-skill walkthrough shows the same pattern: a lean SKILL.md pointing to a bundled forms.md, read only when a task touches form-filling.

Getting that structure clean at the outset matters. The first systematic study of SKILL.md as a software artifact, a 238-skill arXiv analysis by Hong, Imani, and Ahmed (2026), found over 99% of real-world SKILL.md files contain at least one “skill smell,” a violation that, per co-author Iftekhar Ahmed, Associate Professor of Informatics at UC Irvine, “rarely disappear as skills evolve” once introduced. A clean structure like skill-creator’s is worth building from the start; for the step-by-step version, see how to write an Agent Skill.

---

When should you write a SKILL.md?

Permalink to “When should you write a SKILL.md?” #

Not every reusable instruction belongs in a skill. The format is built for stable, repeatable knowledge, not data that changes invocation to invocation.

Skill-worthy knowledge is a procedure that holds steady across runs: how to fill out a specific form, scaffold a new skill, structure a recurring report. A live account balance or this week’s on-call schedule is a different problem. As LlamaIndex frames it, that kind of volatile lookup belongs to an MCP connection or a tool call, not a skill’s static instructions. See Agent Skills vs MCP, Agent Skills vs tools, and why MCP matters for AI agents for the fuller breakdown.

---

How does Atlan approach governed context for Agent Skills?

Permalink to “How does Atlan approach governed context for Agent Skills?” #

Teams shipping their first Agent Skills often report the skill is “working”: it loads, follows the procedure, produces neatly formatted output, while the underlying answer can still be wrong, because the skill can’t know whether the table its bundled script just queried is stale, deprecated, or uncertified. Progressive disclosure was never designed to answer that.

Atlan is the context layer for AI: a governed source a skill’s bundled resources can point at instead of a static file an author copy-pasted once. Context Repos are versioned, bounded, portable units of context any agent can consume, the same shape as a skill’s references/ or scripts/ bundle, but with certification, versioning, and ownership attached. Context Bootstrapping auto-generates the same kind of semantic layer a skill author would otherwise hand-write into a references/schema.md. Because Context Repos are delivered over MCP, any compatible skill or agent can read from that same governed source instead of a frozen extract, whether the business context layer sits in a data engineering team’s stack or is scoped to a single agent’s domain.

Customers building on Atlan’s MCP server describe this shift below, in their own words: stop hand-copying a schema into references/, connect the skill to a governed one instead. That carries the portability skill engineering already promises one step further, from portable procedure to portable, trustworthy context.

---

Real stories from real customers: Governed context reaching AI agents

Permalink to “Real stories from real customers: Governed context reaching AI agents” #

---

SKILL.md solves the format problem, not the data problem

Permalink to “SKILL.md solves the format problem, not the data problem” #

SKILL.md’s mechanics are simple and thoroughly documented: two required frontmatter fields, three loading levels, a body, optional bundled resources. None of that is in dispute. As the format spreads past Claude into GitHub Copilot’s review flow, LangChain’s roadmap, and Arize’s evaluation workshops, the open question stops being how a skill loads a reference file and becomes whether that file is still true when it loads. Skill engineering makes the procedure portable; it was never built to certify the data the procedure runs on. For skills that touch real business context, that is the piece still missing, the question a governed context layer is built to answer.

---

FAQs about SKILL.md

Permalink to “FAQs about SKILL.md” #

1. What is SKILL.md?
   The required file inside every Agent Skill folder. It pairs a YAML frontmatter block, name and description are the only mandatory fields, with a Markdown body telling Claude what the skill does and how, plus optional bundled references, scripts, and assets files.

2. What’s the difference between a skill and an MCP server or a tool?
   A skill encodes a stable, repeatable procedure in Markdown. An MCP server or tool call retrieves live data or performs a discrete action at runtime. Skills answer how to do this; MCP and tools answer what the world looks like right now.

3. How does Claude decide which skill to load?
   Claude matches the task against every installed skill’s description field, since that field alone loads into every session. If it matches, the full body loads next, followed by any bundled files the task requires.

4. Do bundled scripts inside a skill count against the context window?
   No. Level 3 resources, references, scripts, and assets files, cost zero tokens until Claude specifically reads or runs them, which makes a skill’s bundled content effectively unbounded.

5. What’s the maximum length for the name and description fields?
   Name is capped at 64 characters, lowercase letters, numbers, and hyphens only. Description is capped at 1,024 characters and must state what the skill does and when to use it.

6. Is a SKILL.md file only for Claude?
   No. GitHub Copilot supports custom agent skills in its review flow, LangChain has an open request for native support, and Arize has run production workshops on Agent Skills. The format is becoming a cross-vendor standard, not a Claude-only mechanic.

---

Sources

Permalink to “Sources” #

1. Agent Skills, Claude Platform Docs, Anthropic. https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
2. Equipping agents for the real world with Agent Skills, Anthropic Engineering. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
3. From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills, arXiv. https://arxiv.org/abs/2607.01456
4. Agent Skills specification, agentskills.io. https://agentskills.io/specification
5. anthropics/skills GitHub repository. https://github.com/anthropics/skills
6. 8 Tips for Writing Agent Skills, Philipp Schmid. https://www.philschmid.de/agent-skills-tips
7. Skills vs MCP tools for agents: when to use what, LlamaIndex. https://www.llamaindex.ai/blog/skills-vs-mcp-tools-for-agents-when-to-use-what
8. First-party Agent Skills support in langchain, GitHub issue #38170. https://github.com/langchain-ai/langchain/issues/38170