Content
82%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, actionable instruction skill that provides concrete templates and a clear writing workflow. Its main weakness is redundancy between the 'Required Sections' templates and the 'Example Structure' section, and the absence of an explicit verification step for the stated line-count target.
Suggestions
Consolidate 'Example Structure' so it references or trims the Commit Attribution and File-Scoped Commands templates already shown under 'Required Sections' rather than duplicating them verbatim.
Add an explicit validation checkpoint after writing, e.g. 'Verify the file is under 60 lines and contains no linter/config rules duplicated from .eslintrc/biome.json/ruff.toml'.
Tighten the brief opening paragraph ('AGENTS.md is the canonical agent-facing documentation...') or fold its line-count guidance into the validation step to reduce token overhead.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean (headers + bullets + template code blocks) and avoids explaining concepts Claude already knows, but the 'Example Structure' section duplicates the Commit Attribution block and File-Scoped Commands table already shown in 'Required Sections', so it could be tightened further. | 4 / 5 |
Actionability | Highly actionable for an instruction-only skill: copy-paste-ready markdown templates, concrete symlink command, named lock-file/config detection lists, and command tables cover the common cases. | 5 / 5 |
Workflow Clarity | A clear sequence exists (File Setup → Before Writing analysis → Writing Rules → Required Sections → Anti-Patterns) with the Anti-Patterns list acting as a checklist, but there is no explicit verification step for the stated 'under 60 lines; never exceed 100' target. | 4 / 5 |
Progressive Disclosure | Well-organized into clearly labeled sections with no nested references and a self-contained structure, but at ~113 lines with some template redundancy it sits just below the fully lean, optimally split top anchor. | 4 / 5 |
Total | 17 / 20 Passed |