Skip to content

What is AGENTS.md?

AGENTS.md: AGENTS.md is a Markdown file in a repository that tells AI coding agents how to work in it: setup, commands, conventions and rules to follow.

AGENTS.md is a README for coding agents. A README explains a project to people; AGENTS.md holds the instructions an agent needs and a person would find noise: which commands build and test the code, which conventions the codebase follows, what to never do. It is plain Markdown with no required fields, and it lives at the repository root. Codex, Cursor, GitHub Copilot, Gemini CLI, Jules, Amp, Windsurf and other agents read it at the start of a session.

What to put in it

  • Commands: how to install, run, test and lint, exactly as typed.
  • Conventions: file layout, naming, the component library and how to import from it.
  • Rules with reasons: "semantic tokens only, because dark mode depends on them" is followed more reliably than "use tokens".
  • Things that are not obvious from the code: generated files not to edit, framework versions with breaking changes, where the docs live.

Keep it short and specific. Every line is read on every task, and a rule an agent cannot act on costs context without changing the output. In a monorepo, put an AGENTS.md in each package; agents use the one closest to the file they are editing.

Claude Code and other file names

Some tools read their own file first: Claude Code reads CLAUDE.md, Cursor reads rules in .cursor/rules, GitHub Copilot reads .github/copilot-instructions.md. To keep one source of truth, write the rules in AGENTS.md and import it from the others. In Claude Code, a CLAUDE.md that contains the line @AGENTS.md pulls the whole file in.

CLAUDE.mdbash
@AGENTS.md

How MiniDev UI uses it

MiniDev UI publishes a ready block of rules at /AGENTS.md for you to paste into your own AGENTS.md or CLAUDE.md. It tells the agent to look components up before writing markup (in llms.txt, the per-component .md docs or the MCP server), how to install with the shadcn CLI or npm, and the house rules: semantic tokens only, the shadow and radius set, the 2px grid, spring presets with reduced motion, and focus rings that stay. The same rules ship as a Cursor rules file at /rules/minidev-ui.mdc and as a Claude Code skill at /skill/minidev-ui/SKILL.md. Setup for each agent is on Use MiniDev UI with AI agents.

AGENTS.md is guidance, not enforcement. Pair the rules with checks that fail the build, such as a lint rule against raw hex colors, for the ones that must never break.