plantuml

I took a look at your plantuml skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 88/100, solid B grade territory. This is based on Anthropic's skill best practices rubric. Your strongest area is Ease of Use (23/25) — the trigger phrases and metadata are really well thought out. The weakest spot is Spec Compliance (13/15), which is mostly a formality issue, not a functionality problem.

What's Working Well

• Five crystal-clear trigger phrases in your metadata ("create diagram", "generate PlantUML", "convert puml", "extract diagrams", "prepare markdown for Confluence") — this is chef's kiss for discoverability. Most skills are vague here; yours tells users exactly when to call it.

• Progressive disclosure architecture is solid. SKILL.md stays lean as an index, and you've got 39 reference files organized logically under references/, troubleshooting/, and workflows/. Users can dive deep without drowning in the overview.

• Practical utility across three major workflows: text-to-diagram, code-to-diagram, and markdown processing. You're solving real problems developers actually face, especially the Confluence conversion angle.

The Big One: Redundant References Section

Your SKILL.md has a References section (lines 284-309) that duplicates navigation you already provided earlier. You list the same 19 diagram types both in your intent-to-diagram table AND again in the References section. This costs you about 2 points in Progressive Disclosure (Token Economy pillar).

The fix: Delete the redundant References section entirely. Your earlier "Get Started" section with the intent-to-diagram table already does the heavy lifting. If you want a references footer, make it a single compact link to references/toc.md instead of repeating everything.

Why it matters: Token efficiency is about respecting the reader's cognitive load. Repetition makes the skill feel bloated when it's actually well-organized underneath.

Other Things Worth Fixing

1. Second-person voice creeping in: Phrases like "Identify the appropriate diagram type based on user intent" should be "Identify appropriate diagram type based on intent." Removes unnecessary words and keeps the imperative tone consistent. Affects 1-2 points in Writing Style.

2. Large reference files missing TOCs: Files like sequence_diagrams.md (541 lines) and class_diagrams.md are deep dives with no table of contents. Add a quick TOC after the opening description for files over 100 lines so users can navigate without scrolling blind.

3. XML tags in metadata (penalizing you -5 points): Your SKILL.md frontmatter appears clean, but make sure you're not accidentally including XML-style tags in description or other fields. The grading report flagged this, so double-check your YAML.

Quick Wins

• Remove the redundant References section → +2 points immediately
• Add TOCs to large reference files (sequence_diagrams, class_diagrams, etc.) → +1 point
• Tighten voice from second to imperative (cut "user intent" → "intent") → +1 point
• Fix any XML tag issues in metadata → +5 points

These changes would push you from 88 to 95+ — into solid A territory.

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.