
Ask an AI coding agent to “add a feature” and it will happily guess at your build commands, your folder layout and your idea of done. Increasingly, teams answer those questions once, in plain Markdown files that sit in the repository next to the code. A file called AGENTS.md now appears in more than 60,000 open source projects, according to the AGENTS.md project site, and toolkits such as GitHub’s Spec Kit and AWS’s Kiro go further, turning Markdown specifications into the source of truth an agent builds from. This guide maps the file types that matter in 2026, what each one does, how to structure it, and a step-by-step, spec-driven workflow for building an AI agent of your own.
Always-on instruction files: the “README for agents”
The first family of files is loaded automatically at the start of a session. They hold the facts an agent should never have to rediscover.
- AGENTS.md. An open, tool-neutral format described as “a README for agents.” It lives at the repository root, with optional nested copies in subprojects; agents read the nearest file in the directory tree, so the closest one wins, and an explicit chat prompt overrides everything. There are no required fields: it is plain Markdown, and the spec site suggests sections such as project overview, build and test commands, code style, testing instructions and security considerations. The format is now stewarded by the Agentic AI Foundation under the Linux Foundation, and the site lists support from OpenAI Codex, Google Jules, Cursor, VS Code, GitHub Copilot’s coding agent, Devin and many others.
- CLAUDE.md. Claude Code’s memory file. Anthropic’s docs describe four scopes: a managed policy file deployed by IT, a personal
~/.claude/CLAUDE.md, a team file at./CLAUDE.mdor./.claude/CLAUDE.md, and a git-ignoredCLAUDE.local.md. Files can import others with@pathsyntax, and topic rules can sit in.claude/rules/with apathsfront matter field that limits them to matching files. A notable 2026 change: Claude Code now reads AGENTS.md directly when no CLAUDE.md exists, starting with version 2.1.277. - .github/copilot-instructions.md. GitHub Copilot’s repository-wide instruction file. The VS Code reference lists it alongside AGENTS.md as the project instruction files for the Copilot harness, and notes that neither needs front matter.
- GEMINI.md. Gemini CLI’s context file. The Gemini CLI docs describe a hierarchy: a global
~/.gemini/GEMINI.md, workspace files, and “just-in-time” files discovered when a tool touches a directory. All found files are concatenated, and/memory showdisplays the result. The file name is configurable, so a team can point Gemini CLI at AGENTS.md instead. Status note: for unpaid tier and Google One users, Google replaced Gemini CLI with Antigravity CLI on June 18, 2026, according to a banner on the same docs.
Scoped rules, reusable prompts, custom agents and skills
The second family loads only when relevant, which keeps the always-on context lean.
- *.instructions.md (GitHub Copilot and VS Code). Targeted instructions stored under
.github/instructions/. Optional YAML front matter supportsname,descriptionandapplyTo, a glob such astests/**/*.pythat ties the rules to matching files, per the VS Code reference. - *.agent.md (formerly *.chatmode.md). Custom agents bundle a role, a tool list and instructions, stored in
.github/agents/. Front matter carries fields such asname,description,toolsand optionalhandoffs. VS Code’s custom agent reference states that custom agents were previously called chat modes and that.chatmode.mdfiles should be renamed to.agent.md. - *.prompt.md. Reusable prompts in
.github/prompts/, invoked as slash commands. Status note: VS Code’s docs now say prompt files run only in the Local harness, which is deprecated and due for removal by February 2027, and recommend converting them to agent skills. - .cursor/rules/*.mdc. Cursor’s project rules. Cursor’s docs are explicit that rules must use the
.mdcextension; a plain.mdfile in that folder is ignored. Three front matter fields,description,globsandalwaysApply, decide whether a rule is always applied, attached by file pattern, chosen by the agent from its description, or used only when @-mentioned. Cursor also reads AGENTS.md, including nested copies. - SKILL.md. The entry point of an Agent Skill: a folder holding a
SKILL.mdplus optional scripts and reference files. Anthropic’s skills docs describe YAML front matter (withdescriptionrecommended so the agent knows when to load the skill) followed by Markdown instructions. Only the description sits in context until the skill is used, and the docs advise keeping SKILL.md under 500 lines. Claude Code follows the open Agent Skills standard at agentskills.io, and custom slash commands have been merged into skills. - Kiro steering files. Markdown files in
.kiro/steering/, with defaults namedproduct.md,tech.mdandstructure.md, plus inclusion modes (always, fileMatch, manual, auto) set in front matter, per Kiro’s steering docs. - llms.txt. Not a repository file but a website one, and technically
.txt, yet written in Markdown. The llms.txt proposal, now at version 2, specifies an H1 with the project name (the only required part), a blockquote summary, optional detail, and H2 sections listing links to LLM-friendly Markdown pages, with an “Optional” section for skippable material. - README.md and CONTRIBUTING.md. Still the human front door. GitHub’s docs say a README should explain what a project does, why it is useful, how to start, where to get help and who maintains it, alongside contribution guidelines. AGENTS.md is designed to complement, not replace, these files.
Quick comparison
| File | Typical location | Read by | Structure |
|---|---|---|---|
| AGENTS.md | Repo root, nested folders | Codex, Cursor, Copilot, Jules, Kiro, Claude Code and others | Plain Markdown, no required fields |
| CLAUDE.md | Root, .claude/, ~/.claude/ | Claude Code | Markdown, @imports; rules use paths |
| copilot-instructions.md | .github/ | GitHub Copilot | Plain Markdown |
| *.instructions.md | .github/instructions/ | GitHub Copilot in VS Code | Front matter: applyTo, description |
| *.agent.md | .github/agents/ | VS Code, Copilot | Front matter: name, tools, handoffs |
| *.prompt.md | .github/prompts/ | VS Code Local harness (deprecated) | Front matter: agent, tools |
| *.mdc rules | .cursor/rules/ | Cursor | Front matter: description, globs, alwaysApply |
| GEMINI.md | ~/.gemini/, workspace | Gemini CLI | Markdown, @file imports |
| SKILL.md | .claude/skills/<name>/ | Claude Code and Agent Skills hosts | Front matter: name, description |
| llms.txt | Website root or subpath | Agents browsing the web | H1, blockquote, H2 link lists |
| constitution.md, spec.md, plan.md, tasks.md | .specify/memory/, specs/###-feature/ | Spec Kit with many agents | Template headings |
| requirements.md, design.md, tasks.md | .kiro/specs/<feature>/ | Kiro | EARS requirements, design sections, task list |
Spec-driven files: Spec Kit and Kiro
Instruction files tell an agent how to work. Spec files tell it what to build. GitHub framed the idea in its Spec Kit launch post: treat agents as “literal-minded pair programmers” and make the specification a living, executable artifact.
- constitution.md. Project-wide principles that every later phase is checked against, stored at
.specify/memory/constitution.md(see the Spec Kit upgrade guide). The template has Core Principles, additional sections and Governance. - spec.md. The what and why, not the tech stack. Spec Kit’s template uses prioritized user stories with acceptance scenarios, edge cases, numbered functional requirements, key entities, measurable success criteria and assumptions.
- plan.md. The how: technical context, a Constitution Check, project structure and complexity tracking, with companions
research.md,data-model.md,quickstart.mdandcontracts/in the samespecs/###-feature/folder. - tasks.md. A dependency-ordered list grouped into Setup, Foundational, one phase per user story and Polish, with parallel markers, per the Spec Kit command reference.
- Kiro’s requirements.md, design.md and tasks.md. Kiro writes requirements in EARS notation (“WHEN [condition] THE SYSTEM SHALL [behavior]”), a design document covering architecture, data flow, interfaces, error handling and testing strategy, and a trackable task list it can run in parallel waves, according to its Feature Specs docs. Specs live under
.kiro/specs/, one folder per feature.
Best practices that hold across tools
- Keep it short. Anthropic recommends under 200 lines per CLAUDE.md because longer files cost context and reduce adherence; Cursor suggests keeping rules under 500 lines and splitting large ones.
- Be concrete and verifiable. Write “Run
npm testbefore committing,” not “test your changes” (Anthropic). VS Code’s guidance is similar: name the command, directory or library to use. - Scope by directory or pattern. Use nested AGENTS.md files,
applyTo,globsorpathsso specialist guidance loads only where it applies. - Version control and review them. Cursor says to check rules into git; VS Code says to maintain instructions with the code; Kiro says to treat steering changes like code changes.
- No secrets. Kiro’s docs warn never to include API keys, passwords or sensitive data, since steering files are part of the codebase.
- Do not confuse guidance with enforcement. Anthropic notes CLAUDE.md is context, not enforced configuration; use permission settings or hooks for hard limits. VS Code adds that a “do not edit” line is not a permission boundary.
- Avoid duplication and conflict. Don’t restate what linters enforce, and pick one shared file (often AGENTS.md) with tool-specific files importing it.
A step-by-step spec-driven workflow for building an AI agent
The following sequence combines Spec Kit’s command flow (constitution, specify, clarify, plan, checklist, tasks, analyze, implement, converge) with Kiro’s approval gates, applied to an agent rather than an ordinary app.
- Set the constitution. Record non-negotiables: which tools may touch production, that a human approves irreversible actions, that every behavior change ships with an eval. In Spec Kit this is
/speckit.constitution. - Write the root instruction file. Add AGENTS.md (or CLAUDE.md importing it) with build, test and eval commands so the coding agent can verify its own work.
- Specify the agent. Describe users, jobs and outcomes in spec.md or Kiro’s requirements.md. Express each guardrail as a testable requirement (“The agent MUST NOT close tickets”).
- Clarify. Run
/speckit.clarify, which asks up to five targeted questions and writes the answers back into spec.md, or Kiro’s Analyze Requirements to catch ambiguity and gaps before design. - Plan. Now choose the model, framework, tool schemas, memory approach and data contracts in plan.md or design.md. The Constitution Check confirms the plan respects your principles.
- Check requirement quality.
/speckit.checklistproduces “unit tests for your requirements,” for example: is fallback behavior defined when a tool fails? - Break down tasks. Generate tasks.md: tool wrappers, prompt files, guardrail checks and an eval harness, each small enough to implement and test alone.
- Analyze for consistency.
/speckit.analyzeis read-only and flags a task with no matching requirement or a plan that contradicts the spec. Fix issues at their source. - Implement in stages. Run
/speckit.implementphase by phase for large features, reviewing focused diffs rather than one giant change. - Verify and evaluate. Run
/speckit.converge, which appends missing work to tasks.md until it reports “Converged,” then run your agent evals. Anthropic’s skills docs recommend comparing runs with and without a capability in fresh sessions; the same baseline habit works for whole agents. - Iterate through the spec. When behavior must change, update the spec first, regenerate the plan and tasks, and record recurring lessons in AGENTS.md or a skill.
Example skeletons
A compact spec.md for a triage agent, following Spec Kit’s template headings:
# Feature Specification: Support Ticket Triage Agent
## User Scenarios & Testing
### User Story 1: Auto-triage a new ticket (Priority: P1)
A support lead wants every new ticket labeled and routed
within two minutes so urgent issues reach the right queue.
Acceptance scenarios:
1. Given a new ticket mentioning an outage,
When the agent runs, Then it is tagged "urgent" and routed to on-call.
### Edge Cases
- Ticket text is empty or in an unsupported language
- The ticketing API is unavailable
## Requirements
### Functional Requirements
- FR-001: The agent MUST read tickets through the read-only search tool.
- FR-002: The agent MUST NOT close or delete tickets.
- FR-003: The agent MUST ask a human when confidence is below the set threshold.
- FR-004: [NEEDS CLARIFICATION: which languages are in scope?]
### Key Entities
- Ticket, Label, Queue
## Success Criteria
### Measurable Outcomes
- SC-001: 90% of tickets in the eval set get the correct label.
- SC-002: Zero tool calls outside the approved tool list in eval runs.
## Assumptions
- Ticket history for evals is anonymized before use.
A matching AGENTS.md that gives the coding agent its commands and limits:
# AGENTS.md
## Project overview
Python service that runs the ticket triage agent.
Specs live in specs/; the constitution is in .specify/memory/constitution.md.
## Setup and commands
- Install: `uv sync`
- Unit tests: `uv run pytest tests/unit`
- Agent evals: `uv run python evals/run.py`
- Lint: `uv run ruff check .`
## Conventions
- Tools are defined in src/tools/, one file per tool, each with a schema.
- Prompts live in src/prompts/ as versioned Markdown files.
## Guardrails
- Never add a tool that writes to production without an approved spec.
- Never put API keys or tokens in code, prompts or this file.
## Before you finish
- Run unit tests and evals; both must pass.
- Update tasks.md checkboxes for completed tasks.
The takeaway
The file names differ by vendor, but the pattern has converged: a short, always-on instruction file; scoped rules and skills that load on demand; and versioned specs that say what to build before any code is written. Start with one AGENTS.md, add a spec for your next agent feature, and let the review of those Markdown files become part of how your team ships.
Sources
- AGENTS.md: a simple, open format for guiding coding agents, AGENTS.md / Agentic AI Foundation
- How Claude remembers your project, Anthropic Claude Code Docs
- Extend Claude with skills, Anthropic Claude Code Docs
- Use custom instructions in VS Code, Microsoft
- Custom instructions reference, Microsoft VS Code
- Custom agents in VS Code, Microsoft
- Custom agent file reference, Microsoft VS Code
- Use prompt files in VS Code, Microsoft
- Rules, Cursor Docs
- Provide context with GEMINI.md files, Google Gemini CLI
- The /llms.txt file, v2, Answer.AI (Jeremy Howard)
- About the repository README file, GitHub Docs
- Spec Kit repository, GitHub
- Agentic SDD command reference, GitHub Spec Kit Docs
- Upgrade guide, GitHub Spec Kit Docs
- Spec-driven development with AI: Get started with a new open source toolkit, The GitHub Blog
- Specs, Kiro Docs
- Feature Specs, Kiro Docs
- Steering, Kiro Docs