Your AI coding agent can write a React component in seconds. But does it know your project’s coding rules, how to perform a complex task, or what your interface should look like?
That is where three increasingly useful files enter the picture: AGENTS.md, SKILL.md, and DESIGN.md.
They may all contain instructions for AI, but they solve different problems. Understanding the difference can help you build applications with fewer repeated prompts, more consistent interfaces, and coding agents that follow your project's conventions.
1. what is AGENTS.md?
Think of AGENTS.md as the instruction manual for an AI coding agent working inside your repository.
It tells the agent how your project works, which commands to run, what conventions to follow, and which constraints matter. The open format is supported by a growing ecosystem of coding tools, including OpenAI Codex, Google's Jules, and other compatible agents. <Cite refs={["turn398327view0"]}/>
For example, your file might contain:
# Project Instructions
## Development
- Use TypeScript.
- Follow existing component patterns.
- Use pnpm for package management.
## Testing
- Run pnpm test before finishing.
- Run pnpm lint after changing files.
## Rules
- Never commit API keys.
- Avoid unrelated refactoring.
Now, instead of repeating these instructions in every conversation, you can keep them in the repository.
When should you use it? Use AGENTS.md for persistent project guidance that agents need to follow across different tasks.
One important detail: instructions only help when the coding tool actually reads and follows the file. Check your agent's documentation to understand how it discovers instructions and resolves conflicts.
2. what is SKILL.md?
SKILL.md serves a different purpose. It teaches an AI agent how to perform a particular task or follow a reusable workflow.
Imagine that you frequently ask an agent to create API endpoints, write database migrations, review pull requests, or integrate a specific SDK. Instead of explaining the entire procedure every time, you can package the relevant expertise into a skill.
The Agent Skills specification describes a format built around a SKILL.md file containing metadata and instructions. A skill can also include scripts, reference documents, and other supporting resources. <Cite refs={["turn472086search6"]}/>
For example:
---
name: api-development
description: Build and test API endpoints
---
# API Development
1. Inspect existing API conventions.
2. Validate request parameters.
3. Handle errors consistently.
4. Add relevant tests.
5. Verify the endpoint before finishing.
Compatible agents can use the skill when a task matches its description, depending on how that agent implements skill discovery.
The useful idea is that you do not need to load every detailed workflow into every conversation. Skills can provide specialized instructions when they are relevant.
When should you use it? Use SKILL.md when you want to teach an agent a repeatable procedure or give it specialized knowledge for a particular kind of work.
3. what is DESIGN.md?
Now imagine your AI agent builds a dashboard. The functionality works, but every page uses different button styles, spacing, typography, and colors.
The problem is not necessarily the code. The agent may lack a clear description of your design system.
DESIGN.md addresses this by describing visual design rules in a format that coding agents can use. Google's experimental format, developed through Google Labs, covers design tokens and guidance such as colors, typography, layouts, and component patterns. <Cite refs={["turn472086search2","turn472086search3"]}/>
A simplified example might look like this:
# Design System
## Colors
- Primary: #2563EB
- Background: #FFFFFF
- Text: #111827
## Typography
- Headings: Inter, semibold
- Body: Inter, regular
## Components
- Buttons use consistent padding.
- Cards use a shared border radius.
- Forms display clear validation errors.
A real DESIGN.md following Google's format may use structured front matter and more specific design tokens. The example above illustrates the idea rather than the complete specification.
The goal is to give AI a shared visual reference instead of making it invent styling decisions for every new component.
When should you use it? Use DESIGN.md to document the visual rules your AI-generated interfaces should follow. Remember that support and automatic discovery depend on the coding tool and its configuration.
4. what is the difference between AGENTS.md, SKILL.md, and DESIGN.md?
Here is the easiest way to remember their roles.
| File | Main purpose | Example question it answers |
|---|---|---|
AGENTS.md | Project instructions | How should I work in this repository? |
SKILL.md | Reusable task expertise | How should I perform this kind of task? |
DESIGN.md | Visual design guidance | How should this interface look? |
Consider building a settings page for an existing application.
AGENTS.md tells the agent to use TypeScript, follow the existing architecture, and run the project's tests.
SKILL.md provides a reusable workflow for building and verifying accessible React forms.
DESIGN.md specifies the colors, typography, spacing, and component styles the page should follow.
Together, they address three different questions: how to work in the project, how to perform the task, and how the result should look.
They complement one another rather than replacing one another.
5. do you need all three files in every project?
No. Adding more instruction files does not automatically make an AI coding agent better.
For a small personal project, a concise AGENTS.md might be enough. If you repeatedly perform specialized tasks, adding skills may save time and improve consistency. If your application has a defined visual identity, DESIGN.md can help keep generated interfaces aligned with it.
The important thing is to solve an actual problem.
Avoid copying large instruction files from unrelated repositories without checking whether their rules apply to your project. Outdated commands, contradictory guidance, and irrelevant requirements can confuse agents instead of helping them.
Also, do not assume every agent automatically recognizes all three formats. AGENTS.md has broad ecosystem adoption, Agent Skills has its own specification, and Google's DESIGN.md format is still evolving. Check the relevant tool's support before relying on automatic discovery.
6. how should you organize these files?
Start with the information that has the widest application, then add specialized guidance only when necessary.
A simple project might look like this:
my-app/
├── AGENTS.md
├── DESIGN.md
├── src/
└── skills/
└── api-development/
└── SKILL.md
This is an illustrative structure, not a universal convention. Many tools expect skills in specific directories, so follow the directory structure documented by your chosen agent.
Keep project-wide instructions concise. Put reusable task procedures in skills, and keep design guidance focused on visual decisions. If your repository has multiple applications or packages, consider scoped instructions where the tool supports them.
Most importantly, keep these files under version control. That lets your team review changes, discuss conventions, and improve the guidance as the project evolves.
7. the bigger idea: make your project easier for AI to understand
These files represent a broader shift in software development. Developers are increasingly describing not only what software should do, but also how AI systems should work within an existing project.
That does not mean Markdown files replace tests, source code, design tools, or engineering judgment. They provide context and instructions that complement those existing systems.
A well-written AGENTS.md cannot guarantee correct code. A SKILL.md cannot guarantee that every workflow succeeds. A DESIGN.md cannot guarantee a pixel-perfect interface in a tool that does not support it.
Their value comes from reducing ambiguity and making important decisions easier to discover.
The best setup is not the one with the most files. It is the one that gives an AI agent the right guidance at the right time.
"AGENTS.md tells AI how to work. SKILL.md teaches it how to perform a task. DESIGN.md shows it how your interface should look."