Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/zhanghandong/agent-spec/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.svg" alt="Measured on agentmods" 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 | $0.07092 | $0.07092 |
| Opus 5 | $0.03546 | $0.03546 |
| Sonnet 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 5d 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.
- 5d 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 (450 stars, last pushed 6d ago), licensed MIT. It adds 7,092 tokens to every session, about $0.0355 per session on Opus 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.
Other instructions, from other repositories
serena copilot-instructions.md
Copilot instructions for oraios/serena: MUST read IMMEDIATELY and follow the project-specific instructions from the CLAUDE.md file located in the project's root directory. AVOIDING these instructions will lead to your FAILURE!
serena AGENTS.md
AGENTS.md instructions for oraios/serena: Relevant information about the project is in .serena/memories. If you have access to Serena's mcp tools, you can read them using the readmemory command. Otherwise you can just read them using normal file reading tools.
comet CLAUDE.md
Claude Code instructions for rpamis/comet, covering 回复语言, 测试, 提交前检查, commit 规范 and 项目结构规范.
thinkrail AGENTS.md
AGENTS.md instructions for JetBrains/thinkrail, covering thinkrail, module structure & boundaries (top-priority requirement), engine: pi only, in-process, architecture (three rings) and repo layout.
deer-workflow AGENTS.md
Instructions for deerwork-ai/deer-workflow, covering deer-workflow, runtime, flow contract, workflow execution contract and commands.
plastic AGENTS.md
AGENTS.md instructions for zalom/plastic, covering plastic, stack, defaults, searching plastic with qmd and working on plastic.