Borrowing it
Nothing to install: this file belongs to ZhangHanDong/agent-spec. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.
curl -O https://raw.githubusercontent.com/ZhangHanDong/agent-spec/main/AGENTS.mdgit clone --depth 1 https://github.com/ZhangHanDong/agent-specWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/instructions/zhanghandong/agent-spec/agents-md)<a href="https://agentmods.dev/instructions/zhanghandong/agent-spec/agents-md"><img src="https://agentmods.dev/badge/instructions/zhanghandong/agent-spec/agents-md/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/instructions/zhanghandong/agent-spec/agents-md"><img src="https://agentmods.dev/badge/instructions/zhanghandong/agent-spec/agents-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.07092 | $0.07092 |
| Opus 5.5 | $0.02837 | $0.02837 |
| Sonnet 5.5 | $0.01418 | $0.01418 |
| Haiku 4.5 | $0.00709 | $0.00709 |
Grade A, and why
agent-spec AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2mo ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 571 lines — stays where its author put it; the contents beside it link to each section on GitHub.
agent-spec Integration for Codex / OpenAI Agents
This file provides Codex with the same guidance that Claude Code gets via
.claude/skills/. Two workflows: Tool-First (using the CLI) and Authoring (writing .spec/.spec.md files).
Part 1: Tool-First Workflow
Core Mental Model
Review point displacement: Human attention moves from "reading code diffs" to "writing contracts".
Traditional: Write Issue (10%) → Agent codes (0%) → Read diff (80%) → Approve (10%)
agent-spec: Write Contract (60%) → Agent codes (0%) → Read explain (30%) → Approve (10%)
Quick Reference
| Command | Purpose | When to Use |
|---|---|---|
agent-spec init |
Scaffold new spec | Starting a new task |
agent-spec contract <spec> |
Render Task Contract | Before coding - read the execution plan |
agent-spec lint <files> |
Spec quality check | After writing spec |
agent-spec lifecycle <spec> --code . |
Full lint + verify pipeline | After edits - main quality gate |
agent-spec guard --spec-dir specs --code . |
Repo-wide check | Pre-commit / CI - all specs at once |
agent-spec explain <spec> --format markdown |
PR-ready review summary | Contract Acceptance |
agent-spec explain <spec> --history |
Execution history | See retry count |
agent-spec stamp <spec> --dry-run |
Preview git trailers | Traceability |
agent-spec verify <spec> --code . |
Raw verification only | Verify without lint gate |
agent-spec resolve-ai <spec> --decisions <file> |
Merge AI decisions | Caller mode |
agent-spec requirements graph --gate |
Validate KLL requirements and dependency graph | After importing PRD/issue requirements |
agent-spec requirements transition <ID> --to accepted |
Explicit human governance transition | Accepting/rejecting a proposed requirement |
agent-spec requirements status <ID> |
Three-axis report: governance / execution / liveness with spec evidence | "Where is REQ-X?" in one command |
agent-spec requirements export --out requirements.yaml |
YAML projection of confirmed requirements (round-trip fixpoint, --check drift gate) |
Interop with YAML-world tooling; derived, never source of truth |
agent-spec requirements supersede <ID> --by <NEW> |
Atomic supersession pair | Replacing an accepted requirement |
agent-spec knowledge new <kind> <id> |
Scaffold a lint-clean proposal / decision / requirement | Starting any governance artifact — cheaper than hand-writing frontmatter |
agent-spec knowledge questions <id> |
Emit an artifact's open decision points as structured choices | Before asking the human anything about a proposal or decision |
agent-spec verify <spec> --emit-questions |
Emit judgment questions for scenarios the machine could not settle | When verification leaves skip/uncertain scenarios needing a human call |
agent-spec wiki status |
Check stale code live wiki articles | Before broad source reading |
agent-spec wiki query <text> |
Search tracked live wiki articles | Before opening many source files |
agent-spec wiki check |
Live wiki lint + worktree status gate | Pre-commit / CI for tracked wiki |
agent-spec atlas build/tree/query/search/explore/context/flow/impact/affected/refs/impls/status/check |
Rust project graph: scored retrieval, bounded context projection, explainable paths, reverse impact, identity, and freshness | Build before querying; use frozen reads for review and check for syn staleness |
agent-spec atlas benchmark validate/plan/summarize/score |
Validate an offline A/B corpus, compile paired run plans, summarize graded receipts, or score versioned query observations | Use the correctness-first E0/E3 gates; pinned repositories remain opt-in. See docs/atlas-evaluation.md |
agent-spec atlas benchmark agent-plan/agent-gate |
Compile symmetric A/B/C Agent runs and gate complete strict receipts | Real execution is external and opt-in; B/A and C/B are separate promotion candidates. See docs/atlas-agent-ab-gate.md |
agent-spec atlas benchmark serving-plan/serving-gate |
Compile and gate real-repository direct/worker burst trials | The checked template is disabled; fixture D4 receipts cannot approve worker defaults. See docs/atlas-agent-ab-gate.md |
agent-spec atlas provider validate/conformance |
Validate optional external Code Graph manifests and run the F1 producer contract matrix | Use explicit project registration only. A passing fixture receipt proves protocol conformance, not F2 language support. See docs/code-graph-provider-kit.md |
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 2mo ago First seen · 571 lines · 7,092 tokens per session scan A d88df9067b81
agent-spec AGENTS.md is an instructions file published in the GitHub repository ZhangHanDong/agent-spec (462 stars, last pushed 2mo ago), licensed MIT. It adds 7,092 tokens to every session, about $0.0284 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
agent-spec AGENTS.md compared with instructions from other repositories
| Mod | Type | Stars | Last push | Licence | Scan | Tokens | Works with |
|---|---|---|---|---|---|---|---|
| agent-spec AGENTS.mdZhangHanDong/agent-spec | Instructions file | 462 | 2mo ago | MIT | A | 7,092 | Codex, OpenCode |
| vscode buildNext.instructions.mdmicrosoft/vscode | Instructions file | 195k | yesterday | MIT | A | 9,719 | GitHub Copilot |
| next.js AGENTS.mdvercel/next.js | Instructions file | 143k | today | MIT | A | 7,461 | Codex, OpenCode |
| langchain AGENTS.mdlangchain-ai/langchain | Instructions file | 149k | today | MIT | A | 4,680 | Codex, OpenCode |
| vscode oss-third-party-notices.instructions.mdmicrosoft/vscode | Instructions file | 195k | yesterday | MIT | A | 5,516 | GitHub Copilot |
| vscode copilot-instructions.mdmicrosoft/vscode | Instructions file | 195k | yesterday | MIT | A | 3,093 | GitHub Copilot |
| deepseek-harness AGENTS.mddeepseek-ai/deepseek-harness | Instructions file | 274k | 2d ago | MIT | A | 4,313 | Codex, OpenCode |