Content
56%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 dense, highly actionable rulebook whose commands, gates, and output templates are concrete and executable — but it is a single monolithic 635-line file that repeats its core taxonomy several times and inlines everything rather than splitting CLI reference or dossier specs into bundle files. Strong on actionability and workflow discipline, weak on token efficiency and progressive disclosure.
Suggestions
Define the claim-level taxonomy once (e.g., in a 'Claim Levels' reference file) and have 'Core Rules', 'Dossier Mode', and 'Output Shape' point to it instead of restating it four times.
Move the gitcrawl CLI command catalog and the upstream-refresh/update machinery into references/ files (e.g., references/gitcrawl-cli.md, references/upstream-refresh.md), keeping SKILL.md as a routing overview.
Merge the repeated install/health-check command blocks ('Gitcrawl Install', '<update>' step 1, 'Archive-First Discovery') into one canonical baseline block and reference it.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~635 lines the body restates the same claim-level taxonomy (fixes-claimed / improves-claimed / cluster-synced / needs-repro / needs-human) in at least four places ('Core Rules', 'Claim Levels', 'Dossier Mode', 'Output Shape'), and the gitcrawl command set is repeated across the 'Gitcrawl Install', '<update> Mode', and 'Archive-First Discovery' sections. This matches 'noticeably verbose; several unnecessary explanations or padded sections' — accurate throughout, but clearly padded with repetition. | 2 / 5 |
Actionability | The guidance is overwhelmingly executable: exact gitcrawl CLI invocations with JSON field lists ('gitcrawl sync ianstormtaylor/slate --numbers <ref> --include-comments --with pr-details --json'), concrete ledger file paths, a copy-paste dossier markdown template, and an exact output shape. It misses 5 only because several commands depend on placeholders and external state (../clawsweeper checkouts, brew taps, ledger files not present in the skill bundle) rather than self-contained examples covering common cases. | 4 / 5 |
Workflow Clarity | The Small-Fix Sweep Loop gives a clear numbered 8-step sequence with an all-gates checklist, skip rules, and explicit 'if no issue qualifies, say so' guard; the '<update>' mode ends with a sync-verification step ('rg -n ... .agents/rules/clawsweeper.mdc'), and Verification Discipline encodes reproduce → fix → rerun → broaden with Hard Stops as escalation checkpoints. It falls short of 5 because the interleaving of seven pulled-in disciplines into one flow leaves some sequences implicit (e.g., when Dossier Mode is entered relative to the sweep loop), and error-recovery loops for ledger updates are named but not fully specified. | 4 / 5 |
Progressive Disclosure | There is real structure — well-labeled sections and an ordered 'Source Of Truth' list of external ledger files — but the skill bundle contains no reference files at all, so ~635 lines of gitcrawl CLI reference, dossier-mode spec, and upstream-refresh procedure are all inlined in SKILL.md. That matches 'some structure but content that should be separate is inline'; it avoids a 2 only because the section headers keep navigation possible and the external file references are clearly signaled, unlike the header-less anchor example. | 3 / 5 |
Total | 13 / 20 Passed |