spec-updater

I took a look at your spec-updater skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 76/100, solidly in C territory — which means you've got good fundamentals but there's meaningful room to climb. Based on Anthropic's skill best practices, your Writing Style is flawless (10/10), but Progressive Disclosure Architecture is dragging you down (14/30). The skill does real work, though — it solves an actual problem in spec-driven workflows.

What's Working Well

• Writing is crisp. Imperative voice, no fluff, high information density. You're not wasting words, which is exactly what you want in a skill.
• Solid examples. Your JSON input/output samples and spec format templates give people concrete patterns to follow. That's the kind of thing that separates "readable" from "actually useful."
• Clear workflow steps. The numbered procedures are straightforward — no ambiguity about what the skill does or how to trigger it.
• Strong utility. This solves a real need. Tracking spec progress in development workflows is genuinely useful, and your error handling and validation logic is comprehensive.

The Big One: Layered Structure Is Missing

Here's what's holding you back most: you've crammed 400+ lines into a single SKILL.md file. No references directory, no external docs, no layered architecture. This kills your Progressive Disclosure score (only 3/10 on layered structure, 0/5 on reference depth).

This matters because skills need to be scannable — developers should get the essential info immediately, then dig deeper if they need to. Right now, someone reading your skill has to scroll through everything.

Fix: Create a references/ directory structure:

• references/workflows.md — Move the detailed workflow descriptions here
• references/examples.md — Detailed JSON examples and spec templates
• references/api-reference.md — Full parameter documentation
• Keep only the essentials in SKILL.md itself (quick description, basic workflow, one example)

This alone could bump you +7 points to around 83/100.

Other Things Worth Fixing

1. Add a table of contents to SKILL.md. With 400+ lines, people need navigation signals. Just a simple markdown TOC at the top linking to sections would give you +2 points.

2. Trigger phrases are vague. Your description says "marks phases complete, checks off tasks..." but doesn't have crisp trigger phrases. Add explicit ones like: Use when asked to "update spec status", "mark phase complete", "check off tasks", or "add implementation notes". This helps discoverability (+1 point).

3. Frontmatter has minor formatting issues. Nothing breaking, but tightening up the YAML structure (spacing, field order) gets you closer to the 5/5 spec compliance mark.

Quick Wins

• Build that references/ directory — biggest bang for your buck (+7 points)
• Add a TOC — quick structural win (+2 points)
• Crisp up trigger phrases — helps people find this skill (+1 point)
• Tighten frontmatter formatting — polish the foundation (+1 point)

Total realistic improvement: +11 points → ~87/100 (B grade). The skill already works; it just needs better information architecture.

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.