Frontmatter is a small block of settings at the very top of a markdown file, fenced by two --- lines. Everything above the second --- is configuration; everything below it is the normal text. Claude Code uses this one format for most of its markdown-based extensions: a skill, a subagent or a rule is a markdown file, and its frontmatter tells Claude Code how and when to use it. Once you can read frontmatter, you can read and write all of them.
How it looks
A subagent file in .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Look at the changed files and give
specific, actionable feedback.The part between the --- lines is YAML, a plain text format for settings: one key: value per line, and lists either as a, b, c on one line or as - item lines below the key. Here name and description say what the subagent is and when to use it, tools limits what it can do, and model picks the model it runs on. The text after the closing --- is the subagent’s instructions.
Where Claude Code reads it
Each file type has its own set of fields. The ones you meet most often:
| File | Where it lives | Typical fields | What the body is |
|---|---|---|---|
| Skill | .claude/skills/<name>/SKILL.md | description, allowed-tools, model, effort, paths | Instructions Claude follows when the skill runs |
| Subagent | .claude/agents/<name>.md | name, description, tools, model, effort | The subagent’s own system prompt |
| Rule | .claude/rules/<topic>.md | paths | Instructions loaded next to CLAUDE.md |
| Auto memory note | ~/.claude/projects/<project>/memory/ | type, modified | The note itself |
| Output style | .claude/output-styles/<name>.md | name, description, keep-coding-instructions | Instructions that change how Claude responds |
A rule shows why this matters. Without frontmatter, it loads into every session like CLAUDE.md. With a paths field, it loads only when Claude works on a matching file, so it costs no context the rest of the time:
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates its inputIn auto memory, Claude writes the frontmatter itself: type records what kind of note it is, and Claude Code adds a modified time when it updates a file that already has frontmatter.
Why it matters
Frontmatter is the settings, and the body is the prompt. The fields are read by Claude Code, not by the model: model: haiku on a subagent really runs it on Haiku, and paths really keeps a rule out of context. The body is text the model reads and tries to follow, with no guarantee. When you want something to happen for sure, look for a field that does it rather than writing “please use Haiku” in the body.
Gotchas
- The opening
---must be the first line. With anything above it, even an empty line or a heading, Claude Code does not see frontmatter at all and treats the whole file,---lines included, as plain text. - Typos fail silently. Claude Code ignores a field it does not recognize, with no error.
modle: haikujust does nothing, and the subagent runs on the main conversation’s model. - Broken YAML fails quietly too. A skill whose frontmatter does not parse still loads, with no fields set.
- Field names differ between file types. Skill fields use lowercase words with hyphens (
allowed-tools,disable-model-invocation), while multi-word subagent fields use camelCase (disallowedTools,permissionMode). Check the reference for the file type you are writing. - Only some fields are required. A subagent needs
nameanddescription. In a skill every field is optional, but without adescriptionClaude falls back to the first line of the body to decide when to use it, so write one.
Related
- CLAUDE.md: the instructions file that rules sit next to.
- Auto memory: memory notes that carry their type in frontmatter.
- Context window: what path-scoped rules and on-demand skills keep out of it.