Feedback on your clear skill

[RichardHightower]

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

Links:

• GitHub
• Your skill in the SkillzWave marketplace

The TL;DR

You're at 61/100, landing in D territory. Based on Anthropic's best practices, your skill is solid on workflow clarity (Ease of Use: 20/25) but has a critical blocker with Spec Compliance at 0/15. The good news? This is fixable with a few focused changes.

What's Working Well

• Clear numbered workflow - Your Step 1 through 4 progression is easy to follow, and the destructive operation confirmation pattern is thoughtful
• Copy-paste ready commands - The bash commands are concrete and immediately actionable
• Consistent terminology - You're consistent with 'target' and path references throughout, which helps users follow along

The Big One: Your Frontmatter Is Broken

This is why you're at 0/15 on Spec Compliance. Your YAML frontmatter has invalid syntax:

---
name: clear
description: Clear saved SourceAtlas analysis results
model: haiku
allowed-tools: Bash, Read
argument-hint: (optional) [target: overview|patterns|flows|history|impact|deps]
---

The issue? The allowed-tools and argument-hint fields are non-standard. Based on Anthropic's skill spec, frontmatter should only have name and description. Here's the fix:

---
name: clear
description: Clear cached analysis results from .sourceatlas/ directory. Use when asked to "clear analysis", "remove cached files", or "reset SourceAtlas data".
---

Why this matters: Invalid frontmatter breaks skill parsers across multiple platforms. This single fix gets you +5 points immediately, and the better description triggers discoverability (+2 more).

Other Things Worth Fixing

1. Vague description loses context - "Clear saved SourceAtlas analysis results" doesn't tell users which analysis types can be cleared. Mentioning the specific types (overview, patterns, flows, etc.) helps both discoverability and clarity.

2. No error handling guidance - Your Step 4 just runs rm -rf .sourceatlas/* with no guidance if permission denied or partial failures occur. Add a line about checking file permissions or running with elevated access if needed.

3. Example output feels redundant - Lines 44-51 duplicate what's already clear from the instructions. Either remove it or make it more minimal (just show the date format expected).

4. Watch the voice - One spot says "Help user clear saved analysis results" which is a bit second-person. Keep it imperative: "Clear saved analysis results from .sourceatlas/ directory."

Quick Wins

• Fix frontmatter syntax (removes parsing errors, +5 points)
• Improve description with trigger phrases ("+2 points, better discoverability)
• Remove or tighten example output section (streamlines PDA, +1 point)
• Add error handling note to Step 4 (+2 points on utility)

These four changes alone would push you toward 73/100 territory.

---

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