Agentic-AI-Template/Codex/plugins/agents-md-management v2/1.0.0/skills/auditing-agents-md/references/quality-criteria.md

AGENTS.md Quality Criteria

Assessment Order

1. Read each selected instruction file completely.
2. Map its scope and place in the active chain.
3. Cross-reference every factual claim with repository evidence.
4. Score all six criteria independently.
5. Add the scores, assign a grade, and list evidence-backed issues.

Scoring Rubric

Commands and Workflows - 20 points

• 20: Essential setup, build, test, lint, and handoff commands are current, scoped, and copy-paste ready.
• 15: Most essential commands are accurate; minor context is missing.
• 10: Only basic commands are present or important workflow context is absent.
• 5: Several commands are missing or stale.
• 0: No usable commands are documented.

Repository Map and Instruction Scope - 20 points

• 20: Important directories and relationships are accurate; root, nested, and override rules are placed at the narrowest correct scope.
• 15: The map and scope are useful with minor omissions.
• 10: A directory list exists but relationships or scope are unclear.
• 5: Paths or precedence are substantially misleading.
• 0: No usable map exists or the file governs the wrong content.

Non-Obvious Constraints and Gotchas - 15 points

• 15: Recurring quirks, prerequisites, ordering constraints, and reliable workarounds are concise and evidenced.
• 10: Some important non-obvious constraints are documented.
• 5: Only minimal or weakly supported constraints are present.
• 0: Important recurring gotchas are absent.

Conciseness and Duplication - 15 points

• 15: Every line earns prompt space; no filler, obvious facts, or duplicate rules exist across the active chain.
• 10: Mostly concise with limited repetition.
• 5: Noticeable verbosity, duplication, or misplaced detail.
• 0: Mostly filler or repeated content.

Also report the combined selected-file byte count. The default project_doc_max_bytes is 32 KiB; use the configured value when repository or user config proves a different limit.

Currency Against the Codebase - 15 points

• 15: Commands, paths, versions, architecture, and tool names match current repository evidence.
• 10: Mostly current with minor staleness.
• 5: Several claims are outdated or unverified.
• 0: Guidance is severely stale or misleading.

Actionability and Verifiability - 15 points

• 15: Instructions are concrete, safely verifiable, and include clear completion expectations.
• 10: Mostly actionable with small ambiguities.
• 5: Several vague or untestable rules remain.
• 0: Guidance is theoretical or unusable.

Grades

Score	Grade	Meaning
90-100	A	Comprehensive, current, concise, and actionable
70-89	B	Good guidance with minor gaps
50-69	C	Useful basics with important omissions
30-49	D	Sparse, stale, conflicting, or poorly scoped
0-29	F	Missing or severely misleading

Red Flags

• A command missing from the relevant manifest or task runner.
• A reference to a deleted or moved path.
• Root and nested rules that conflict without an intentional override.
• The same rule repeated across the active chain.
• A broad file containing rules true only for one subtree.
• An override used when additive nested guidance was intended.
• Combined guidance near or beyond the configured byte limit.
• Templates copied without real paths, commands, or repository details.