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.
The body is highly actionable and well-structured: an executable entry-point command, a templated response format, and a genuine progressive-disclosure layout backed by a complete, verifiable bundle. The main weaknesses are redundancy — the Mindset section and the Anti-Patterns section make the same four points twice — and a workflow that stops before re-validating fixes or folding in the runtime sandbox-testing step the Mindset itself mandates.
Suggestions
Collapse the Mindset section into the Anti-Patterns section (or vice versa): the four NEVER rules already restate, with WHY/BAD/GOOD framing, every point the Mindset paragraph makes, so one of the two can be deleted outright with no loss of guidance.
Add a closing feedback step to the Required Workflow, e.g. "6. Re-run: bash scripts/validate.sh <script-path> and repeat until no errors remain; then test the script with representative inputs in a sandbox", so the fix→verify loop the Mindset mandates is an explicit checkpoint rather than prose.
Trim or merge the 'Validation Logic' section into the 'Example Output' sample — the seven logic steps re-describe behavior the sample output and exit-code table already demonstrate.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The Mindset paragraph and the four Anti-Patterns each restate the same four points (runtime testing over ShellCheck, global SCxxxx suppressions, sh-vs-bash shebang mismatch, exit-code swallowing with `|| true`/`exit 0`), and "Validation Logic" re-describes what the "Example Output" sample already demonstrates. It is not 4 because this duplication is more than minor trimming — roughly the whole Mindset section is repeated with WHY/BAD/GOOD framing — and not 2 because nothing explains concepts Claude doesn't know and every section still carries some signal. | 3 / 5 |
Actionability | Guidance is fully executable: the copy-paste command "bash scripts/validate.sh <script-path>", a ready-to-use Response Format Template showing exactly how to present each issue (problem/reference/fix/why), concrete install commands for three options, documented exit codes (0/1/2), and a realistic sample of validator output. It is not 4 because there are no gaps — the common case (run validator, report each issue in the templated format) is covered end to end with copy-paste-ready material. | 5 / 5 |
Workflow Clarity | The Required Workflow is a clear numbered sequence (run validator → read output → consult common-mistakes.md / shellcheck-reference.md → per-issue show/explain/fix/why), but there is no "re-run the validator to confirm the fixes" checkpoint, and the Mindset's mandated sandbox execution of the script never appears as a workflow step. It is not 5 because the fix→verify feedback loop is missing, and not 3 because the sequence is explicit, concrete, and includes per-issue handling with pointed reference lookups rather than having only implicit checkpoints. | 4 / 5 |
Progressive Disclosure | SKILL.md stays an overview — workflow, output format, install, and anti-patterns — with all detail pushed one level deep into real bundle files (all 8 references/*.md, both scripts, and all 4 assets exist and match the Layout section), each listed with a one-line description, and the workflow says exactly when to open common-mistakes.md versus shellcheck-reference.md. It is not 4 because navigation is essentially complete: references are clearly signaled, correctly scoped, and nothing that belongs in a bundle file is inlined. | 5 / 5 |
Total | 17 / 20 Passed |