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 agentic skill in the SkillzWave marketplace

The TL;DR

You're at 65/100, which puts you in D territory – this one needs some work before it's ready to ship. The grading is based on Anthropic's skill best practices across 5 pillars. Your strongest area is Spec Compliance (12/15) – the frontmatter and metadata are solid. The biggest drag is Progressive Disclosure Architecture (19/30) – you're cramming everything into one 170-line file when it should be layered and modular.

What's Working Well

• Valid metadata: Your YAML frontmatter is clean, triggers like 'shell script', 'bash', and 'zsh' are solid
• Good template: You've included a safe script template with proper error handling patterns – that's useful
• Clear section structure: Headers for core competencies, patterns, and tools make it easy to navigate within the file
• Practical patterns: The examples actually address real scripting needs (argument parsing, error handling, etc.)

The Big One: No Layered Architecture

Here's what's holding you back the most: all content lives in a single SKILL.md file. This violates the Progressive Disclosure Architecture (PDA) principle that Claude skills should use – basically, start users with essentials, then offer references for depth.

Why it matters: A 170-line file is heavier than it needs to be. Users landing on your skill get overloaded, and you lose ~8 points right there.

The fix: Create a references/ directory with separate files:

• references/shell-templates.md – move your template and variations here
• references/common-patterns.md – move best practices (error handling, argument parsing, etc.)
• references/modern-tools.md – move the tool list
• Keep SKILL.md as a ~50-line overview that links to these

This restructure alone gets you to 73/100.

Other Things Worth Fixing

1. Add a table of contents – Files over 100 lines need a TOC at the top with links to each section. Takes 2 minutes, adds clarity.

2. Drop the role-play voice – Change "You are a shell scripting expert" and "Your role is to..." to imperative: "Provide expert shell scripting guidance for Bash and Zsh." More direct, less second-person.

3. Add workflow steps – Instead of just listing best practices, give numbered procedures: "To create a safe script: 1) Start with the template, 2) Add argument parsing, 3) Implement main(), 4) Run shellcheck." Makes it actionable.

4. Expand trigger phrases – You've got 'shell script', 'bash', 'zsh' – add variations like 'bash scripting', 'shell command', 'script debugging' for better discoverability.

Quick Wins

• Restructure into SKILL.md + references/ (biggest impact)
• Add TOC to SKILL.md
• Swap role-play voice for imperative
• Add 3-5 numbered workflows for common tasks
• Include input/output examples for your template

---

Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) 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.