Content
14%Scale 1-3Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads as an exhaustive Bash reference manual rather than a focused, actionable skill document. It covers an enormous breadth of topics—many of which Claude already knows—without providing clear workflows, complete executable examples, or progressive disclosure. The content would benefit dramatically from being restructured into a concise overview with detailed sections split into bundle files.
Suggestions
Reduce the SKILL.md to a concise overview (under 80 lines) with a complete script template showing strict mode, argument parsing, cleanup traps, and logging in one executable example, then move detailed sections (tools, advanced techniques, CI/CD, security) into separate bundle files.
Replace the vague 4-step Instructions with a concrete workflow including validation checkpoints, e.g.: '1. Create script with strict mode header → 2. Add argument parsing with getopts → 3. Run ShellCheck: `shellcheck --enable=all script.sh` → 4. Fix issues and re-run → 5. Add Bats tests → 6. Verify tests pass before committing.'
Remove content Claude already knows (basic parameter expansion, brace expansion, conditional execution, what tools like jq and curl do) and focus only on project-specific conventions, non-obvious patterns, and opinionated decisions.
Add a complete, copy-paste-ready script template that demonstrates the key patterns (strict mode, argument parsing, logging, cleanup traps, error handling) working together in a real example.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 300+ lines with extensive lists of bullet points covering topics Claude already knows well (basic Bash features, parameter expansion, brace expansion, conditional execution). Many sections read like a Bash textbook rather than adding novel, targeted guidance. Significant redundancy across sections (e.g., error trapping mentioned in multiple places). | 1 / 3 |
Actionability | Contains many concrete code snippets and specific commands (e.g., strict mode, mktemp patterns, find -print0 idioms), but most are isolated one-liners rather than executable, complete examples. No full script template or copy-paste-ready starter is provided. The 'Instructions' section is only 4 vague steps without concrete implementation details. | 2 / 3 |
Workflow Clarity | The 4-step Instructions section is extremely vague ('Define script inputs, outputs, and failure modes', 'Implement core logic with defensive patterns') with no concrete sequencing, validation checkpoints, or feedback loops. For a skill involving destructive operations (file manipulation, CI/CD pipelines), there are no explicit validation steps in any workflow. The content is organized as reference lists rather than actionable workflows. | 1 / 3 |
Progressive Disclosure | Monolithic wall of text with no bundle files to offload detailed content. Sections like 'Advanced Techniques', 'Essential Tools', 'Modern Bash Features', 'References & Further Reading' could all be separate files. Everything is inlined into one massive document with no layered structure or navigation aids. | 1 / 3 |
Total | 5 / 12 Passed |