Menu
Extract implicit knowledge and audit AGENTS.md against four principles. Derives sections from domain, not from a fixed template.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when a request will produce frontend UI, a visual asset, an image prompt, or a video prompt, AND the intent/style is not already fully specified by the user or an existing design system in the repo. Forces a minimal, checkable design-context object to exist before generation so output does not default to generic/templated. Do NOT use for: single-property edits (color, spacing, copy tweak) with no ambiguity; bug fixes; refactors; or when the user already gave complete visual specs and you only need to execute. For those, just do the work.
Root orchestrator. Reads durable state, routes to one phase, dispatches fresh workers.
Pre-implementation alignment gate. Checks spec / plan / tasks consistency and plan vs codebase reality before code is written.
Define the goal: what problem we solve, for whom, and what success looks like. The directional anchor that architecture and specs must serve.
RED-GREEN-REFACTOR implementation per task. Each task passes before next. Produces handoff.md with reproducible evidence.
Design architecture: components, API schema, DB model, impact analysis, test strategy.
| name | agents-md |
| description | Extract implicit knowledge and audit AGENTS.md against four principles. Derives sections from domain, not from a fixed template. |
| trigger | When the user asks to create, review, or optimize an AGENTS.md file. |
| inputs | ["AGENTS.md (current, if exists)","CONSTITUTION.md (if exists)","Project codebase / file tree"] |
| outputs | ["AGENTS.md (created or updated)","Audit notes (optional — what was flagged and why)"] |
| boundaries | Read-only on all files except AGENTS.md. Advises, does not dictate structure. Domain decides format. |
Extract what an agent cannot discover from code and write it into AGENTS.md. Audit existing AGENTS.md against four principles. Sections emerge from the project's domain — there is no universal template.
These govern ALL AGENTS.md decisions. Derived from OpenAI best practices + clean philosophy.
Rule: If an agent can discover it by reading code, running ls, or inspecting config files — don't write it.
| Write (implicit) | Don't write (discoverable) |
|---|---|
| Which directory is the canonical state root (vs archive) | File tree structure (ls already shows this) |
WHY a non-standard tool was chosen (uv not pip) | That React is used (package.json already says this) |
| Pipeline phase ORDER and checkpoint positions | Individual phase contracts (each SKILL.md already defines these) |
| Intent routing logic | Domain skill names (discoverable from skills directory) |
Commit message convention (type(scope): description) | Lint rules (linter already enforces these) |
Test: Delete the content. Run the agent on the project. If the agent still does the right thing → the content was discoverable.
Rule: Sections emerge from what the project DOES, not from a template. A design project doesn't need a pipeline section. A research project doesn't need commit conventions.
Common domain archetypes and their natural sections:
| Domain | Natural Sections |
|---|---|
| Code project (app, library, service) | Tech stack, dev commands, invariants, boundaries, commit conventions |
| Methodology / harness (agents-stack) | Pipeline, checkpoints, invariants, safety rules, cold-start protocol |
| Design system | Component library, tokens, principles, review protocol |
| Research / knowledge base | Scope, methodology, sources, output format |
| AI agent / infra | Agent architecture, model routing, tool conventions, safety boundaries |
Start by asking: "What does an agent working on this project MOST need to know that it can't discover?" The answer IS the section list.
Rule: ~60 lines is ideal. >150 is a warning. >300 is almost certainly redundant with discoverable content.
Not a hard limit — a diagnostic. When AGENTS.md grows:
Rule: AGENTS.md compliance rate is ~70%. Rules that MUST be enforced (security, data integrity) need hooks or tool-level guards, not just AGENTS.md entries.
| AGENTS.md is right for | Hooks/tools are right for |
|---|---|
"Prefer uv over pip" | "NEVER push to main" |
| "Tests must pass before commit" | "NEVER commit secrets" |
| "Load SKILL.md before executing phase" | "NEVER modify reference/ outside release" |
If a rule appears in both the AGENTS.md Safety section AND a tool hook → the AGENTS.md entry is still valuable (it explains WHY), but don't rely on it for enforcement.
| Question | If YES | If NO |
|---|---|---|
| Is this implicit (agent can't discover from code)? | Keep | Flag for removal |
| Is this duplicated in another referenced file? | Flag for removal | Keep |
| Is this domain-relevant (does this project actually DO this)? | Keep | Flag for removal |
| Is this a hard enforcement rule? | Note: needs hook | AGENTS.md is sufficient |
Static content at the top maximizes cache hits. Dynamic content (routing, workstream references) goes at the bottom or in external files.
The ideal order (emerges naturally from the principles, not a template):
pnpm dev, pytest -v)When auditing, produce findings in this format:
## AGENTS.md Audit
**Project:** [name] | **Domain:** [archetype] | **Lines:** [N]
### Implicit Knowledge Gaps
[What should be in AGENTS.md but isn't — agent would get this wrong]
### Discoverable Content
[What's in AGENTS.md but agent can find from code — candidate for removal]
| Section | Content | Discoverable From | Recommendation |
|---------|---------|------------------|----------------|
### Length Check
[Current lines vs ~60 target. Which sections are the biggest contributors?]
### Compliance Notes
[Which rules need hooks, not just AGENTS.md entries?]
AGENTS.md exists (or audit report delivered). Every line passes the implicit knowledge test. Sections emerge from domain, not template. Static content precedes dynamic. Compliance ceiling noted where relevant.