Awesome AGENTS.md

Name: awesome-agents-md
Author: khasky

One AGENTS.md to import, with shared rules for AI coding agents: Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor Agent — plus optional rule modules in rules/ that load on demand. Clone once, import it globally into every agent you use.

The always-loaded core covers: concise token-efficient communication, a "lazy senior dev" coding discipline (smallest correct diff, no speculative abstractions), a hard verification gate before any "done" claim, debug escalation, and a commit-proposal habit with no assistant traces. On-demand modules in rules/ extend it — commit messages that inherit the target repo's own convention, backend security, databases, caching, resilience, deployment and infrastructure definitions, payments, and more.

No hard dependencies and nothing tool-specific. The ruleset is framework- and project-agnostic — it holds for any stack and any of the four agents, with nothing extra to install. Agent tooling lives in sibling repos: agent-mcp-integrations for the MCP integration servers (browsers, cloud, databases, infra, domain APIs) and claude-code-token-optimization for the token-efficiency layers (LSP, codebase-memory-mcp, ast-grep, Context7, Caveman, Ponytail).

Awesome AGENTS.md

Repository layout

AGENTS.md        # the core ruleset — always loaded, under 200 instruction lines and 32 KiB (CI-enforced)
rules/           # on-demand modules, read only when the task matches — the full list
                 # with trigger conditions is the last section of AGENTS.md, and CI
                 # fails if a module there is missing or a module here is unlisted
README.md        # setup and optional tooling (this file)
llms.txt         # index of the core and every module for LLM consumption —
                 # CI keeps it two-way synced with rules/
hooks/           # hooks.json — the SessionStart hook that prints AGENTS.md into a
                 # Claude Code session when the repo is installed as a plugin
.claude-plugin/  # plugin.json and marketplace.json for that install path
scripts/         # lint.py — every gate above, run by CI and by the optional
                 # pre-commit hook that install-hooks.py sets up

