Content
78%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 whose 8-step workflow, anti-patterns, and one-level-deep bundle references (all verified to exist) are near-exemplary. It falls short of top marks on a broken template path in Quick Commands, validators not wired into the workflow steps, and minor trimmable sections (Mindset, MCP JSON config).
Suggestions
Fix the Quick Commands path: `cp templates/REFERENCE-paper.md references/<slug>.md` references a nonexistent file — align it with step 4, which reads `assets/templates/REFERENCE-paper.yaml` for structure rather than copying a .md template.
Wire validation into the workflow: add an explicit step after creating `references/<slug>.md` to run `./scripts/validate-reference-paper.sh` and fix-and-re-run on failure, rather than leaving the validators only in Quick Commands; also add the `analysis/` prefix to the validate-analysis command.
Trim the "Mindset" section and the mcpServers JSON block — the package names and fallback ordering (semantic-scholar → google-scholar → WebFetch) carry the needed information in fewer tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and operational (exact paths, table row formats, commands) with almost no explanation of concepts Claude already knows, but the "Mindset" section and the full mcpServers JSON block are trimmable — package names plus the fallback ordering would carry the same information. Not 5 because of these minor instances of over-explanation; not 3 since nothing is padded beyond them. | 4 / 5 |
Actionability | Concrete, executable guidance throughout: slug derivation with examples ("jiang-llmlingua"), grep/curl/validator commands, exact REVIEWED.md row and section formats, and template paths. Not 5 because Quick Commands contains a broken reference — `cp templates/REFERENCE-paper.md references/<slug>.md` points to a nonexistent file and contradicts step 4's "Read assets/templates/REFERENCE-paper.yaml" — and the validate-analysis command omits the `analysis/` prefix from step 8's path. | 4 / 5 |
Workflow Clarity | The 8-step workflow is clearly sequenced with a hard checkpoint ("If already present, report it and stop") reinforced by an anti-pattern. Not 5: the validator scripts appear only in Quick Commands rather than as explicit validate-and-fix steps inside the workflow (step 4 never says to run validate-reference-paper.sh on the created file), so the feedback loop is implicit. | 4 / 5 |
Progressive Disclosure | SKILL.md stays an overview: frontmatter/section structure is delegated to templates ("Read assets/templates/REFERENCE-paper.yaml to get the required frontmatter fields"), and a closing References section signals each artifact with a link. All six referenced bundle files exist and are one level deep with no nesting, matching the well-signaled clear-overview pattern. | 5 / 5 |
Total | 17 / 20 Passed |