mermaid-diagrams

I've been diving into diagram-as-code approaches lately, and I'm curious how your mermaid implementation handles the balance between flexibility and accessibility—81/100 suggests you're doing something really well, but I'm wondering what tradeoffs you made to get there.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 81/100, solid B-grade territory. This is based on Anthropic's five-pillar evaluation framework. Your writing style is genuinely strong (9/10)—clear, technical, no fluff. But you're losing points on discoverability and navigation, which is interesting because the content itself is really useful.

What's Working Well

• Writing quality is legit. Imperative tone, technical depth, no marketing nonsense. That 9/10 is earned.
• Your AST-to-Mermaid function is a solid reference implementation. Gives Claude actual working code to build from, not just theory.
• Good reference file structure. Splitting syntax and theming out of the main SKILL.md keeps token bloat down while staying accessible.
• Multiple diagram types covered. Flowcharts, sequence, state, class—you're not limiting Claude's options, which is exactly what utility should look like.

The Big One: Description Triggers Are Too Vague

Here's what's holding back your discoverability score. Your description says:

"Use when creating Mermaid diagrams - covers flowcharts, sequence diagrams, and AST visualization"

The problem? Claude doesn't activate skills on vague descriptions. It needs specific action triggers. When should Claude actually use this? When someone says "create a diagram"? "Visualize my code structure"? "Generate a flowchart"?

Fix: Rewrite your description to include actual trigger phrases:

description: Create Mermaid diagrams (flowcharts, sequ...