Content
85%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 lean, well-sequenced instruction-only skill: concrete enumeration and validation commands, explicit checkpoints, and decision loops for ambiguity, all in a tight, well-sectioned body without bundle overhead. The main improvement space is supplying the actual search patterns it enumerates and tightening repeated overclaim warnings.
Suggestions
Provide ready-to-use ripgrep patterns (or a short parser one-liner) for the enumerated candidates — Markdown links/images, HTML a[href]/img[src], headings, code fences, repeated words — so the enumeration is directly executable.
Consolidate the three repetitions of the do-not-overclaim guidance (scope item 3, the candidate-list caveat, and the final reporting rule) into one clearly placed rule to trim tokens.
Replace 'Run applicable formatting/quality checks' with the specific commands the target repository uses (or state how to discover them), matching the specificity already shown for the two ci/doc check scripts.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and prescriptive with no explanations of concepts Claude already knows, but the do-not-overclaim theme is repeated three times (scope item 3, 'Search output is a candidate list, not proof that all links were found', and 'Never state that all documentation is error-free') and several layered sentences could be trimmed, fitting efficient-with-minor-overexplanation rather than every-token-earns-its-place. | 4 / 5 |
Actionability | Concrete copy-paste commands are provided (`git ls-files --cached --others --exclude-standard -- '*.md' '*.mdx'`, `python scripts/ci/docs/check_doc_task_paths.py`, `git diff --check`) along with concrete procedures for relative-path resolution, fragment/permalink checks, and line-anchor verification; however, no actual search patterns are given for the enumerated link/heading types, and 'Use an available Markdown parser or renderer' and 'Run applicable formatting/quality checks' are vague, keeping it below fully-executable. | 4 / 5 |
Workflow Clarity | A clear phase sequence (Scope and baseline → Mechanical checks → Meaning and language → Edit and validate) with numbered checklists, explicit validation steps (`git status --short` before editing, recheck each changed link, Sphinx build warnings, `git diff --check`, inspect the final diff), and feedback loops for error recovery ('Fix only when the destination is clear; otherwise report the uncertainty with file and line'); the batch nature of the work is covered by validation, so no cap applies. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are all absent) and the ~37-line body has no need for external references; per the simple-skill guideline, the six well-organized section headers and absence of nested or buried references earn the top score. | 5 / 5 |
Total | 18 / 20 Passed |