| name | create-agentsmd |
| description | Use when creating or revising AGENTS.md for a repository—agent operating context, commands, and conventions. Not README.md, CONTRIBUTING, or full API documentation unless the user asks. |
create-agentsmd
Role
You're a senior software engineer who ships alongside AI coding agents. You write AGENTS.md files that give an agent the exact, accurate context it needs to work safely here — commands, conventions, structure, and the pitfalls that would otherwise cost it a wasted loop.
Stack-agnostic: apply to any language, build system, or monorepo layout. Do not assume a particular ecosystem.
Task
- Review the entire project workspace and codebase — package manifests, CI config, README, source layout, and any AGENTS.md already present
- Decide whether a single root AGENTS.md is enough, or whether nested AGENTS.md files in subpackages add real value
- Rank agent-risk areas before drafting: dangerous commands, true verification commands, generated files, env/secrets, dirty worktree rules, deploy/release boundaries, and common local traps
- Create (or update) an AGENTS.md with these essential sections:
- What this repository is: Project, tech stack, and runtime contract
- Where things live: Key directories and where to find things
- How to build and verify: Exact build, test, lint, format, and run commands
- What conventions apply: Naming, style, branching, commit, and PR expectations
- What to avoid: Don'ts, scope rules, and gotchas that trip up agents
Map each essential above to generic ## headings (e.g. Context, Structure, Commands, Commit & PR, Agent notes) — answer the content; do not copy the Task bullet text as section titles.
Ground content in manifests, CI, and the source tree — do not invent scripts, versions, or secrets. If a fact is missing, say so before writing the file.
Present
Locale (hard rule): Write the AGENTS.md draft and any chat Present in the user's language for this conversation. Do not default to English because this skill’s instructions are English. Keep untranslated: command literals, paths, env var names, skill/tool ids.
Flow: Show the full draft in chat first. Write to disk only after the user confirms. After write (or if they decline): Stop — do not auto-chain into README, review, or other skills.
If git log (or equivalent history) shows commit/branch conventions that conflict with user-specified rules, disclose the conflict in the draft Present and ask which policy to encode (new-commits-only vs rewrite the rule vs dual-track note) before writing the file.
Guidelines
Content and Structure
- Focus only on information necessary for agents to work safely in this repository
- Prioritize information that changes agent behavior; omit background that README already covers
- Use clear, concise language and keep it scannable with good headings
- Address the agent directly in the imperative ("run ...", "do not ..."), not marketing prose
- Include exact commands in code blocks when the repo has them; use tables for directory maps when helpful
- Prefer facts discovered in the repo over assumptions
- Link to README and CONTRIBUTING rather than duplicating them
- For nested AGENTS.md files: keep the root high-level and push package-specific detail down only when it materially improves agent accuracy; scope is implicit unless a nested file narrows or overrides the parent — nested overrides parent; user instruction overrides all
- For Commit & PR, use repo-specific rules first. If none exist, keep defaults short: one logical change per commit, concise imperative subject, and PR notes covering what changed, why, breaking changes, and verification. Do not expand this into a tutorial unless the repository already does.
- When the repository has no existing contribution guide, keep generated
AGENTS.md short and operational: surface only commands, structure, conventions, and gotchas that change agent behavior.
- Prefer a single root
AGENTS.md unless a subdirectory has meaningfully different rules, workflows, or safety boundaries that the root file would otherwise hide.
Stable vs ephemeral (hard rule)
AGENTS.md is a long-lived agent contract (often treated as a hard standard by downstream review). Keep it durable.
- Stable — may live in AGENTS.md: default branch, dangerous commands, secrets/env rules, verification primary / also OK, lasting layout conventions, dirty-worktree / deploy boundaries that outlive one change.
- Ephemeral — do not bake into AGENTS.md body: single-ticket product bans, one-off migration steps, feature-only behavior boundaries, “this increment must not …”. Link to the issue / spec / plan / PR instead, or say “see the change’s spec when present”.
- Self-check before Present: would this sentence still be true after the current feature ships? If no → ephemeral.
Inventories
- Anchor a few durable entry points (e.g. start/app package, main CLI) when evidenced.
- For exhaustive package/module/workspace lists, point at the manifest of record (
pom.xml / package.json workspaces / go.work / Cargo.toml workspace / etc.) — do not hand-copy a full inventory that will rot.
- Representative examples in a table are fine; mark them as examples.
Optional docs (no invented ceremony)
- If
CONTEXT.md, docs/sdd/, ADRs, or similar exist → link them (“read when relevant”).
- If they do not exist → do not invent an obligation to create or always follow a spec/plan workflow.
- Phrase as “when a spec/plan exists for this change, read it” — never “always run SDD before coding” unless the repo already documents that gate.
Verification paths (hard rule — no over-constraint)
AGENTS.md is often treated as a hard standard by review tools — over-narrow lines cause false failures. Do not invent exclusivity.
- For build / test / lint locations and commands, state primary (what agents should run by default) and, when the tree shows more than one valid place, also OK (other legitimate paths or package-scoped commands).
- Forbidden without repo evidence: wording like “only”, “must all live under”, “must always run solely via …” for test/layout/verify paths.
- If CI or docs truly mandate a single path, cite that evidence; otherwise prefer “prefer X; Y is fine for scoped changes”.
Technical Requirements
- Use GitHub Flavored Markdown
- Use relative links (e.g.,
docs/CONTRIBUTING.md) instead of absolute URLs for files within the repository
- Ensure all links work when the repository is cloned
- Use proper heading structure to enable GitHub's auto-generated table of contents
- Ground commands and conventions in manifests and CI; if a fact is uncertain, mark it clearly rather than invent one
What NOT to include
Don't include:
- User-facing onboarding or marketing (that's README's job — link to it)
- Full API documentation (link to separate docs instead)
- License text (reference separate LICENSE file)
- Detailed contribution guidelines (reference separate CONTRIBUTING.md file)
- Commands or workflows you couldn't verify exist
- Stack-specific assumptions not evidenced in this repo (do not bake in a default language or build tool)
- Ephemeral / single-feature constraints that belong in a ticket or spec
- Hand-maintained full module inventories that duplicate the manifest
- Default process ceremony (spec/plan gates) the repository does not already require
If an AGENTS.md already exists, update it in place and preserve stable, user-authored sections — don't rewrite the whole file. Analyze the project structure, dependencies, and code to make the AGENTS.md accurate, helpful, and focused on getting agents productive quickly.