The core is self-sufficient. Agents read rules/*.md only when the task matches (editing Markdown, styling UI, a dedicated refactor, ...) and skip them if the clone can't be located — so importing the single AGENTS.md is always enough.

The 200-instruction cap is not cosmetic: frontier models follow roughly 150–200 instructions reliably (measured by IFScale), and the agent's own system prompt already spends ~50 of them. Everything past that budget degrades adherence to the rules that matter. The file also stays under 32 KiB, the default project_doc_max_bytes past which Codex silently truncates project instructions.

Prerequisites

At minimum you need git and one of the agents. Windows one-liners (skip what you already have):

winget install -e --id Git.Git
winget install -e --id OpenJS.NodeJS.LTS   # npx — required by Gemini CLI

The agents themselves:

winget install -e --id Anthropic.ClaudeCode
$env:CODEX_NON_INTERACTIVE = "1"; irm https://chatgpt.com/codex/install.ps1 | iex
npm install -g @google/gemini-cli

Cursor: download from cursor.com.

Install

git clone https://github.com/khasky/awesome-agents-md.git

Examples below assume the clone lives at C:\repos\awesome-agents-md (Windows) or ~/repos/awesome-agents-md (macOS/Linux) — adjust the path to yours.

Each agent has a global instructions file. Add one import line to it (create the file if it does not exist). Keep those files thin — all rules live in the shared AGENTS.md.

Claude Code

%USERPROFILE%\.claude\CLAUDE.md (macOS/Linux: ~/.claude/CLAUDE.md):

@C:/repos/awesome-agents-md/AGENTS.md

Claude Code resolves @path imports natively; forward slashes work on Windows. Approve the import when prompted.

Never copy rules/ into .claude/rules/ (project-level or ~/.claude/rules/): Claude Code loads every file in that directory unconditionally at session start, which turns the on-demand modules into ~33k always-on tokens per request. The single import line above is the whole install.

Verify inside Claude Code: run /memory — the imported AGENTS.md should be listed.

Instead of the import line, Claude Code can install the repository as a plugin: /plugin marketplace add khasky/awesome-agents-md, then /plugin install awesome-agents-md@awesome-agents-md. The plugin ships a SessionStart hook that prints AGENTS.md into the session, so the core loads without editing CLAUDE.md, and the hook appends the absolute path of the installed rules/ so the on-demand modules resolve there. plugin.json pins no version on purpose: Claude Code then tracks the commit, and a rule added here reaches installed users on the next push instead of waiting for a release bump.

Pick one of the two, not both — an @import alongside the plugin puts the core in context twice. Verify the plugin path by the canary below rather than by /memory, which lists imports only: a plugin contributes context through its hook.

Optional but recommended: "attribution": { "commit": "", "pr": "" } in %USERPROFILE%\.claude\settings.json (older builds: "includeCoAuthoredBy": false) empties the commit and PR attribution Claude Code appends by default. That is a soft backstop for the ruleset's no-AI-traces rule: a session can still be handed an attribution instruction at run time, and one that names a Claude-Session trailer has reached a session whose settings already carried the empty strings. The hard backstop is a commit-msg hook rejecting any message that matches Co-Authored-By|Claude-Session|claude\.ai/code/session.

OpenAI Codex CLI

%USERPROFILE%\.codex\AGENTS.md (macOS/Linux: ~/.codex/AGENTS.md):

@C:/repos/awesome-agents-md/AGENTS.md

Codex has no import syntax: the @ line is plain text, and the model follows it by reading the shared file — reliable in practice, but not enforced by the CLI. For guaranteed loading, paste the full contents of AGENTS.md into that file instead; Codex stops adding instruction files once their combined size reaches project_doc_max_bytes (32 KiB by default, configurable in ~/.codex/config.toml).

Verify:

codex "Which instruction files did you load? Do not modify anything."

Gemini CLI

%USERPROFILE%\.gemini\GEMINI.md (macOS/Linux: ~/.gemini/GEMINI.md):

@C:/repos/awesome-agents-md/AGENTS.md

Gemini CLI supports @file imports in GEMINI.md natively.

Verify inside Gemini CLI: /memory show. After editing the files: /memory refresh.

Cursor

Cursor has no global markdown import. Two options:

Per project: copy AGENTS.md into the project root — Cursor Agent reads it.
Globally: paste the contents of AGENTS.md into Cursor Settings → Rules → User Rules.

Per-project alternative (any agent)

Copy AGENTS.md into a repository root. Codex and Claude Code pick up a project-level AGENTS.md automatically. For Gemini CLI, add it to the recognized context files in ~/.gemini/settings.json:

{ "contextFileName": ["GEMINI.md", "AGENTS.md"] }

Loaded-rules canary

The first rule in AGENTS.md makes the agent end every response with ✓ awesome-agents-md: if you see the marker, the import chain works. Once confirmed (or if you find it noisy), delete that line in your clone.

Beyond the canary: in Claude Code, /context confirms the file is actually loaded and /doctor suggests trims; a model-agnostic check is prompting "Summarize the instructions you loaded." If a specific rule keeps being ignored, the usual cause is file length — prune before rephrasing.

Three guides, one split — pick the layer you need:

Awesome Agents MD — this repo: the base, tool-agnostic ruleset every agent imports (one AGENTS.md). Start here; the layers below are optional on top.
Awesome Agent Skills — portable SKILL.md skills every agent loads: code review, debugging, security and leak audits, code and text cleanup.
Agent MCP Integrations — MCP servers that connect agents to browsers, cloud, databases, infra, and domain APIs.
Claude Code Token Optimization — the token-efficiency layer (LSP, codebase-memory-mcp, ast-grep, Context7, Caveman, Ponytail).
Claude Code Security Audit — the layered security-audit workflow (deep audit, continuous guardrails, scanners).

A rule or a skill? A rule is a standing constraint the agent honors without being asked; a skill is a procedure you invoke, with phases and an output contract. The two layers overlap: rules/code-review.md here sets the bar every review must meet, and the awesome-code-review skill runs the review and produces the report. Install both — rules keep everyday work in line, skills handle the jobs you name.

Contributing

A rule earns its line only if an agent would get it wrong without it, and the core AGENTS.md stays under 200 instruction lines and 32 KiB — see CONTRIBUTING.md for the format of a new rules/ module and the checks CI runs.

License

Released under the MIT license. AGENTS.md adapts MIT-licensed material from two projects — JuliusBrussee/caveman (output compression) and DietrichGebert/ponytail (lazy senior dev mode) — with credit kept inline where each is used.

awesome-agents-md