Content
96%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.
This is a high-quality instruction-only skill body: lean, dense with executable grep commands and exact paths, and a clearly sequenced procedure with an explicit re-grep-to-zero verification step and a completion checklist. The only structural improvement would be moving the repo-specific documentation-surface map into a one-level reference file.
Suggestions
Move the agent-workflows doc-surface listing in step 2 (documentation/ pages, interfaces inventory, AGENTS.md, project workspace) into a clearly signaled reference file (e.g. doc-surface.md) so the core procedure stays scannable while repo-specific detail is progressively disclosed.
The 'When this applies' bullet list partially duplicates the frontmatter description's trigger conditions; consider trimming it to the delta (e.g. the file/symbol-citation case) to save tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and operational with no explanation of concepts Claude already knows — e.g. "If you removed a thing, delete its page and its index row, not just its prose" and "Two copies drift; a pointer does not" compress policy into single terse lines. The brief opening rationale earns its place by justifying the deletion and cross-link rules, so it fits 'every token earns its place' rather than the 4 anchor's 'minor instances of over-explanation'. | 5 / 5 |
Actionability | Guidance is copy-paste ready: executable commands like `grep -rn "<old name or field>" docs/ --include=*.md` and `rg -l ... --glob '**/AGENTS.md'`, exact paths ("docs/design/agent-workflows/interfaces/"), and concrete field-level specifics ("the row and its Status column: stable / evolving / declared-not-wired"). For an instruction-only skill this fully matches the 'specific examples cover the common cases' anchor; the placeholder in the grep commands is appropriate templating, not pseudocode. | 5 / 5 |
Workflow Clarity | A five-step procedure is clearly sequenced with an explicit validation/feedback loop — step 5: "Re-grep for the old name to confirm zero stragglers. Check that any file or line citation you touched still resolves" — reinforced by a pre-done checklist. This matches the top anchor (explicit validation, error-recovery re-check, checklist) for what is a batch edit operation, and is clearly above the 4 anchor's 'minor validation gaps'. | 5 / 5 |
Progressive Disclosure | The single file is well organized into clear sections (When this applies / The procedure / external-integration caveat / checklist) with no nested or buried references, matching 'good structure; most content is appropriately placed'. It stops short of 5 because the body runs well past 50 lines and the repo-specific doc-surface map in step 2 (documentation/ pages, inventory, AGENTS.md, project workspace) is bulky enough that it could live in a clearly signaled one-level reference file, keeping the procedure itself tighter. | 4 / 5 |
Total | 19 / 20 Passed |