Feedback on your overview skill

[RichardHightower]

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

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 85/100, solid B-grade territory. This is based on Anthropic's best practices for agentic skills. Your strongest area is utility (18/20) — the skill genuinely solves a real problem (understanding large codebases fast using information theory). Weakest spot is spec compliance (11/15), mostly around missing trigger phrases in the description.

What's Working Well

• Utility is excellent. You're addressing a real pain point: scanning <5% of files to get 70-80% understanding. That's genuinely valuable, and the fingerprinting approach with entropy calculations shows thoughtful problem-solving.

• Progressive Disclosure Architecture is solid. Your 5-file structure is clean — SKILL.md delegates to workflow.md, reference.md, output-template.md, and verification-guide.md. That's exactly how you should organize complexity. The reference depth is perfect: one level out from SKILL.md with clear anchors.

• Verification loops are comprehensive. The V1-V4 verification checklist in workflow.md gives users clear feedback loops and self-correction patterns. That's what separates good skills from great ones.

• Triggers are clear and specific. 'project overview', 'fingerprint', 'scan <5%' — these activate when they should. Good discoverability for when developers need this.

The Big One: Missing Trigger Phrases

Your description is missing the actual trigger phrases that tell users when to invoke this skill. Right now it reads:

Get project overview - scan <5% of files to achieve 70-80% understanding

But it needs to follow the spec with actual usage triggers:

Performs overview operations. Use when asked to "overview", "run overview", or "overview help".

This matters because without triggers, users won't know when to ask for this skill. It's a +2 point bump once you add it. Quick fix in SKILL.md frontmatter.

Other Things Worth Fixing

1. Add a Table of Contents to SKILL.md. At 320 lines, it needs navigation signposts. Add a TOC after the frontmatter listing the major sections (Cache Check, Core Workflow, Output Format, etc.). +2 points, takes 5 minutes.

2. Remove the duplicate "Output Header" section. Lines 309-319 repeat the format from lines 159-178. Just delete the one at the end and reference the earlier section. Cleans up token economy. +1 point.

3. Kill the AI tool detection table duplication. Same table appears identically in workflow.md (243-258) and reference.md (169-182). Keep it only in reference.md and link from workflow.md. +1 point, better maintainability.

4. Tighten the voice. Section titled "Your Task" uses second-person when it should be imperative like the rest. Change to just "Task" and start with "Execute Stage 0 Analysis Only". +1 point, improves consistency.

Quick Wins

• Add trigger phrases to description → +2
• Add TOC to SKILL.md → +2
• Remove duplicate Output Header → +1
• Consolidate AI tool tables → +1
• Fix second-person voice → +1

That's 7 potential points for about 30 minutes of work. You'd land at 92/100 and A-grade territory.

---

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.