Agentic-AI-Template/plugins/agents-md-management/skills/agents-md-improver/references/quality-criteria.md

AGENTS.md Quality Criteria

Scoring Rubric

1. Commands and Workflows - 20 points

20 points: all essential commands documented with context.

• Build, test, lint, format, dev, and deploy commands are present when relevant.
• Development workflow is clear.
• Common operations and verification expectations are documented.

15 points: most commands present, some missing context.

10 points: basic commands only, little workflow.

5 points: few commands, many missing.

0 points: no commands documented.

2. Architecture Clarity - 20 points

20 points: clear codebase map.

• Key directories explained.
• Module relationships documented.
• Entry points identified.
• Data flow described where relevant.

15 points: good structure overview, minor gaps.

10 points: basic directory listing only.

5 points: vague or incomplete.

0 points: no architecture info.

3. Non-Obvious Patterns - 15 points

15 points: gotchas and quirks captured.

• Known issues documented.
• Workarounds explained.
• Edge cases noted.
• Unusual "why this way" rules explained briefly.

10 points: some patterns documented.

5 points: minimal pattern documentation.

0 points: no patterns or gotchas.

4. Conciseness - 15 points

15 points: dense, valuable content.

• No filler or obvious info.
• Each line adds value.
• No redundancy with code comments or README basics unless Codex specifically needs it.

10 points: mostly concise, some padding.

5 points: verbose in places.

0 points: mostly filler or restates obvious code.

5. Currency - 15 points

15 points: reflects current codebase.

• Commands work as documented.
• File references are accurate.
• Tech stack and architecture are current.

10 points: mostly current, minor staleness.

5 points: several outdated references.

0 points: severely outdated.

6. Actionability - 15 points

15 points: instructions are executable.

• Commands can be copied and run.
• Steps are concrete.
• Paths are real.
• Verification expectations are clear.

10 points: mostly actionable.

5 points: some vague instructions.

0 points: vague or theoretical.

Assessment Process

1. Read each instruction file completely.
2. Cross-reference with the actual codebase.
3. Check documented commands against package manifests, scripts, and config.
4. Verify file and directory references.
5. Score each criterion.
6. Calculate total and assign grade.
7. List specific issues.
8. Propose concrete, concise improvements.

Red Flags

• Commands that would fail.
• References to deleted files or folders.
• Outdated tech versions.
• Placeholder template content.
• Generic advice not specific to the project.
• Duplicate or contradictory guidance across nested instruction files.
• An AGENTS.override.md that accidentally hides a sibling AGENTS.md.