Content
38%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 rich in concrete POSIX guidance but heavily redundant — the same rules are restated in three to four sections — and organized as a monolithic 295-line reference file with a dangling pointer to a nonexistent playbook. Broken snippet syntax and the absence of any complete worked example further weaken actionability.
Suggestions
Deduplicate: consolidate 'POSIX Constraints', 'Common Pitfalls to Avoid', and 'POSIX-Specific Best Practices' into a single canonical section (each rule currently appears 3-4 times), cutting the body roughly in half.
Fix the dangling reference: either create resources/implementation-playbook.md and move the reference-grade sections (Essential Tools, CI/CD, Migration, Output) into it, or remove the pointer.
Replace broken/pseudocode snippets (the heredoc-less 'Newline-Separated' pattern, 'mktemp() { ... }') with one complete, executable example script demonstrating the core patterns end-to-end with a validate→fix→retry loop (e.g., shellcheck -s sh, fix, re-run).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~295-line body repeats the same guidance across four sections: 'Quote all variable expansions' appears in Approach, Safety & Security Patterns, and POSIX-Specific Best Practices; 'use [ not [[' appears in POSIX Constraints, Approach, Common Pitfalls, and POSIX-Specific Best Practices; printf-vs-echo and '.'-vs-'source' each appear 3+ times. Much of it (quoting, command -v, traps) is knowledge Claude already has. This is noticeably padded — anchor 2 — though it doesn't explain basic concepts from scratch, so not 1. | 2 / 5 |
Actionability | Many concrete one-liners ('trap 'rm -f "$tmpfile"' EXIT INT TERM', 'shellcheck -s sh *.sh && shfmt -ln posix -d *.sh', 'case $num in *[!0-9]*) exit 1 ;; esac'), but several snippets are broken or pseudocode: the 'Newline-Separated' pattern ends with a dangling '<<EOF' and no heredoc body, and 'mktemp() { ... }' is a literal placeholder. No complete executable script example exists. Fits anchor 3 — concrete guidance present but incomplete, with pseudocode where executable code should be. | 3 / 5 |
Workflow Clarity | No multi-step workflow with validation checkpoints. The 'Migration from Bash to POSIX sh' section lists a rough sequence (checkbashisms assessment → convert arrays/conditionals → incremental testing) but validation is named, not sequenced — there is no validate→fix→retry loop. The Quality Checklist lists validation criteria but is not embedded in any workflow. Fits anchor 3: sequence present, checkpoints missing or implicit. Not capped lower since this is not a destructive/batch-operation skill. | 3 / 5 |
Progressive Disclosure | The body references 'resources/implementation-playbook.md' but no resources/ directory exists in the bundle — a dangling reference. Meanwhile ~300 lines of reference-grade material (Essential Tools, CI/CD Integration, Migration, Output) are inlined monolithically. Section headers provide some structure (above anchor 2's 'no structure'), but content that clearly belongs in separate files is inlined and the single reference is broken, which tips it to anchor 2 rather than 3. | 2 / 5 |
Total | 10 / 20 Passed |