documentation-specialist

I took a look at your documentation-specialist skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 94/100, solid A territory. This is based on Anthropic's PDA framework and best practices for agentic skills. Your strongest area is Spec Compliance (14/15) – you nailed the frontmatter and conventions. Weakest is Utility (18/20) – a few edge cases and some broken example references holding you back from a perfect score.

What's Working Well

• Progressive Disclosure Architecture is chef's kiss – Your 3-tier structure (SKILL.md → workflows → templates/references) is textbook PDA. The routing hub at 139 lines keeps token load lean, and everything loads on-demand exactly as intended.

• Trigger phrases are comprehensive – You've got 5+ distinct intents covered ("create documentation", "document my code", "write SRS", "generate PRD", "documentation specialist"). Users will find this skill easily.

• Examples and templates are real – 380+ lines in billing-srs.md with actual Gherkin acceptance criteria, runbooks with step-by-step instructions, getting-started guides. This isn't template-ware – it's production-ready documentation people can actually use.

The Big One: Broken Example References

Your examples/TOC.md references files that don't exist in the actual structure – specifically greenfield/ecommerce-sdd.md and brownfield subdirectories that aren't there. When users try to navigate to these, they'll hit dead ends.

Why it matters: Breaks discoverability and makes the skill feel incomplete. Users exploring examples won't find what they're looking for.

The fix: Audit references/examples/TOC.md and either create the missing files (if intentional) or remove the references. Since you've got solid examples already (billing-srs.md, database-failover-runbook.md, etc.), I'd suggest removing orphaned references and keeping your TOC tight to what actually exists.

Impact: +1-2 points.

Other Things Worth Fixing

1. Add a quick TOC to SKILL.md – At 139 lines, you're approaching the threshold where one helps. Just a brief 5-6 item TOC after "Quick Start" would let users jump to "Intent Classification" or "Template Selection" without scrolling. Low effort, +1 point.

2. TOC files have some redundancy – Your comprehensive-guide.md and workflows/TOC.md list similar info in both tables and prose. Consolidate to either table-format or prose, not both. Saves tokens and keeps navigation cleaner.

3. Description formatting could be cleaner – Your YAML description spans multiple lines in a way that's technically valid but a bit awkward. Single-line descriptions with trigger terms packed tighter read better and parse more consistently.

Quick Wins

• Remove broken references in examples/TOC.md – Most impactful fix. Takes 5 minutes, +1-2 points.
• Add brief TOC to SKILL.md – Easy win for organization, +1 point.
• Tighten TOC redundancy – Saves tokens and improves clarity, +0.5 points.

Your skill is already strong – these are just polish moves to get from 94 to 97+.

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.