Content
81%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.
An exemplary policy skill: lean, entirely repo-specific, with a sequenced workflow, executable validation commands, and an explicit recovery path. Remaining gaps are minor — a placeholder in the lint command and slight redundancy in restating the line caps.
Suggestions
Make the lint step fully copy-paste ready by replacing '<other-changed-markdown>' with a concrete expansion instruction, e.g., 'npx markdownlint-cli AGENTS.md docs/<changed-files>'.
Consolidate the repeated 120-line cap statements (Hard constraints, Workflow step 7, Validation) so each mentions the check once with a single authoritative command list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense policy prose with zero filler or explanation of concepts Claude already knows — every rule is repo-specific. It sits at 4 rather than 5 because the 120-line cap is restated across 'Hard constraints', 'Workflow' step 7, and the 'Validation' block, a minor redundancy that could be consolidated. It is well above the 'mostly efficient but includes some unnecessary explanation' of 3. | 4 / 5 |
Actionability | Concrete, executable guidance dominates: exact commands ('wc -l AGENTS.md', 'wc -l .claude/skills/steward/SKILL.md', 'npx markdownlint-cli AGENTS.md <other-changed-markdown>'), named file paths, numeric caps, and a numbered workflow. It falls short of the copy-paste-ready 5 anchor because '<other-changed-markdown>' is an unfilled placeholder and several constraints ('Confirm every protected template remains directly usable') are checkable only by judgment, not command. | 4 / 5 |
Workflow Clarity | The 8-step workflow is clearly sequenced with baseline capture (step 1 'Record the baseline with wc -l AGENTS.md'), embedded checkpoints (steps 6-7), a dedicated 'Validation' section of executable checks, and an explicit error-recovery path ('When the cap is exceeded, move a whole concern to its focused owner'). This matches the anchor for clear sequence with explicit validation steps and feedback loops for error recovery. | 5 / 5 |
Progressive Disclosure | A single-file skill (~70-line body) with well-organized sections and clearly signaled, one-level-deep document routes ('docs/repository-workflow.md', 'the steward skill', etc.) in the 'Ownership test'. It scores 4 rather than 5 because the body exceeds the under-50-line simple-skill threshold and the seven-entry routing list is a fairly dense inline index — good structure with minor organization polish remaining, not the ideal split of the 5 anchor. | 4 / 5 |
Total | 17 / 20 Passed |