What is SKILL.md?

SKILL.md meaning

`SKILL.md` is the core file of an Agent Skill, a packaged capability that Claude and other agents can load on demand. Anthropic introduced Agent Skills in late 2025. Each skill lives in its own folder, and the SKILL.md file inside defines what the skill does and when it should be used. It is a plain Markdown file, so it is easy to write, read, and version in Git.

A skill bundles instructions and optional supporting files, such as scripts or reference documents, behind a single Markdown entry point. This makes a reusable capability portable between projects and tools.

The two parts of a SKILL.md file

Every SKILL.md has two sections:

1. YAML frontmatter between `---` markers. This configures how the skill runs and, most importantly, when it activates.
2. Markdown body with the instructions, steps, and examples the agent follows once the skill is active.

In short: the frontmatter says HOW the skill is registered, and the Markdown body says WHAT the agent should do.

Required frontmatter: name and description

Two frontmatter fields are required:

• name must match the parent folder name.
• description tells the agent when to activate the skill, so it should clearly state the triggers and use cases.

---
name: pdf-tools
description: Extract text and tables from PDF files, fill forms, merge or split PDFs. Use when the user works with .pdf files.
---

# PDF Tools

## Instructions
1. ...

## Examples
...

Optional fields such as `allowed-tools` and `disable-model-invocation` let you control permissions and behavior.

How progressive disclosure works

SKILL.md is built around progressive disclosure. When an agent starts a session, it scans every skill directory but reads only the YAML frontmatter from each SKILL.md, building a lightweight catalog of available skills. That catalog goes into the agent's system prompt. The full Markdown body is loaded only when a skill is actually triggered. This keeps startup cheap while still giving the agent access to deep instructions when needed, which is why the description field matters so much.

Why SKILL.md is useful

Skills turn repeated, multi-step work into a reusable package. A good SKILL.md means you do not re-explain a workflow every time, the agent activates the right capability automatically, and the instructions stay in one reviewable file. Because it is Markdown with simple frontmatter, anyone on the team can read and improve it.

SKILL.md vs other agent files

CLAUDE.md gives whole-project memory, while SKILL.md packages a specific capability the agent loads only when relevant. AGENTS.md sets cross-agent project rules. They work together: project context in CLAUDE.md or AGENTS.md, reusable capabilities in skills. Compare them all in the AI agent instruction files guide.

How to create your own SKILL.md

Ready to build one? Our step-by-step tutorial covers the folder structure, naming rules, frontmatter, and a full working example: how to create a SKILL.md file.

Write SKILL.md with a live preview

Since SKILL.md is Markdown with YAML frontmatter, you can draft it in the Markdown Docs online editor to check the structure, or download Markdown Docs to edit it on Windows with autosave. See also common .md files for AI projects.

Related references

• Anthropic: Agent Skills overview official Agent Skills docs.
• Claude Code: Extend Claude with skills for using skills in Claude Code.