I reverse-engineered popular coding-agent instruction repos and distilled their best ideas into a stack-agnostic AGENTS.md. 📦
The core rules cover small, focused changes, security boundaries, debugging, and verification before an agent says a task is done. More specialized guidance lives in rules/ and is meant to be read when a task calls for it.
Take it for a spin 👉 https://github.com/khasky/awesome-agents-md
One core for the work every agent does
I wanted a set of rules I could use across Claude Code, Codex, Gemini, and Cursor without rewriting them for each framework or project.
The core lives in one AGENTS.md and covers the parts of a coding task that don't change with the stack: understanding the request, keeping the change focused, handling sensitive data, debugging failures, and checking the result.
The file also sets boundaries. Unless I explicitly ask, the agent shouldn't delete files, rewrite Git history, force-push, or make a failing check pass by weakening it. It proposes a commit message instead of running git commit or git push on its own. These are instructions for the agent; actions that must be blocked without exception still need permissions, hooks, or CI.
Less code, with evidence that it works
Before adding a helper or dependency, the agent is asked to check whether the code already exists in the project, whether the standard library or an installed dependency can handle it, and whether the solution can be simpler. The goal is the smallest change that solves the actual problem. This part draws on the "lazy senior developer" approach from Ponytail; the repo also credits Caveman for its concise communication ideas.
Verification is just as important. Before saying a task is done, fixed, or passing, the agent is told to run a relevant check, read its output, and report the result. "34/34 pass, exit 0" tells me something useful. "Should work now" tells me it's time to check. For a bug fix, the rules call for rerunning the scenario that failed in the first place.
Specialized rules when the task calls for them
The core points to modules in rules/, each with a "Read this when" trigger. There are modules for databases, backend security, caching, deployment, payments, browser automation, and more. An agent working on payments is instructed to read the payments rules; a task with no checkout doesn't need that guidance in context.
The modules are framework-agnostic too. When an example uses a particular technology, its scope is stated explicitly. For example, the database guidance applies its general principles to relational databases while using PostgreSQL syntax for examples.
I keep the core under 200 instruction lines and 32 KiB, and CI checks both limits. That forces a useful question whenever I add a rule: would an agent likely get this wrong without it? The core can stand on its own; the modules add depth only when needed.
Use it with your coding agent
Clone the repository first:
git clone https://github.com/khasky/awesome-agents-md.git
The tools load shared instructions in different ways:
| Agent | How to use the core |
|---|---|
| Claude Code | Add an @path/to/AGENTS.md line to your global CLAUDE.md, or install the repository as a Claude Code plugin. Use one method, not both. |
| Gemini CLI | Add an @path/to/AGENTS.md line to your global GEMINI.md. |
| OpenAI Codex CLI | Put a path reference in the global AGENTS.md and ask the agent to read it, or copy the core into that file for direct loading. Codex does not have a native @ import. |
| Cursor Agent | Copy AGENTS.md into a project root, or paste the core into Cursor's User Rules. Cursor does not have a global Markdown import. |
The README has exact paths and verification steps for each tool. For Claude Code, the plugin option uses a SessionStart hook to supply the core without editing CLAUDE.md.
If your agent reads the local clone, updating the rules is a git pull followed by a fresh session. If you copied or pasted the contents into an agent's settings, refresh that copy when you want the newer rules. There are no modes to switch between or extra dependencies to install for the ruleset.
The first rule asks the agent to end its replies with ✓ awesome-agents-md. It's a quick way to see that the core reached the session. You can remove that line from your clone after checking it. The README also lists ways to inspect loaded instructions in each tool.
Refined on real projects
I've revised these rules over many iterations while working on real applications. The public commit history shows how the wording has changed, and I keep revisiting rules as models improve. Every rule is plain Markdown, so you can inspect it and decide whether it belongs in your workflow.
Try it, make it your own, and tell me what you'd improve. Issues and PRs are welcome! 😉
Follow me for more on AI, LLMs, and Software Development:
khasky — LinkedIn / Patreon / GitHub / Bluesky / Mastodon
khaskydev — X / Threads / Instagram / Pinterest / Facebook
Top comments (0)