create-agents-md
Skill0 starsChanged 18 days agoMITView on GitHub
Create, audit or refresh AGENTS.md files: the repo root, nested package files, and the user-level global file, for Claude Code, Cursor and Codex. Use when asked to write, improve, split, shrink or migrate AGENTS.md or CLAUDE.md.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- crbnos/carbontheir own version, first seen Nov 7, 2026
- AlessioScarfone/skillstheir own version, first seen Nov 6, 2026
- MSiccDev/ai-context-kittheir own version, first seen Jul 7, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- crbnos/carbon★ 2.8ksame name
- MSiccDev/ai-context-kit★ 12same name
- AlessioScarfone/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository57 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/comments.mdcCursor rule
- .cursor/rules/commit-messages.mdcCursor rule
- .cursor/rules/git-workflow.mdcCursor rule
- .cursor/rules/manage-stack.mdcCursor rule
- .cursor/rules/no-worktrees.mdcCursor rule
- manage-stackSkill
- convert-as-skillSkill
- create-agentSkill
- create-commandSkill
- create-hookSkill
- create-ruleSkill
- create-skillSkill
- retrospectiveSkill
- super-architectureSkill
- super-cachingSkill
- super-elixirSkill
- super-nodejsSkill
- super-protobufSkill
- super-tech-blueprintSkill
- atomic-semantic-commitSkill
- code-reviewSkill
- create-bruno-collectionSkill
- create-documentationSkill
- create-ticketsSkill
- ready-specSkill
- write-adrSkill
- write-changelogSkill
- write-mr-descriptionSkill
- write-planSkill
- write-postmortemSkill
- write-runbookSkill
- noslopSkill
- output-saversSkill
- safe-refactorSkill
- tddSkill
- verifySkill
- get-movingSkill
- later-listSkill
- standupSkill
- challenge-meSkill
- codebase-learnerSkill
- researchSkill
- second-opinionSkill
- traceSkill
- color-kitSkill
- design-system-kitSkill
- diagramSkill
- infographicSkill
- product-polish-workflowSkill
- prototype-wireframeSkill
- ui-ux-kitSkill
- evidenceSkill
- find-skillsSkill
- handoffSkill
- rumblingSkill
- use-levistackSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 57
Nested: only when a directory has different build or test commands, a different language or framework, stricter rules, or risky areas.
- Distinctive: line 58
Global: only for personal preferences that are true in every repo (communication style, tool habits).
- Very specific: line 63
Inspect before writing: Read build files, scripts, CI config, test and lint config, README, CONTRIBUTING, recent commit subjects, and every …
- Distinctive: line 70
commit, branch and PR rules
- Very specific: line 72
Prove it: Run each command you wrote, or mark it (unverified).
- Distinctive: line 82
Run the audit script, then read each file against the content rules below.
- Very specific: line 98
Use headings and bullets. Use backticks around any path you do not want imported (@path outside backticks is an import in Claude).
- Very specific: line 103
Claude Code: run /memory and look for the file's path.
- Distinctive: line 104
Cursor: ask the agent to summarize the instructions it has for a file in the target directory.
- Distinctive: line 117
Every command was run or is marked unverified, and every path exists.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Create AGENTS.md
An AGENTS.md is a README for coding agents: the commands, conventions and traps an agent cannot infer quickly from the code. One canonical file at the repo root, optional nested files where a package genuinely differs, and an optional personal file for rules that apply to every repo.
Pick the mode
| The request | Mode |
| "Write / set up AGENTS.md" | Root |
| "This package works differently", monorepo | Nested |
| "My preferences for every repo" | Global |
| "Improve / shrink / it's ignored / out of date" | Audit and refresh |
| "We have CLAUDE.md / .cursor/rules / copilot instructions" | Migrate |
Infer the mode from the request. Ask only if it is genuinely ambiguous.
How each tool reads the files
Checked against the tools' docs on 2026-10-04 (sources and re-check steps in tool-behavior.md). Behavior changes between versions, so treat this as a map and verify with the commands below.
| Global | Project root | Nested | Notes | |
| Codex | ~/.codex/AGENTS.md (AGENTS.override.md wins; first non-empty only) | Yes | Walks git root down to the working directory, one file per directory, concatenated root to leaf, closer text last | Stops adding files at 32 KiB combined |
| Cursor | None. Personal rules live in Settings → Rules | Yes | Combined hierarchically, more specific wins | Plain Markdown: no frontmatter, no globs |
| Claude Code | ~/.claude/CLAUDE.md | Reads AGENTS.md only if no CLAUDE.md exists in the working directory or above (v2.1.277+) | Subdirectory files load on demand when Claude reads files there | Otherwise import it with @AGENTS.md |
Across all of them the agents.md convention holds: the nearest file wins, and an explicit user prompt overrides every file.
Decide placement
- Root holds everything true for the whole repo.
- Nested only when a directory has different build or test commands, a different language or framework, stricter rules, or risky areas. A nested file adds or overrides specifics. It never restates the root, and never contradicts it: Codex and Claude put both in context.
- Global only for personal preferences that are true in every repo (communication style, tool habits). Never project facts.
- One source of truth. If the repo also needs a
CLAUDE.md, make it a symlink toAGENTS.md, or a two-line file:@AGENTS.mdplus Claude-only notes.
Create or refresh (root and nested)
- Inspect before writing. Read build files, scripts, CI config, test and lint config,
README,CONTRIBUTING, recent commit subjects, and every existing instruction file (AGENTS.md,CLAUDE.md,.cursor/rules,.github/copilot-instructions.md). Runnode scripts/audit.mjs <repo>to see what already exists and how big it is. - Keep only what an agent cannot get quickly from the code:
- exact commands to install, build, run one test, run all tests, lint, format
- conventions that differ from the language default, with the reason
- boundaries: what not to touch, generated files, layers that must not import each other
- traps that look fine and fail later
- how to verify work, and what "done" means
- commit, branch and PR rules
- Draft from the templates in templates.md. Write instructions a reviewer could check: "Run
npm test -- pathbefore committing", not "test your changes". - Prove it. Run each command you wrote, or mark it
(unverified). Confirm every path exists. - Keep it short. Root: aim for 150 lines or fewer. Nested: 60 or fewer. Claude's guidance is under 200 lines per file; Codex's whole chain must fit in 32 KiB.
- Run
node scripts/audit.mjs <repo>and fix the findings.
Global mode
Write ~/.codex/AGENTS.md and/or ~/.claude/CLAUDE.md with the same short personal preferences. Keep them in one file and import it from the other (@~/.codex/AGENTS.md works in a Claude user file). Tell the user that Cursor has no global file and the same text must be pasted into Settings → Rules. Do not write to the user's home directory without saying which file and why.
Audit and refresh
Run the audit script, then read each file against the content rules below. Report findings by priority:
- Broken: commands that fail, paths that do not exist, a
CLAUDE.mdthat hidesAGENTS.mdfrom Claude. - Costly: files over the line or byte budget, text that duplicates the README or the code, stale directory listings.
- Risky: secrets, personal paths, contradictions between root and nested files.
Propose the smallest edits. Preserve auto-managed marker blocks and the maintainers' sections.
Migrate
Merge CLAUDE.md, .cursor/rules, and copilot instructions into one AGENTS.md, deduplicating. Keep file-scoped rules that need globs as Cursor or Claude rules, since AGENTS.md has no metadata. Replace the old CLAUDE.md with the shim. Do not delete the originals until the user confirms.
Content rules
Belongs: commands, non-default conventions, boundaries, traps with rationale, verification steps, git rules.
Does not belong: directory trees and dependency lists (they go stale and the agent can read them), architecture overviews derivable from code, generic advice ("write clean code"), persona text, anything already in the README, long prose, secrets, tokens, personal paths, or @-imports of files that may not exist.
Use headings and bullets. Use backticks around any path you do not want imported (@path outside backticks is an import in Claude).
Verify what loaded
- Codex:
codex --ask-for-approval never "Summarize the current instructions." - Claude Code: run
/memoryand look for the file's path. - Cursor: ask the agent to summarize the instructions it has for a file in the target directory.
Related skills
create-rule: a standard should apply by file glob or path.create-skill: a long procedure belongs outside AGENTS.md.create-hook: something must be enforced, not just asked.codebase-learner: the file must describe a codebase you have not read yet.concise: keep the file short and plain.
Done when
- The right files exist at the right levels, and nothing is duplicated between them.
- Every command was run or is marked unverified, and every path exists.
- The audit script reports no warnings, or the user accepted the remainder.
- Claude can see the content (symlink or import), and the user knows Cursor has no global file.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.