# 04 Runtime context

> How tokens, meaning, and intent reach the agent at the moment it acts.

A great spec still needs a delivery mechanism that does not lock you to one vendor. That is what the runtime files do.

## Summary
- Three Markdown files run your repo's relationship with AI: AGENTS.md (how to build and test), SKILL.md (portable capabilities), and DESIGN.md (the visual system).
- This is the top of the stack, where tokens, meaning, and intent get delivered to the agent at the moment it acts.
- None of it is finished: the formats are young and agent-to-agent coordination is still open, but writing intent down beats hoping the agent guesses.

## The argument

Three files now run your repo's relationship with AI. Agents stopped guessing, because three Markdown files started telling them what they need. AGENTS.md says how to build and test the project. SKILL.md packs up capabilities the agent carries from project to project. DESIGN.md hands over your visual system so nothing drifts off-brand. Three files, plain Markdown, and the repo explains itself.

One thing people botch: these are not protocols. MCP is how an agent talks to a system. These files are what it needs to know about your project. Different job.

Why Markdown and not some clever format? Agents read it better than anything else, because it is most of what they trained on. And one file in one spot kills the scatter, no more rules spread across `.cursorrules`, `CLAUDE.md`, and whatever ships next week. That scatter is vendor lock-in.

This is the top of the stack, where the other three pillars get delivered. Tokens gave the values. Machine-readable systems gave the meaning. Spec-driven development gave the intent. Runtime context is how all of it reaches the agent at the moment it acts. Skip it and the agent scavenges for build commands, hallucinates one, and breaks your pipeline.

The fix is one rule everyone can follow: make AGENTS.md the single source of truth and point every tool-specific file at it instead of duplicating context everywhere.

None of this is finished, and that is worth saying plainly. The file names are converging, but they are young, and the harder problem past host-to-agent context, getting agents to coordinate with each other, is still unsettled. The bet is not that the format is done. It is that writing intent down in a file the agent can read beats hoping it guesses.

You do not make an agent reliable by making it smarter. You make it reliable by writing down what it needs in a file it can actually read. Three files, maintained once, used everywhere.

## Fact-checked claims
- These files are not protocols. MCP is how an agent talks to a system; AGENTS.md, SKILL.md, and DESIGN.md are what it needs to know about your project.
- Markdown is the common tongue because it is what these models were trained on. AGENTS.md is governed by the Agentic AI Foundation, DESIGN.md was formalized by Google Stitch, and SKILL.md was pioneered by Anthropic.

## Sources
- [The three context files](https://blog.agentailor.com/posts/top-ai-agent-standards-2026): AGENTS.md, SKILL.md, and DESIGN.md, the roundup in one place.
- [AGENTS.md](https://agents.md/): The AGENTS.md standard itself, the file that carries build and architectural intent. Now stewarded by the Agentic AI Foundation.
- [Anthropic on Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills): The SKILL.md format Anthropic pioneered: portable capabilities an agent carries between projects.
- [What DESIGN.md is](https://designmd.app/what-is-design-md/): What DESIGN.md is, plus a public library of ready-made design systems you can drop in.

## Questions to take to the notebook
- Why Markdown, and not a cleverer machine format?
- What is the difference between MCP and a context file like AGENTS.md?
- How do you stop rules from scattering across vendor-specific files?