CLAUDE.md and YAML: Which Files Use Frontmatter?
CLAUDE.md is plain Markdown with no required YAML frontmatter. Here is what YAML does in AI tool configs and content files, and where each type of instruction belongs.
Updated 6 min read
CLAUDE.md is a plain Markdown file with no required YAML frontmatter and no enforced schema. You write it in natural language and structure it with headings. It does not need a title key, a date field, or a block of dashes at the top. Claude Code reads the whole file as instructions, not as a document with metadata.
The confusion is understandable: many content systems require YAML frontmatter in Markdown files, and some AI tools use YAML files for configuration. Tools like fenbs store prompt templates as plain text in a shared library that any connected assistant can read, which sidesteps the question of which file format to use for shared instructions. This page explains where each format actually appears.
What CLAUDE.md looks like in practice
A CLAUDE.md file is Markdown with headings and short paragraphs. Claude Code reads it as context at the start of a session. There is no published schema, no required front matter, and no validation step. You can use level-two headings to organize sections — Project overview, Commands, Rules, What not to do — or write a flat list of instructions. Both work.
The only rule is that the file must be at the right path — usually the project root, the user home directory, or a parent directory Claude Code inherits from. The CLAUDE.md examples guide shows how different teams structure their files. None of them require YAML.
Where YAML does appear in AI tooling
Several places in the AI tools ecosystem do use YAML, and it is easy to mix them up with CLAUDE.md. Knowing which file is which helps you write the right format in the right place.
| File or context | Format | Purpose |
|---|---|---|
| CLAUDE.md | Plain Markdown (no YAML) | Project instructions Claude Code reads at session start |
| GitHub Actions workflow | YAML (.yml or .yaml) | CI/CD pipeline definition read by GitHub, not by Claude Code |
| MkDocs or Jekyll page | Markdown with YAML frontmatter | Content metadata (title, date, layout) read by the site generator |
| OpenAI plugin or action schema | YAML (OpenAPI spec) | Describes API endpoints for a ChatGPT plugin or custom action |
| Claude Code skill definition | Plain text or Markdown | A reusable instruction file invoked by name, no schema required |
If you write a GitHub Actions workflow to run tests or deploy your project, that YAML file is read by GitHub, not by Claude Code. You can ask Claude Code to help write or edit the YAML file, but the YAML syntax is for GitHub's benefit, not Claude Code's.
YAML frontmatter in content projects
Static site generators like Jekyll, Hugo, and Eleventy require YAML frontmatter in their Markdown files — the block of dashes at the top that holds the title, date, and layout fields. If your Claude Code project involves generating or editing those content files, your CLAUDE.md should describe the required frontmatter schema so Claude Code produces valid files.
The distinction here is clear: the frontmatter is in the content files Claude Code generates, not in CLAUDE.md itself. A rule like "Blog posts require frontmatter with title, date, and draft fields" belongs in CLAUDE.md as a plain Markdown instruction. The YAML stays inside the output files.
Should you add YAML frontmatter to CLAUDE.md anyway?
You can add a YAML-style block to CLAUDE.md as a convention for your own organization, and Claude Code will read it as part of the instruction text. But it provides no special benefit — Claude Code does not parse it as structured metadata or use the keys for anything. A plain Markdown heading is cleaner and easier to read.
One reason teams sometimes consider frontmatter is to add a version or last-updated date to their CLAUDE.md. That information is more reliably tracked in git commit history or in a fenbs context note than in an unvalidated field that could fall out of sync.
Keeping prompt templates where assistants can find them
A related question is where to store reusable prompt templates: the prompts you write once and want every assistant session to be able to use. Embedding them in CLAUDE.md works for a small set of short prompts, but a growing library becomes hard to maintain in a single file. An assistant reading a CLAUDE.md that is several hundred lines long may not reliably reach the prompts at the bottom.
fenbs's Skills and prompts library keeps those templates outside the CLAUDE.md, with each one named so a connected assistant can list available prompts and fetch the one it needs. That also makes it easy to update a prompt without editing every project's instruction file.
Keep prompt templates where every assistant can reach them
Add reusable prompt templates to the Skills and prompts library in fenbs. A connected assistant can list the available prompts and read the one it needs, without requiring you to copy the template into each project's CLAUDE.md. One update to the library reaches every session.
Create a free accountFree for one person · No credit card · Works with Claude, ChatGPT, Cursor and more
How to do this with fenbs
- Create a free account. Start a project and add your key instructions and prompt templates.
- Write your CLAUDE.md as plain Markdown with clear headings. No YAML frontmatter needed.
- Move reusable prompt templates to the Skills and prompts library in fenbs rather than pasting them into every CLAUDE.md.
- Connect Claude Code to fenbs from Integrations. Ask it to read the project context at the start of each session to pick up the current rules and available skills.
- If your project generates content files with YAML frontmatter, add the required schema to CLAUDE.md as a plain Markdown instruction so Claude Code produces valid output.
For a deeper look at where CLAUDE.md files can live and how they inherit from parent folders, see CLAUDE.md examples and does Claude Code read AGENTS.md.