Feedback on your shell-scripting skill

[RichardHightower]

I took a look at your shell-scripting skill and wanted to share some thoughts.

Links:

• GitHub
• Your shell-scripting skill in the SkillzWave marketplace

The TL;DR

You're at 79/100, which puts you in solid C territory. This is based on Anthropic's 5-pillar skill best practices. Your strongest area is Utility (17/20) — the defensive programming patterns and ShellCheck integration genuinely solve real problems. The weakest area is Progressive Disclosure Architecture (18/30), which is the main thing holding you back from a B grade.

What's Working Well

• Practical defensive patterns — Your mandatory foundations (set -euo pipefail, error handling) address real gaps in how most people write shell scripts. The ShellCheck integration as a validation loop is solid.
• Clear structure within the single file — Section headers are logical, patterns are numbered, and the Quick Reference Checklist gives people a concrete path forward. That's good teaching.
• Solid examples — You show complete, runnable templates (simple script, main-function pattern). The Wrong/Correct pairs demonstrate actual anti-patterns developers encounter.
• Good bonus points — The grep-friendly structure and quality pre-commit checklist earned you extra points. Those details matter.

The Big One: Split This Into Multiple Files

Here's the issue: your skill is 574 lines in a single SKILL.md file. That violates progressive disclosure architecture, which Claude skills are supposed to follow. You pack Mandatory Foundations, Core Safety Patterns, Intermediate Patterns, Advanced patterns, and Anti-Patterns all into one file.

Why it matters: New users get overwhelmed. Advanced users have to scroll through basics. Token economy suffers — you're forcing people to load everything to get what they need.

The fix: Restructure like this:

• SKILL.md (~150 lines): When to use shell, Mandatory Foundations (set -euo pipefail, error handling), one Core Safety Pattern example
• references/intermediate-patterns.md: Input validation, logging patterns, configuration management
• references/advanced-patterns.md: Dry-run pattern, state management, complex error recovery
• references/anti-patterns.md: Current "Wrong" examples called out explicitly

Add a table of contents to SKILL.md linking to each section. This gets you +6 points.

Other Things Worth Fixing

1. Tighten the verbose examples — Some of your Wrong/Correct pairs take 15+ lines for a concept that could be shown in 5. Consider comparison tables or inline comments instead of separate code blocks. Small win, but cleans up readability.

2. Add more trigger phrases to the description — Currently you mention "bash scripting" but could be explicit: "Use when writing shell scripts, bash automation, deployment scripts, build scripts, CI/CD workflows, or needing ShellCheck compliance." Helps discoverability.

3. Add a proper TOC — A 500+ line file needs navigation. Add ## Contents with anchor links right after the frontmatter. Takes 5 minutes, improves usability significantly.

Quick Wins

• Biggest impact: Split into SKILL.md + reference files (+6 points)
• Quick additions: TOC for navigation (+2 points)
• Polish: Trigger phrases in description, tighten verbose examples (+2 points)

You've built something genuinely useful here. These changes are about structure and organization, not rethinking your content. Get those files split and you'll be at 87/100 easily.

---

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.