What is STYLE.md

STYLE.md is a portable creative style specification you drop into a project. Any AI tool — a coding agent, an image model, or an LLM — reads it to understand how your work should look, sound, and feel.

This page explains the convention. For the exact file structure, see the Format reference.

The convention

A STYLE.md file lives in a project root, next to files like AGENTS.md and README.md. It’s the stylemd compilation of a StyleRef style: YAML frontmatter that names the style and its sections, followed by a Markdown body describing each section.

Because it’s a committed file, a project’s style travels with the repo. Every agent and teammate who opens the project reads the same style contract — no one re-explains the aesthetic in a prompt.

What it includes

• Frontmatter — the style name, a generator marker, the list of sections present, and a small signals block of machine-readable values.
• A Markdown body — one ## heading per style section (Colors, Typography, Mood, Voice & Language, and so on), each with a prose description.

What it deliberately does not include

STYLE.md exposes the style’s content and a minimal machine-readable surface. It does not carry StyleRef’s block taxonomy or extraction internals. It’s a spec for a project to follow, not a dump of the tool’s data model.

Relationship to AGENTS.md

AGENTS.md tells an agent how to work in a repo. STYLE.md tells it how the output should look and sound. They’re complementary: you reference STYLE.md from AGENTS.md with a single line, and the agent applies the style to everything it generates.

Next steps

• Format reference — the exact structure and rules.
• Add STYLE.md to a project — write one into a repo.
• Validate & lint — check a STYLE.md is well-formed.