The Markdown files of the AI era

A project used to have one kind of reader: people. The README told them how to run it, the code told them how it worked, and the rest lived in someone’s head. Now an AI agent reads the project too, every time it’s asked to change something, and it starts each session knowing nothing about it: not the conventions, not the taste, not the things that were tried and dropped.

Think of it as a new engineer joining the team, every morning. They can code; what they don’t know is this project: how to run the tests, which files not to touch, which component library the buttons come from. You’d tell a new hire once. Telling the agent again in every request is the thing these files stop.

They’re close to prompt engineering: a prompt you keep sharpening the same way (“…and use our component library”) is a line that belongs in a file, so it’s there on every task without being typed. And they’re part of what’s now called context engineering: deciding what the model has in front of it when it works. Some files are in front of it always, some load only when a task needs them; which is which is most of this piece. Together they’re sometimes called agent specifications.

So projects grew a handful of Markdown files written for that reader. They look alike, and they’re easy to mix up, but each one is read by a different reader at a different moment. The demo at the top is the whole argument in one switch: the same request, answered from a vague file and from a specific one. The agent didn’t get smarter. It got told.

• README.md: people, when they first open the project. How to install it, run it, deploy it.
• CLAUDE.md / AGENTS.md: the agent, at the start of every session. The project’s standing rules.
• DESIGN.md: the agent (and designers) whenever the work touches what users see. The design system, in words.
• SKILL.md: the agent, only when a task matches the skill’s description. A procedure for one kind of job.
• Rules files (Cursor’s .cursor/rules, Copilot’s .github/copilot-instructions.md): the same idea as CLAUDE.md, for other tools.
• Memory: the agent, across sessions and projects. Facts it learned about you along the way.

The question to ask of any rule is who needs this, and when? Try it:

This is the one that matters most, because it’s read at the start of every session, whatever the task. CLAUDE.md is Claude Code’s name for it; AGENTS.md is the same idea as an open convention that many coding tools read. You can keep both in step by having one import the other: this site’s CLAUDE.md starts with @AGENTS.md.

Because it’s read every time, every line costs something, so the rule is: only what the agent can’t work out by reading the code.

There’s some evidence for both halves of that. Google’s developer video on these files cites a benchmark the Agentic AI Foundation ran in July 2026: on loosely defined tasks, an AGENTS.md made the runs quicker, cheaper in tokens and smaller in their diffs. Not by speeding up every task, but by cutting the long tail where the agent gets lost, spinning on a build file that isn’t there. And the files that helped were short, about a dozen lines. This site’s is far longer, because it also holds the design rules a DESIGN.md would; the study is a fair argument for splitting them.

Where the file sits decides who it’s for. The one in the project is committed with the code, so the whole team, and every tool that reads it, works from the same rules. A personal one, in your home folder (~/.claude/CLAUDE.md for Claude Code), applies to every project you open and to no one else: “explain things with a diagram” goes there, “every change needs an integration test” goes in the project.

# Project

This is a Next.js app. Write clean, maintainable code.
Follow best practices. Make the UI look good.

# Working together
- Don't commit or push: I review everything first.
- Check UI changes in the browser; say what you didn't check.

# Conventions
- Internal links use TransitionLink, never next/link.
- Every animated change uses a spring from ui/springs.js,
  picked by its job (press, swap, morph); never a new literal.
- Comments: only for a non-obvious why. No history in code.

The first says nothing the agent didn’t already assume. The second is full of things it couldn’t have guessed, and each comes with enough of a reason to apply it to cases the file never mentions. Write rules as decisions, this, not that, not adjectives like “clean” or “modern”. And when you correct the agent twice about the same thing, that correction is a missing line in this file. The case study’s last detail shows how this site’s grew that way.

An agent asked to build some UI with no design system to go on builds the average: the look of every tutorial it has read. Gradients, emoji, rounded everything, two buttons where one would do. That’s the left card in the demo at the top. A DESIGN.md is the design system written down for it: not a style guide for people to browse, but the decisions an agent needs to make the same choices you would.

It now has a shape: Google Labs publishes DESIGN.md as an open specification (still marked alpha). The file opens with YAML front matter holding the tokens: colors, typography, rounded, spacing, components, as real values. Then come prose sections in a set order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts. The prose refers back to the tokens by name, {colors.accent}, and a command-line tool lints the file (broken references, contrast) and exports the tokens to Tailwind.

