to-agents-md

name	to-agents-md
description	Conducts a structured interview to create or update a repository's AGENTS.md file (the "constitution" in Spec-Driven Development) — stack, testing standards, repo conventions, workflow, and inviolable engineering principles for coding agents. ALWAYS use this skill when the user mentions creating or bootstrapping a new repository, setting up AGENTS.md or CLAUDE.md, defining a project "constitution", preparing a repo for AI-assisted or spec-driven development, or asks to document repository standards and guidelines for coding agents.
license	MIT

to-agents-md

Create a high-quality AGENTS.md at the root of a repository through a structured interview. AGENTS.md is the constitution of the repo in a Spec-Driven Development (SDD) workflow: the small, stable set of facts and principles that any coding agent (Claude Code, Cursor, Codex, etc.) should load before touching the code.

AGENTS.md is deliberately preferred over CLAUDE.md because it is the tool-agnostic de facto standard. At the end, offer to also generate a one-line CLAUDE.md pointing to it for compatibility:

Read AGENTS.md for repository guidelines.

The core discipline: constitution vs. spec

An AGENTS.md is not documentation and not a feature spec. Apply this litmus test to every piece of content, both what you draft and what the user proposes:

If the statement is still true after 10 new features ship, it belongs in the constitution. If it changes with the next feature, it belongs in a spec.

"We use pytest with 80% minimum coverage on domain logic" survives 10 features → constitution. "The system will have an invoice upload endpoint" is the subject of one feature → spec.

Domain invariants pass the test — but only when stated at the invariant level. A rule like "AI-produced verdicts are write-once; human review is recorded in separate fields" constrains every future feature and belongs in the constitution. But the same rule phrased as "never UPDATE the status_ia and comentario_ia columns" fails: column names are schema material with high churn, and one stale line makes agents distrust the entire file. When drafting principles, strip out table names, column names, endpoint paths, and class names — state the rule; let the schema and specs (which evolve with the code) carry the materialization.

When the user tries to include feature-level content, do not silently accept it. Politely decline, explain the test, and point to where it belongs (e.g., a specs/NNN-feature-name/ directory, if that's the workflow — or wherever the repo keeps per-feature specs). This policing is a feature of the skill, not rudeness: a constitution polluted with feature descriptions goes stale immediately and erodes agent trust in the whole file.

What goes in the file

Target these sections. Not every repo needs all of them; skip what genuinely doesn't apply.

1. Mission — one paragraph, a homeopathic dose of intent: "this service does X for Y." This anchors agent decisions without duplicating product docs.
2. Stack — languages, frameworks, versions, package managers. Exact commands to install and run.
3. Testing standards — framework, expected coverage, what must always be tested, exact commands to run the suite.
4. Repository guidelines — folder structure, naming conventions, module organization.
5. Workflow — branching model, PR conventions, commit message format, CI/CD, where specs/plans live.
6. Inviolable engineering principles — rules that hold for any feature, written as testable assertions in EARS-like form ("the system shall..."). Examples of the genre: "LLMs decide, deterministic code executes"; "no secrets hardcoded, ever"; "every external call has a timeout."
7. What the agent must NEVER do — explicit anti-instructions (e.g., "never force-push to main", "never edit generated files under gen/").

Interview behavior

Extract before asking

Interrogate every available source before asking the user anything:

• The current conversation — the user may have already stated stack, conventions, or principles.
• The repository itself (brownfield) — read manifests (package.json, pyproject.toml, go.mod, ...), CI config, existing test suites, lint configs, directory layout. Most of sections 2–5 is usually inferable from code.
• Architecture decision documents / ADRs, if the user provides them — the engineering principles in such a document are typically ~70% of the constitution. Mine them first.

Then interview only the gaps, and confirm inferences briefly rather than re-asking ("I see pytest with coverage configured at 85% in pyproject.toml — is that the enforced minimum?").

Two modes

• Greenfield (new/empty repo): run the full interview.
• Brownfield (existing code): read the repo first, generate a baseline draft from what's inferable, then interview only about what code cannot reveal — principles, prohibitions, workflow intentions, coverage expectations.

Detect the mode from context; if genuinely ambiguous, ask.

How to ask

• Ask in thematic blocks following the section order: stack → testing → structure → workflow → principles → prohibitions. A few questions per block, never a wall of questions.
• Challenge vague answers. The value of the interview is concreteness. If the user says "testing standard: test things well," push back: which framework? minimum coverage? unit vs. integration split? what command runs it? A constitution made of platitudes is worthless to an agent.
• Match the user's technical level. Experienced engineers don't need terms explained; less technical users may need examples of what a "principle" looks like.

Review before writing

Always present the complete draft in the conversation for the user's review before writing the file. Incorporate corrections, then write AGENTS.md to the repository root (and the optional CLAUDE.md pointer if the user wants it).

Output format

• Markdown, concise. A constitution must fit comfortably in any agent's context: target ~100–200 lines. If the draft balloons past that, it almost certainly contains spec material or documentation — apply the litmus test and cut.
• Clear ## sections matching the structure above (rename/merge freely to fit the repo).
• Principles and prohibitions as short, testable, imperative statements — not essays.
• Language: default to English, since AGENTS.md files are read by coding agents and often live in shared/public repos. If the conversation is happening in another language, ask the user which language they want for the file before drafting.

See references/example-agents-md.md for a complete annotated example of a finished file.