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/workf...