agents-md

Original：🇺🇸 English

Translated

Audits AGENTS.md and CLAUDE.md files using execution-first standards. Checks commands, gotchas, and signal-to-noise ratio. Use when asked to audit, review, score, refactor, or improve agent instruction files, fix stale commands, or reduce bloat.

9installs

Sourcemblode/agent-skills

Added on2026-02-07

NPX Install

npx skill4agent add mblode/agent-skills agents-md

SKILL.md Content

View Translation Comparison →

AGENTS.md / CLAUDE.md Audit

AGENTS.md and CLAUDE.md are execution contracts, not knowledge bases.

Litmus test for every line: "Would removing this cause the agent to make a mistake?" If no, cut it. Bloated instruction files cause agents to ignore actual rules.

Reference Files

File	Read When
`references/quick-checklist.md`	Default: fast triage (10 checks, target >= 8/10)
`references/quality-criteria.md`	Full audit mode or when quick audit fails
`references/refactor-workflow.md`	File is bloated (>150 lines) or low-signal
`references/root-content-guidance.md`	Deciding what stays in root vs separate files
`references/templates.md`	Drafting new file or rebuilding from scratch

Quick Example

Input: AGENTS.md with stale commands and generic advice Quick audit result: 5/10 (Fail) Key issues: Missing test command, generic "follow best practices" advice, dead link to deleted folder Fix: Add

npm test

, replace generic advice with specific gotcha, remove dead link After: 9/10 (Pass)

How to Use

Default path:

Start with quick audit using
```
references/quick-checklist.md
```
(10 checks)
Escalate to full audit (
```
references/quality-criteria.md
```
) only when quick audit fails, file is high-risk, or user requests it
Apply edits only after reporting findings and getting confirmation

Progressive loading:

Always load the checklist for the selected audit mode
Load
```
references/refactor-workflow.md
```
only for low-signal files (below target score, stale commands, or root file over ~150 lines)
Load
```
references/templates.md
```
only when drafting a new file or rebuilding from scratch
Load
```
references/root-content-guidance.md
```
only when deciding what stays in root vs moved out

Audit Workflow

Copy this checklist to track progress:

Audit Progress:
- [ ] Step 1: Discover files
- [ ] Step 2: Select audit mode (quick or full)
- [ ] Step 3: Run audit against checklist
- [ ] Step 4: Report findings with score table
- [ ] Step 5: Propose minimal diffs
- [ ] Step 6: Validate changes
- [ ] Step 7: Apply and verify

Step 1: Discover files

Run:

bash

find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) 2>/dev/null | sort

Also check for a home-level file:

~/.claude/CLAUDE.md

(applies to all sessions).

CLAUDE.md files can exist at multiple levels — project root, parent directories, and child directories are all loaded automatically.

CLAUDE.local.md

is the gitignored personal variant. Audit each level independently.

For monorepos, include workspace-level instruction files.

Step 2: Select audit mode

Quick audit: Default for most files (10 checks, target >= 8/10)
Full audit: When quick audit fails, file is high-risk, or user requests full scoring

Step 3: Run audit

Quick audit target: >= 8/10 checks from
```
references/quick-checklist.md
```
Full audit file-quality target: >= 91% of applicable points from
```
references/quality-criteria.md
```
Full audit execution target: 2/2 when producing an edit proposal
Score each root file independently

Step 4: Report findings

Output a concise report before edits:

markdown

## AGENTS.md Quality Report

| File | Mode | Score | Grade | Key Issues |
|------|------|-------|-------|------------|
| ./AGENTS.md | Quick | 6/10 | Fail | Missing test command, stale path, doc-heavy section |

Step 5: Propose minimal diffs

Fix broken/stale commands first
Remove generic, duplicate, or obsolete guidance
Move deep detail into linked files using
```
@path/to/file.md
```
import syntax
Use emphasis ("IMPORTANT:", "YOU MUST") on critical rules that agents tend to skip
Keep rewrites incremental and preserve useful wording when possible

Show each proposed change with rationale and a diff snippet.

Step 6: Validate changes

Validation loop:

Run smoke checks for core commands (
```
dev
```
,
```
test
```
,
```
build
```
,
```
lint/typecheck
```
) when applicable
If commands cannot be run, verify script existence and note the limitation
Check that linked paths resolve
Confirm no contradictory rules remain
If issues found → revise → validate again
Only proceed when validation passes

Step 7: Apply and verify

Apply approved edits
After each PR, add at most one new gotcha only if it prevented or fixed a real mistake
Verify changes by re-running relevant commands