What is SKILL.md? A Complete Guide to Claude Skill Files

SKILL.md is the file format that powers Claude Skills — the portable instruction system that gives Claude specialized expertise on demand. If you have used Claude Desktop, Claude Code, or Cowork, you may have already benefited from skills without knowing the format behind them. This guide explains everything about how SKILL.md files work.

The Basics of SKILL.md

A SKILL.md file is a plain Markdown file with a specific structure that Claude understands. At its core, it contains two parts: a YAML frontmatter block at the top (enclosed by triple dashes) and the instruction body below. The frontmatter provides metadata that helps Claude identify and categorize the skill. The body contains the actual instructions, guidelines, examples, and constraints that shape Claude's behavior for that particular domain.

Frontmatter Fields Explained

The frontmatter section defines key metadata about your skill. The name field gives the skill a human-readable identifier. The description field provides a brief summary of what the skill does, which Claude uses to determine relevance. Some skills also include an author field and a version field for tracking changes over time.

The optional triggers field is particularly important. Triggers are patterns or keywords that hint to Claude about when this skill should be activated. For example, a testing skill might have triggers like "write tests", "test coverage", or "unit test". While Claude can detect relevance without explicit triggers, well-defined triggers improve reliability.

The Instruction Body

Below the frontmatter, the instruction body is where the real content lives. This section is written in standard Markdown and should be organized with clear headers, lists, and sections. Claude reads this content and uses it as contextual guidance during conversations. Think of the instruction body as a detailed brief for a skilled professional — it should be specific enough to produce consistent results but flexible enough to handle varied situations.

Effective instruction bodies typically include an overview of the skill's purpose, specific guidelines and conventions to follow, examples of expected input and output, common pitfalls to avoid, and constraints or boundaries for the skill's scope. Using Markdown formatting like headers, bold text, code blocks, and lists helps Claude parse and apply the instructions accurately.

How Claude Reads Skills

When you start a conversation with Claude, it scans the available skill directories for SKILL.md files. The frontmatter metadata and triggers help Claude decide which skills are relevant to the current conversation context. Once a skill is activated, Claude incorporates the instruction body into its reasoning process, using the guidelines to shape its responses. Skills do not replace Claude's general capabilities — they augment them with specialized knowledge and structured approaches.

Where SKILL.md Files Live

SKILL.md files can be placed in two primary locations. User-level skills go in ~/.claude/skills/ and are available across all your projects and conversations. Project-level skills go in .claude/skills/ at your project root and are scoped to that specific project. Project-level skills are ideal for team conventions because they can be committed to version control and shared automatically with every developer who works on the project.

Best Practices for SKILL.md Files

Keep your SKILL.md files focused on a single domain or task. A skill that tries to do everything will be less effective than one that does one thing well. Use descriptive frontmatter so Claude can accurately identify when the skill is relevant. Structure your instructions with clear hierarchy — overview first, then specifics, then examples. Test your skill across multiple scenarios before sharing it. And keep the file size reasonable — concise, well-organized instructions consistently outperform verbose, rambling ones.