Feedback on your list skill

[RichardHightower]

I took a look at your list skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 74/100, solid C grade territory. This is based on Anthropic's best practices for skill design. Your Progressive Disclosure Architecture is the strongest pillar (22/30) — the skill's structure and token economy are well thought out. The weakest area is Spec Compliance (10/15), mainly because the description is missing trigger phrases that would help users discover and invoke the skill.

What's Working Well

• Clean command structure — The numbered steps with bash commands are straightforward and easy to follow. Users know exactly what to do.
• Good error handling — You're handling edge cases like empty directories and expired items, with actionable next steps (e.g., "run list refresh").
• Consistent terminology — "saved analyses," "cached," "expired" are used consistently throughout, so there's no confusion about what the skill does.
• Grep-friendly output — The format lends itself well to piping and parsing, which is a nice practical touch (+1 bonus point).

The Big One: Description Needs Trigger Phrases

Your description — "List saved SourceAtlas analysis results" — is too generic. When someone searches the marketplace or asks an agent "list my cached analyses," they won't find this skill because those keywords aren't in the metadata.

Current:

description: List saved SourceAtlas analysis results

Better:

description: List cached SourceAtlas analyses - show saved results, cache status, expired items, and storage usage in .sourceatlas/ directory

This adds searchable terms like "cached," "show results," "cache status," and "expired" that match how users actually think about the problem. This alone could bump you +2-3 points on Spec Compliance and Ease of Use.

Other Things Worth Fixing

1. Verbose example tables — Your 7-row example in Step 3 shows the pattern clearly with 2-3 rows. Trimming this saves tokens and keeps people engaged (+1 point on Writing Style).

2. "Your Task" heading — Minor, but heading with second person ("Your Task") is less imperative than just "Task" or "Overview." Tiny shift, big consistency win (+0.5 points).

3. No table of contents — At ~100 lines, a quick TOC would help users jump to what they need without scrolling (+1 point on Navigation Signals).

Quick Wins

• Add trigger phrases to the description → +2-3 points
• Trim example tables from 7 rows to 3 → +1 point
• Add a simple TOC at the top → +1 point
• Fix "Your Task" to imperative form → +0.5 points

Hit these, and you're looking at 79-81/100 — solid B grade range.

---

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.