Anatomy of a SKILL.md File

Updated Aug 2026

The Two-Part Structure

Every skill is a single markdown file with YAML frontmatter and markdown body:

┌─────────────────────────────┐
│  ---                        │  ← YAML frontmatter start
│  name: my-skill             │
│  description: ...           │  ← Metadata (selection signal)
│  allowed-tools: Bash,Read   │
│  ---                        │  ← YAML frontmatter end
│                             │
│  # Instructions             │
│  Step 1: Do this...         │  ← Markdown body (execution instructions)
│  Step 2: Then this...       │
└─────────────────────────────┘

YAML Frontmatter: The Selection Signal

Required Fields

name (string, max 64 chars)

• Lowercase letters, numbers, hyphens only
• This becomes the invocation command: /my-skill or skill: "my-skill"
• Must be unique across all installed skills

name: browser-tests  # Good
name: Browser Tests  # Bad — no spaces or uppercase
name: browser_tests  # Bad — no underscores

description (string)

• THE critical field. Claude reads all skill descriptions to decide which skill matches user intent
• Must be specific enough to differentiate from other skills
• Should describe the capability, not the implementation

# Good — tells Claude when to use this skill
description: |
  Browser automation via CLI. Navigate pages, click elements,
  fill forms, take screenshots, extract text from web pages.

# Bad — too vague, overlaps with other skills
description: "Helps with web stuff"

# Bad — describes implementation, not capability
description: "Runs playwright-cli commands using the Bash tool"

Optional Fields

allowed-tools (comma-separated string)

• Tools the skill may use, temporarily granted during execution
• Without this, the skill inherits the session's current permissions
• Supports wildcards: Bash(git:*) allows only git commands

allowed-tools: Bash           # Can run any shell command
allowed-tools: Read,Write     # Can read and write files only
allowed-tools: Bash,Read,Write,Glob,Grep  # Full access

model (string)

• Override which Claude model executes the skill
• Useful for cost optimization (use Haiku for simple skills)

model: claude-haiku-4-5   # Cheaper, faster
model: claude-sonnet-5    # Balanced

version (string)

version: "1.0.0"

disable-model-invocation (boolean)

• When true, the skill can only be invoked explicitly (via /skill-name), never automatically

disable-model-invocation: true

Markdown Body: The Execution Instructions

The body is what Claude reads when the skill is invoked. It should be structured for an AI agent, not a human reader.

Best Practices

1. Lead with a one-line summary — What does this skill do?
2. List commands in a reference table — Quick lookup format
3. Show common patterns — The 80% use cases
4. Include tips — Gotchas the agent needs to know
5. Stay under 500 lines — Longer skills bloat context; use /references/ for details

Example: A Browser-Automation SKILL.md Structure

This is the shape of the SKILL.md that playwright-cli install --skills generates (and the same shape Vibium's vibe-check skill pioneered):

# Playwright CLI — Browser Automation Reference

The `playwright-cli` automates browsers via the command line.
Snapshots and screenshots are saved to .playwright-cli/ on disk.

## Commands

### Core
- `playwright-cli open <url>` — launch browser at a page
- `playwright-cli snapshot` — save page snapshot (YAML with element refs)
- `playwright-cli click <ref>` — click element by ref (e.g. e8)
- `playwright-cli fill <ref> "<text>"` — fill input by ref
...

### Common Patterns

**Read a page:**
​```sh
playwright-cli open https://example.com
playwright-cli snapshot   # then Read the snapshot file it names
​```

## Tips
- All actions auto-wait for the element to be actionable
- Take a snapshot after navigation before interacting — refs come from snapshots

This structure works because:

• The agent can scan the command table to find what it needs
• The patterns section provides copy-paste workflows
• The tips prevent common mistakes

Bundled Resources (Optional Directories)

Skills can include additional directories alongside SKILL.md:

/scripts/ — Executable Code

my-skill/
├── SKILL.md
└── scripts/
    ├── setup.sh          # Run once on install
    ├── validate.py       # Called by agent via Bash
    └── generate-report.sh

The agent invokes scripts via Bash: bash {baseDir}/scripts/validate.py

/references/ — Documentation the Agent Can Read

my-skill/
├── SKILL.md
└── references/
    ├── api-schema.json       # Loaded into context on demand
    ├── selector-patterns.md  # CSS selector cheat sheet
    └── error-codes.md        # Troubleshooting reference

The agent loads references via Read tool: Read {baseDir}/references/error-codes.md

This is progressive disclosure — SKILL.md is always loaded, but references are loaded only when needed.

/assets/ — Templates and Static Files

my-skill/
├── SKILL.md
└── assets/
    ├── report-template.html  # Referenced by path, not loaded into context
    └── logo.png

The CLI-Wrapping Skill Pattern

The best browser-automation skills are intentionally minimal — a single SKILL.md file with zero bundled resources:

skills/browser-automation/
└── SKILL.md    # ~100 lines. That's it.

This is a deliberate design choice:

• The CLI binary handles all complexity (browser management, actionability, protocol plumbing)
• The skill just needs to teach the agent the command interface
• No scripts needed because the CLI is the script
• No references needed because the SKILL.md itself is concise enough

This is the gold standard for CLI-wrapping skills: thin instruction layer over a capable binary. Vibium's vibe-check skill pioneered the pattern in 2025; Microsoft adopted it in 2026 — playwright-cli install --skills generates exactly this kind of file. The pattern outlived the question of which vendor's binary sits underneath, and it is portable across agents: the same SKILL.md works in Claude Code, Cursor, Gemini CLI, and Codex CLI.

How the Agent Uses the Skill at Runtime

Here's what happens when you say "Go to example.com and take a screenshot":

1. User: "Go to example.com and take a screenshot"

2. The agent reads available skills → finds the browser skill description matches

3. The agent invokes: Skill(skill="playwright-cli")

4. System injects SKILL.md content into conversation context

5. The agent now knows the full command surface

6. The agent executes via Bash:
   → playwright-cli open https://example.com
   → playwright-cli screenshot

7. The agent reports: "Done. Screenshot saved to .playwright-cli/screenshot.png"

The key insight: steps 1-5 happen transparently. The user never sees the SKILL.md. They just see the agent driving a browser.

Interview Talking Point

"Agent skills are a fundamentally different architectural choice from MCP servers. Where MCP adds tool schemas to the context window — often thousands of tokens per server — skills inject procedural knowledge as markdown. A browser-automation SKILL.md is about 100 lines that teach the agent an entire CLI command surface. Those same capabilities via MCP mean exposing dozens of tool definitions with JSON schemas, input validation, and response formats on every request. Skills are the 'recipes'; MCP is the 'kitchen equipment.' It's telling that Microsoft's own Playwright CLI ships a --skills flag now — the pattern won."