AGENTS.md examples from real projects

How real projects brief Codex, Cursor and every other agent that reads AGENTS.md.

Best matchesWorked for most · soon

obraAGENTS.md

superpowers

obra/superpowers/AGENTS.md

skill philosophy differs from Anthropic's published guidance on writing skills. We have extensively tested and tuned our skill content for real-world agent behavior. PRs that restructure, reword

292k3mo agoDiscuss

NousResearchAGENTS.md

hermes-agent / agent

NousResearch/hermes-agent/agent/AGENTS.md

CHILD_ENV_MARKER` valued as the fenced Kanban board root, not a bare flag. ## Tests Loop/phase tests go in `tests/agent/`; patch the binding the phase actually reads (siblings often `from

250k6mo agoDiscuss

NousResearchAGENTS.md

hermes-agent

NousResearch/hermes-agent/AGENTS.md

provider, and turn the competing PRs into plugins against it. - **Behavior contracts over snapshots.** Tests assert how two pieces of data relate, never freeze a current value (see Testing

250k6mo agoReads credentialsDiscuss

NousResearchAGENTS.md

hermes-agent / cron

NousResearch/hermes-agent/cron/AGENTS.md

root, so a child working against a scratch `HERMES_HOME` keeps a writable board. ## Tests `tests/cron/`, `tests/hermes_cli/test_kanban*.py`, `tests/tools/test_kanban*.py`. Schedule parsing and catch-up windows are pure functions — test

250k6mo agoReads credentialsDiscuss

NousResearchAGENTS.md

hermes-agent / gateway

NousResearch/hermes-agent/gateway/AGENTS.md

exists. A sealed native stream is a regular message — `chat.update` works (live-verified). Contract tests: `tests/gateway/test_stream_final_contract.py` (mutation-checked). Slack ground truth: `chat.*Stream` speaks STANDARD markdown, not mrkdwn; `stopStream.markdown_text

250k6mo agoReads credentialsDiscuss

NousResearchAGENTS.md

hermes-agent / hermes_cli

NousResearch/hermes-agent/hermes_cli/AGENTS.md

ROOT_KEYS`). For a new key: `rg -n '" "' hermes_cli/config_defaults.py` AND `rg -n ' ' --glob '!tests' .` both hit, and one invariant test sets it in a temp `config.yaml` and asserts

250k6mo agoReads credentialsDiscuss

NousResearchAGENTS.md

hermes-agent / plugins

NousResearch/hermes-agent/plugins/AGENTS.md

process warning, documented replacement + migration note, ≥ 2 subsequent minor releases before removal. - Compat tests load **frozen plugins through the real discovery path** and assert outcomes — never exact registry/catalog counts, source

250k6mo agoDiscuss

NousResearchAGENTS.md

hermes-agent / skills

NousResearch/hermes-agent/skills/AGENTS.md