The prose is the part that matters most; the tokens are there to support it. An Overview that paints a picture does more than any hex value: Google’s own example describes a graduate lecture handout from an old university, and an agent that reads that knows not to add sparkles. Build one:

---
version: alpha
name: Editorial
colors:
  neutral: "#0b0b0b"
  accent: "#d2633d"
typography:
  title:
    fontFamily: EB Garamond
    fontSize: 40px
    lineHeight: 1.1
  body:
    fontFamily: Roboto
    fontSize: 16px
    lineHeight: 1.6
rounded:
  md: 8px
---

## Overview
A quiet, editorial interface, like a well-set printed essay: generous margins, few colours, type doing the work.

## Colors
{colors.accent} (ember) is only for the active state and the one thing that matters on a screen. Everything else is {colors.neutral} and white at 100 / 75 / 50%.

## Typography
A serif ({typography.title}) for titles, a sans ({typography.body}) for copy. Never lighter than 400 below 18px.

## Shapes
{rounded.md} on cards and buttons; a nested corner is the outer one minus its padding.

## Motion
Springs with no bounce, under 300ms; nothing moves on its own. Respect prefers-reduced-motion: fade instead of move.

## Do's and Don'ts
- No gradients behind text
- No emoji as icons

• A picture first: the Overview in a sentence or two, something the agent can imagine, not “modern and clean”.
• Tokens with values: the colour, the type, the radius, as numbers it can use, not “a warm accent”.
• Rules with reasons: “the accent is only for the active state” lets it decide about a button the file never mentions.
• Motion, too: the spec has no section for it, but unknown sections are kept, so add one: durations, springs, what moves and what never does.
• Do’s and Don’ts: the defaults you’re steering away from. Short, and blunt.

Some knowledge is only needed now and then: how to write a release note, how to audit the animations, how to generate a logo from a font. Put it in CLAUDE.md and it’s read on every task, mostly for nothing. A skill is a folder with a SKILL.md in it, and the agent only reads the whole of it when a task calls for it.

---
name: release-notes
description: Writes release notes from merged pull requests. Use when
  the user asks for release notes, a changelog or "what shipped".
---

1. List the PRs merged since the last tag.
2. Group them by area; one line each, under 80 characters.
3. Run scripts/check-links.sh on the result.

The description is what decides everything: it’s always visible to the agent, and it’s how the agent knows when to open the skill, so say what it does and when to use it. The body is the procedure. A skill can carry scripts for the steps that should be exact every time, and reference files it only reads when it needs them, so a large skill stays cheap until it’s used.

Skills aren’t only for code. Copy in a brand’s tone, a round of copy editing, a performance review: if it’s a prompt you’d write again, it can be a skill. And you don’t have to write them all: there are open collections of them, Google’s and Anthropic’s among them. Read one before you install it, as you would any dependency; it’s instructions your agent will follow. This site uses a few written by others (for motion, for interface details), each read first, and its own CLAUDE.md says where they win and where it does.

Other tools read their own files: Cursor reads .cursor/rules, where each rule can be scoped to the files it applies to, and GitHub Copilot reads .github/copilot-instructions.md. The writing is the same as for CLAUDE.md; only the file name changes.

Memory is different: it’s written by the agent, not by you. When it learns something about you that will still be true next week (you want replies in English, you check phones on the deployed site, you never want a build run without asking), it keeps it, one fact to a note, and reads the list at the start of the next session. A memory worth keeping is about the person or the work, not about the code: the code already says that.

• One file, one job; ask who reads it, and when: setup for people goes in the README, standing rules in CLAUDE.md, the look in DESIGN.md, one-off procedures in a skill.
• One shared source: if the team uses different tools, keep one AGENTS.md and have the others import it, so no two say different things.
• Treat them as code: in the repo, reviewed, versioned, so everyone sees when a rule changes.
• Specific beats general: values, names, this, not that. An adjective tells the agent nothing it didn’t assume.
• A reason with every rule, so it can apply the rule to a case you didn’t write down.
• Short: whatever’s read every session costs something every session. Leave out what the code already says.
• Grow it from corrections: every time you correct the same thing twice, add the line.
• Prune it: a rule that stopped being true is worse than none.

Further: Google’s video on agent specifications (AGENTS.md, DESIGN.md and skills, with the study above), and the DESIGN.md specification itself.