Skill File Anatomy

Every skill is defined by a Markdown file with YAML frontmatter. This pattern is shared across agent platforms — Claude Code uses SKILL.md, Cursor and Windsurf use .mdc rule files, and Copilot uses instruction Markdown. Regardless of the platform, the structure is the same: metadata on top, instructions below. Let's break down every part.

Directory Structure

Skills typically live inside a named directory. The directory name often becomes the skill's identifier (e.g., a slash command in Claude Code). The only required file is the skill Markdown file itself, but you can include supporting files alongside it:

The skill file is the entry point the agent reads. Any sibling files can be referenced from within the instructions, acting as templates, examples, or reference material.

The Two Sections

A skill file has exactly two sections: the frontmatter and the body.

Frontmatter (YAML)

The frontmatter is a block of YAML between two lines of three dashes. It provides metadata that the agent reads during discovery, before loading the full skill. The most important field is description, which tells the agent when this skill is relevant.

Body (Markdown)

Everything below the closing --- is the instruction body. This is free-form Markdown that the agent reads as a prompt. You can use headings, lists, code blocks, emphasis — anything that helps communicate your instructions clearly.

A Complete Annotated Example

Here is a full skill file with annotations explaining each part:

---
# FRONTMATTER — metadata the agent reads during discovery
description: Create a new React component with tests and Storybook story
allowed-tools:
  - Bash(npm run*)       # allow running npm commands
  - Read                 # allow reading existing files
  - Edit                 # allow editing files
  - Write                # allow creating new files
---

# BODY — instructions the agent follows when the skill is invoked

## Overview

Create a new React component following our project conventions.
The component name is provided as the first argument: $1

## Steps

1. **Create the component file** at `src/components/$1/$1.tsx`:
   - Use a named export (not default)
   - Define props as an interface named `$1Props`
   - Use our standard import order: React, libraries, local modules

2. **Create the test file** at `src/components/$1/$1.test.tsx`:
   - Use React Testing Library
   - Include at least a render test and an interaction test
   - Read `./example.test.ts` for our test patterns

3. **Create the Storybook story** at `src/components/$1/$1.stories.tsx`:
   - Export a default meta and at least two story variants
   - Use the CSF3 format

4. **Create the barrel export** — add an export line to `src/components/index.ts`

## Conventions

- All components use Tailwind CSS for styling (no CSS modules)
- Props interfaces are always exported
- Components must be accessible (proper ARIA attributes)
- File names use PascalCase to match the component name

How Agents Read It

Understanding the reading process helps you write better skills:

1. Phase 1: Description scan — When the agent starts, it scans all skill directories and reads only the description field from each skill's frontmatter. These short descriptions are held in context so the agent knows what skills exist.
2. Phase 2: Full load — When you invoke a skill (via slash command, rule trigger, or explicit reference), the entire file is loaded. The frontmatter fields configure behavior (like tool permissions), and the body becomes the agent's working instructions.
3. Phase 3: Execution — The agent processes the body top to bottom, treating it as a detailed prompt. It follows the steps, uses the permitted tools, and substitutes variables like $1 and $ARGUMENTS with actual values.

Writing Effective Skill Bodies

The body is where most of the value lives. Here are guidelines for writing instructions that agents follow reliably:

• Be explicit about steps. Numbered lists work better than prose paragraphs. Agents follow numbered steps sequentially.
• Specify file paths. Use exact paths rather than saying "create a file in the appropriate place." Agents follow precise instructions more accurately than vague ones.
• Include examples. If you want output in a specific format, show a concrete example. Agents will pattern-match against it.
• State negative constraints. If there are things the agent should not do, say so explicitly. "Do NOT modify existing tests" is more effective than hoping it will leave them alone.
• Reference sibling files. Instead of inlining long templates, put them in separate files and instruct the agent to read them. This keeps the skill file focused on logic.

What's Next

You now understand the overall structure of a skill file. The next lesson goes deep on every available frontmatter field — what each one does, when to use it, and practical examples.