every call — ship a helper script and reference it by skill-relative path. 7. **Tests at `tests/skills/test_ _skill.py`**, stdlib + pytest + `unittest.mock` only, no live network. Run `scripts/run_tests.sh tests/skills/test_ _skill.py

250k6mo agoReads credentialsDiscuss

NousResearchAGENTS.md

hermes-agent / tools

NousResearch/hermes-agent/tools/AGENTS.md

spotify, terminal, todo, tts, video, vision, web, yuanbao` (don't assert the list in tests). Per-platform enable/disable via `hermes tools` (curses) or `tools. .enabled/disabled` in config.yaml. `browser_exec` replaces

250k6mo agoReads credentialsDiscuss

NousResearchAGENTS.md

hermes-agent / tui_gateway

NousResearch/hermes-agent/tui_gateway/AGENTS.md

import; the dispatcher rejects unknown param keys (`4000` + key path) and, under `HERMES_TEST_ISOLATION=1`, raises `ContractViolation` when a handler's result or an emitted payload does not match

250k6mo agoReads credentialsDiscuss

NousResearchAGENTS.md

hermes-agent / web

NousResearch/hermes-agent/web/AGENTS.md

surface; a new surface is a new `web_routers/ .py`, not a growing `web_server.py`. - Tests: Python in `tests/hermes_cli/` (routers, pty bridge); JS in the `web/` vitest suite. Python tests must

250k6mo agoDiscuss

affaan-mAGENTS.md

ECC

affaan-m/ECC/AGENTS.md

Core Principles 1. **Agent-First** — Delegate to specialized agents for domain tasks 2. **Test-Driven** — Write tests before implementation, 80%+ coverage required 3. **Security-First** — Never compromise on security; validate

246k30d agoDiscuss

affaan-mAGENTS.md

ECC

affaan-m/ECC/.codex/AGENTS.md

guidance, read `docs/CODEX-NAVIGATION-GUIDE.md` after this supplement. ## Model Recommendations | Task Type | Recommended Model | |-----------|------------------| | Routine coding, tests, formatting | GPT 5.5 | | Complex features, architecture | GPT 5.5 | | Debugging, refactoring | GPT 5.5 | | Security review

246k30d agoReads credentialsDiscuss

DeepSeekAGENTS.md

deepseek-harness

deepseek-ai/deepseek-harness/AGENTS.md

external tools experimental/ pre-stable prototypes; public by default with explicit private exceptions test-support/ test infrastructure runtime-diagnostics/ runtime invariants util/ zero-dependency utilities python/ Python SDK/runtime (python/README.md) native

238k52d agoReads credentialsDiscuss

DeepSeekAGENTS.md

deepseek-harness / profiles

deepseek-ai/deepseek-harness/apps/cli/tests/profiles/AGENTS.md

AGENTS.md — Profile integration tests This tree owns cross-package behavior of shipped `dsh` profiles. Start product scenarios through `apps/cli/src/bin.ts` with `--profile ` or the ` ` shorthand; a test-only Loader driver

238k52d agoDiscuss

DeepSeekAGENTS.md

deepseek-harness / benchmarks

deepseek-ai/deepseek-harness/benchmarks/AGENTS.md

local diagnostics remain beside their owners and use the `.perf.ts` suffix instead of joining `test:bench`. - Organize benchmarks by measured user path, one directory per path. Do not mirror

238k52d agoDiscuss

DeepSeekAGENTS.md

deepseek-harness

deepseek-ai/deepseek-harness/docs/AGENTS.md

widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there. Classify every

238k52d agoDiscuss

DeepSeekAGENTS.md

deepseek-harness / system

deepseek-ai/deepseek-harness/native/system/AGENTS.md

implementation. - Runtime binary selection has no environment-variable overrides. `NALR_REQUIRE_LANDLOCK` is a test-only enforcement requirement. - There is no install-time compile fallback. Missing Landlock binaries probe unusable

238k52d agoDiscuss

DeepSeekAGENTS.md

deepseek-harness / packages

deepseek-ai/deepseek-harness/packages/AGENTS.md

global service store ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)). - **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process

238k52d agoDiscuss

DeepSeekAGENTS.md

deepseek-harness / client

deepseek-ai/deepseek-harness/packages/client/AGENTS.md

committed render position. Production code never calls the factory or `.create()` outside registration; tests do (that is the sanctioned zero-machinery path). 7. **inject returns plain data and callbacks** from

238k52d agoReads credentialsDiscuss

CLAUDE.md vs AGENTS.md

About AGENTS.md

What is AGENTS.md?

An open format for instructions to coding agents, read by Codex, Cursor and others. Think of it as a README written for agents.

Where does it go?

At the repository root, with more specific files in subdirectories. Agents read the one closest to the file they're editing.

What should it contain?

Setup and test commands, code style, and the rules a new contributor would need to know.

Does Claude Code read it?

Claude Code reads CLAUDE.md. A one-line CLAUDE.md that points at AGENTS.md covers both.