design-doc-mermaid

I took a look at your design-doc-mermaid skill and wanted to share some thoughts.

Links:

• GitHub
• SkillzWave Marketplace

The TL;DR

You're at 87/100, solid B territory. This is based on Anthropic's best practices for agent skills. Your strongest area is Ease of Use (23/25) – the trigger phrases, decision tree, and "When to Use What" table are chef's kiss. Weakest is Progressive Disclosure Architecture (26/30) – mainly because you're carrying too much weight in SKILL.md itself.

What's Working Well

• Trigger phrases are dialed in – "create a diagram", "generate mermaid", "code to diagram" – developers will find this skill easily
• Hierarchical structure is clean – References are organized by diagram type (deployment, architecture, sequence, activity) with clear paths and no guessing
• Comprehensive troubleshooting guide – 28 documented errors with fixes shows you thought through real problems developers hit
• Framework examples pay dividends – Spring Boot, microservices, K8s patterns give people immediate wins without hunting for templates

The Big One

Inline examples are killing your token efficiency. You've got three complete, styled Mermaid diagrams embedded directly in SKILL.md (Infrastructure, Activity Flow, Microservices sections). Every time someone invokes this skill, they're loading those diagrams even if they don't need them.

The fix: Move the detailed styled examples to references/guides/unicode-symbols/guide.md where they belong, and keep just one minimal example in SKILL.md to show the concept. This single change gets you +2 points and makes the skill snappier for real-world use.

Other Things Worth Fixing

1. Resilient workflow is explained twice – The full workflow appears in both the Resilient Workflow section AND Pattern 6. Pick one location, reference it cleanly. This redundancy adds ~10 lines of noise. +1 point.

2. File organization tree is redundant – Your guide reference tables already map the structure. The 40+ line directory tree duplicates this info visually. Keep the tree OR the tables, not both. +1 point.

3. A few second-person constructions – Phrases like "validate your work" and "your specific request" pop up occasionally. Rephrase to imperative: "validate the work", "the specific request". Keeps it crisp. +1 point.

Quick Wins

• Move 3 inline diagrams → separate reference file (fixes PDA, +2 points)
• Deduplicate workflow explanation → single source of truth (fixes Writing Style, +1 point)
• Consolidate structure documentation → either tables or tree, not both (+1 point)
• Trim second-person language → purely imperative voice (+1 point)

These four changes are low-effort, high-impact. You're looking at 87 → 92, easy A-range territory.

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.