| name | agents-md-author |
| description | Bootstrap or update project AI-agent instruction files (AGENTS.md for Codex, CLAUDE.md for Claude Code, or both) from the current project's structure. Triggers on: write AGENTS.md, write CLAUDE.md, generate AGENTS.md, agent instructions, project conventions for AI, bootstrap agent docs, set up project memory for Codex/Claude, document dev/test/build commands for AI coding tools, single-source project instructions for any AI agent. |
| version | 1.0.1 |
agents-md-author
Generate cross-vendor project instruction files: AGENTS.md for Codex (and most other tools), CLAUDE.md for Claude Code, or both kept in sync. Load references/agents-md-spec.md if you need the cross-vendor convention details.
When to activate
- User asks to "write AGENTS.md", "create CLAUDE.md", or "set up project instructions for AI"
- User wants the same project doc to work in Codex, Claude Code, Cursor, or any tool that follows the AGENTS.md convention
- User mentions onboarding a new AI tool to an existing repo and wants conventions captured
Procedure
1. Detect project context (always do this first)
Read the project root and determine:
- Project name — from
package.json name, pyproject.toml [project].name, go.mod module, Cargo.toml [package].name, or fallback to repo dir name
- Language & runtime —
package.json (Node + lockfile flavor), requirements.txt / pyproject.toml (Python), go.mod (Go), Cargo.toml (Rust), pom.xml / build.gradle (JVM), *.csproj (.NET)
- Common scripts — Node
scripts.{dev,build,test,lint,typecheck}; Python tox.ini / Makefile; Go/Rust task tools
- Test framework — vitest, jest, pytest, go test, cargo test, etc.
- Repo conventions — existing
.editorconfig, .prettierrc, eslint.config.*, pre-commit-config.yaml
If the user provided context (e.g., "this is a Next.js + Prisma app"), use it; otherwise infer from files. Don't ask questions you can answer from disk.
2. Decide the target file(s)
| User wants | Write |
|---|
| Codex / OpenAI tools only | AGENTS.md |
| Claude Code only | CLAUDE.md |
| Both, kept in sync | AGENTS.md + CLAUDE.md (identical content), or AGENTS.md plus a one-line CLAUDE.md that says "See AGENTS.md" |
| Single source (recommended) | AGENTS.md + CLAUDE.md symlink → AGENTS.md |
Default to "both, identical content" unless the user specifies — it's the lowest-risk option and works everywhere.
3. Compose content
Use this canonical structure (load references/agents-md-spec.md if you need the field-by-field rationale or cross-vendor details):
# <Project name>
<one-sentence description>
## Tech stack
- <language + version>
- <framework + version>
- <database / runtime / deployment>
## Dev commands
- Install: `<command>`
- Dev server: `<command>`
- Build: `<command>`
- Test: `<command>` (unit) / `<command>` (e2e)
- Lint / typecheck: `<command>`
## Code conventions
- <indent + line length>
- <import style>
- <naming conventions>
- <test colocation>
- <commit style>
## Architecture notes
<2-5 bullets on layout — where routes live, where business logic lives, what's shared>
## Out of scope for AI agents
<deliberate "don't touch" list — generated files, secrets, migrations, etc.>
Keep it under ~150 lines. AI agents skim — verbose docs are skipped or ignored.
4. Write files
- Use canonical line endings for the OS (LF on macOS/Linux)
- Don't add a trailing summary or "generated by" footer — the file is now the user's
- If a file already exists, read it first, propose a diff, and ask the user before overwriting
5. Verify
- Print the relative paths written
- If both
AGENTS.md and CLAUDE.md were written, confirm they're byte-identical (or show the symlink)
- Suggest the user commit the files
References
