"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...