SKILL.md Format Reference

This is a quick reference for the SKILL.md file format. If you're writing or editing skills for Claude Code, Codex, or other agents that support the Agent Skills standard, this page covers every field and pattern you need to know.

For a gentler introduction, read What Is SKILL.md? first.

File structure

A skill is a folder containing at minimum one file:

my-skill/
├── SKILL.md           # Required
├── scripts/           # Optional: executable helper scripts
├── references/        # Optional: additional docs loaded on demand
└── assets/            # Optional: templates, images, config files

The SKILL.md file has two parts: YAML frontmatter between --- markers, and markdown instructions below.

Frontmatter fields

Required fields

name (string): The skill's identifier. Becomes the /slash-command for manual invocation. Use lowercase with hyphens. Must be unique within the same skills directory.

name: code-reviewer

description (string): What the skill does and when to use it. This is the most important field. The agent reads it to decide whether to load the skill automatically. Include specific trigger phrases.

description: Reviews code for bugs, security issues, and style 
  violations. Use when the user asks for a code review, mentions 
  reviewing changes, or says "check this code."

Optional fields

context (string): Controls execution context. Set to fork to run the skill as a subagent with isolated context. Leave unset to run inline (shared context). Fork is better for skills that do substantial independent work.

context: fork

disable-model-invocation (boolean): When true, only the user can trigger the skill via /skill-name. The agent will never load it automatically. Use for skills with side effects.

disable-model-invocation: true

user-invocable (boolean): When false, only the agent can load the skill. The user cannot invoke it with a slash command. Use for background knowledge that isn't actionable as a command.

user-invocable: false

Markdown instructions

Below the frontmatter, write your instructions in standard markdown. The agent follows these when the skill is active.

Structure recommendations

Start with a heading matching the skill name. Follow with a clear statement of what the skill does. Then provide numbered steps for the workflow. Include output format specifications. Add edge case handling at the end.

Referencing supporting files

You can reference files in your skill's folder:

Load the style guide from references/style-guide.md before reviewing.
Run scripts/check_style.py on the target files.

The agent will read these files when it encounters the reference.

Skill storage locations

Personal skills at ~/.claude/skills/ are available in all projects.

Project skills at .claude/skills/ inside a repo are shared through version control.

Plugin marketplace skills are managed through Claude Code's /plugin system and stored in the plugin directory.

Best practices

Keep SKILL.md under 500 lines. Move detailed reference material to references/ files.

Write specific trigger descriptions. "Use when the user asks to review code or mentions PR review" is better than "helps with code."

Use numbered steps. Agents follow sequential instructions more reliably than unstructured prose.

Include output examples. Show what good output looks like so the agent has a concrete target.

Handle the "nothing found" case. Tell the agent what to do when the expected input doesn't exist. "If no test files are found, ask the user which testing framework to use."

Test both invocation methods. Check that /skill-name works and that automatic discovery triggers correctly.

For a hands-on tutorial, read How to Create Your Own SKILL.md. To see real examples, browse skills on Agensi.