SKILL.md Format Reference

Quick Answer: A SKILL.md is YAML frontmatter (only name and description are required) followed by markdown instructions. Optional fields include when_to_use, allowed-tools, disable-model-invocation, argument-hint, arguments, paths, model, and effort. Place the file inside a folder named after the skill at ~/.claude/skills/SKILL_NAME/SKILL.md.

This is the canonical reference for the SKILL.md file format used by Claude Code, OpenClaw, Codex CLI, and Cursor. Bookmark it.

How should a skill folder be structured?

~/.claude/skills/
└── my-skill/                  # Folder name = skill name
    ├── SKILL.md               # Required — the skill definition
    ├── scripts/               # Optional — executable helpers
    │   └── helper.sh
    ├── references/            # Optional — extra context files
    │   └── style-guide.md
    └── assets/                # Optional — images, templates
        └── logo.png

Only SKILL.md is required. Everything else is loaded on demand by the skill's instructions.

What fields go in SKILL.md frontmatter?

The frontmatter sits between two --- lines at the top of SKILL.md. Required fields are name (or folder name as fallback) and description. All other fields are optional.

What does a minimal SKILL.md template look like?

---
name: my-skill
description: One-sentence description of what this does and when Claude should use it.
---

# My Skill

Detailed instructions for Claude in markdown.

## When to use

Concrete trigger examples.

## How it works

Step-by-step procedure.

What does a standard SKILL.md template look like?

---
name: code-reviewer
description: Review staged git changes for security, logic, and style issues. Use when the user asks for a code review, PR review, or pre-commit check.
when_to_use:
  - User explicitly requests a code review
  - Before opening a pull request
  - After staging significant changes
allowed-tools:
  - Bash
  - Read
  - Grep
---

# Code Reviewer

Perform a structured review of staged changes.

## Procedure

1. Run `git diff --staged` to see the changes
2. Check for security issues (injection, secrets, auth bypasses)
3. Check for logic errors and missing edge cases
4. Suggest improvements organized by severity: Critical, Warning, Suggestion

## Output format

Group findings by file. For each finding, cite the line number and explain the impact.

What does a full SKILL.md template with optional fields look like?

---
name: env-doctor
description: Diagnose why a project fails to start by checking runtime versions, dependencies, env vars, ports, and build state.
when_to_use:
  - "Project won't start"
  - "Tests fail with environment errors"
  - "Newly cloned repo onboarding"
allowed-tools:
  - Bash
  - Read
  - Grep
paths:
  - "package.json"
  - "**/.env*"
  - "**/Dockerfile"
shell: bash
---

# Env Doctor

Systematic environment diagnosis. Read `references/checklist.md` for the full step list.

What are common SKILL.md mistakes?

• Tabs in YAML. YAML requires spaces — tabs throw parse errors.
• Folder name ≠ name field. Claude Code treats the folder name as canonical; mismatched values cause silent load failures.
• Vague description. "Helps with code" tells Claude nothing. "Reviews staged git changes for security and logic issues before commit" tells Claude exactly when to fire.
• Missing the closing ---. The frontmatter block must be opened and closed with --- on its own line.
• Markdown headers above frontmatter. Frontmatter must be the very first content in the file.

How do I verify my SKILL.md?

# Check YAML parses
head -20 ~/.claude/skills/my-skill/SKILL.md

# In Claude Code:
# /skills    → confirms the skill loaded
# Then ask Claude to invoke it by description

What should I do next?

• How to install skills in Claude Code
• What is SKILL.md? — conceptual overview
• How to add skills to Claude