"documentation-specialist"

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

Links:

• GitHub
• SkillzWave Marketplace

TL;DR

You're at 94/100, solidly in A territory. This is a well-architected skill with excellent PDA implementation and comprehensive coverage. Your strongest area is Spec Compliance (14/15) – the YAML frontmatter is clean, naming conventions are correct, and your trigger phrases are well-chosen. Weakest link is Utility (18/20) – mostly because some promised examples aren't actually there yet.

What's Working Well

• Progressive Disclosure Architecture is chef's kiss. Your 3-tier structure (SKILL.md → 8 workflows → sub-guides) with explicit token budgets (~350 tokens per workflow) is the kind of thing other skills should copy. The 65+ files are organized by function, not chaos.

• Intent classification is solid. Your description covers 5 distinct capabilities with 8 trigger phrases ("greenfield docs", "brownfield extraction", "audit", "convert", "diagrams"). Users will actually find this skill when they need it.

• Reference architecture stays shallow. Everything is one level from SKILL.md – no deep nesting traps. The TOC.md files with token budgets show you're thinking about developer experience.

• You've got examples. 8 real-world examples (billing SRS, pet clinic runbook, etc.) plus 9 templates. That's the kind of concrete stuff that makes a skill actually usable.

The Big One: Missing Brownfield Examples

Your references/examples/TOC.md promises brownfield examples that don't exist yet:

• spring-boot-petclinic/ (referenced but not present)
• fastapi-todo-app/ (referenced but not present)
• etc.

Why this matters: Brownfield workflows are your differentiator – they show how to extract docs from real code. Without working examples, developers won't trust the workflow.

The fix: Either create the referenced directories with actual example projects and their generated docs, OR update TOC.md to remove the promises and stick with what you have. I'd go with option 1 – add at least one complete Spring Boot example showing the before/after (original code → generated SDD + OpenAPI).

Impact: +1-2 points to Utility.

Other Things Worth Fixing

1. Workflow files need internal TOCs. Several of your workflow guides (greenfield-workflow.md, brownfield-workflow.md) hit 100+ lines but lack a table of contents. Add ## Table of Contents with anchor links at the top of any workflow >100 lines. Low effort, helps navigation. +1 point.

2. Some template sections are verbose. Your example sections in templates include explanatory prose that could be trimmed. Templates should be scannable – move detailed explanations to the guides, keep templates minimal. Small win, keeps token budgets tight.

3. CRITICAL note placement. You mention "CRITICAL: Always provide...") in one reference file – make sure any critical constraints appear in the main workflow docs, not buried in references. Users won't see it otherwise.

Quick Wins

• Create 1 complete brownfield example (Spring Boot recommended) showing extracted docs
• Add internal TOCs to workflow files >100 lines
• Verify all reference links in TOC.md actually exist in the repo
• Move critical constraints from references into main workflows

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.