diagram-quality — Claude Code skill: what it does, how to install
diagram-quality enforces PlantUML quality and rendering rules for the agent-uml canvas to avoid HTTP 400 errors and unclickable elements in diagram workflows.
MIT 230 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill diagram-quality -a claude-codeWhat diagram-quality does
The skill guides agent-uml MCP tool calls. It covers design_create, diagram_upsert, design_feedback, and design_export. The rules focus on rendering safety and architectural decomposition.
Rendering safety includes 18 rules to prevent HTTP 400 blank screens. Every element must receive an as Alias — without it, canvas clicks and annotations fail completely. Diagrams also mandate skinparam backgroundColor transparent to match the #f4f1ec canvas.
Heuristics establish clear decomposition thresholds. Component diagrams must split once they exceed 12 elements, while sequence diagrams split at over 10 participants or 20 messages. The skill requires an active agent-uml MCP workflow.
What it helps with
- avoid HTTP 400 errors and blank canvas renders
- ensure diagram elements remain clickable and annotatable via aliases
- split oversized component and sequence diagrams
- match PlantUML skinparam styling to the agent-uml canvas palette
Example prompts for the agent
- Check the sequence diagram syntax before calling diagram_upsert on the agent-uml canvas
- Split the component model if it exceeds the decomposition threshold of 12 elements
- Prepare the PlantUML definition with matching skinparam presets and element aliases for design_create
How to install diagram-quality
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill diagram-quality -a claude-code2Manually: put the files in place
~/.claude/skills/diagram-quality/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/diagram-quality/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill diagram-quality -a codex2Manually: put the files in place
.agents/skills/diagram-quality/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill diagram-quality -a cursor2Manually: put the files in place
.cursor/skills/diagram-quality/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/diagram-quality2Manually: put the files in place
.github/skills/diagram-quality/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill diagram-quality -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/diagram-qualityManually: put the files in place
.devin/skills/diagram-quality/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill diagram-quality -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about diagram-quality
How do I install diagram-quality in Claude Code?
Run npx skills add pproenca/dot-skills --skill diagram-quality -a claude-code. The file will be placed in ~/.claude/skills/diagram-quality/SKILL.md.
What is diagram-quality used for?
It provides 18 rendering safety rules and decomposition heuristics for PlantUML. The skill prevents blank screens and keeps diagram nodes interactive on the agent-uml canvas.
When does the skill trigger diagram decomposition?
Decomposition rules require splitting when a component diagram exceeds 12 elements, a class model has over 15 classes, or a sequence diagram passes 10 participants or 20 messages.
Source text
SKILL.md · MIT
--- name: diagram-quality description: "PlantUML diagram quality on the agent-uml collaborative canvas — three tiers: rendering safety (syntax that prevents HTTP 400 blank canvas), conversation mechanics (when to push a version vs ask a question, what to write in the message parameter), and design effectiveness (decomposition thresholds, cross-diagram traceability, export readiness). Trigger whenever calling agent-uml MCP tools (design_create, diagram_upsert, design_feedback, design_export) — even when the task seems simple, since a missing `as alias` makes elements un-annotatable and a skinparam mismatch makes diagrams unreadable." --- # agent-uml Diagram Quality Best Practices Make the human-Claude design conversation converge faster on the agent-uml canvas. ## When to Apply - Before every `diagram_upsert` call — check syntax safety rules and apply the correct skinparam preset - After every `design_feedback` response — consult the versioning decision table to choose the right next action - When starting a new design session — follow the progressive detail layers for diagram ordering - Before calling `design_export` — run the export-readiness checklist - When a diagram renders blank or elements aren't clickable — consult rendering safety rules ## Rule Categories by Priority | Priority | Section | Impact | Reference | |----------|---------|--------|-----------| | 1 | Rendering Safety | CRITICAL | [syn-safety.md](references/syn-safety.md), [_presets.md](references/_presets.md) | | 2 | Conversation Mechanics | HIGH | [_conversation.md](references/_conversation.md) | | 3 | Design Effectiveness | MEDIUM | [_design.md](references/_design.md) | ## Quick Reference ### 1. Rendering Safety (CRITICAL) 18 rules that prevent blank canvas and ensure interactive SVG. Read [syn-safety.md](references/syn-safety.md) before writing any PlantUML source. Key rules: - **Every element gets `as Alias`** — without it, element is not clickable on canvas - **`skinparam backgroundColor transparent`** — white default clashes with #f4f1ec canvas - **Copy the correct preset from [_presets.md](references/_presets.md)** — one block per diagram type, matched to canvas CSS variables ### 2. Conversation Mechanics (HIGH) 5 decision tables for the feedback-response loop. Read [_conversation.md](references/_conversation.md) when deciding what tool to call next. Key tables: - **Table 4: Signal → Action** — maps annotation, chat, silence, and timeout to the correct tool call - **Table 5: Message content** — what to write in the `message` parameter (explain change + ask focusing question) ### 3. Design Effectiveness (MEDIUM) 4 heuristics with concrete thresholds. Read [_design.md](references/_design.md) when planning diagram sequences or preparing for export. Key heuristics: - **Progressive detail layers** — L1 context → L2 container → L3 class → L4 behavior → L5 state - **Cross-reference traceability** — every sequence participant must map to a component; every interface belongs to exactly one component boundary - **Decomposition thresholds** — component >12, class >15, sequence >10 participants or >20 messages → split ## How to Use 1. **Starting a session:** Read [_conversation.md](references/_conversation.md) Table 3 (diagram type scope) to decide which diagram to create first 2. **Writing PlantUML:** Apply the skinparam preset from [_presets.md](references/_presets.md), then check [syn-safety.md](references/syn-safety.md) for the rules relevant to your diagram type 3. **After feedback:** Consult [_conversation.md](references/_conversation.md) Table 4 (signal → action) to decide whether to push a new version or reply with a question 4. **Before export:** Run the checklist in [_design.md](references/_design.md) Heuristic 4 ## Reference Files | File | Description | |------|-------------| | [references/_sections.md](references/_sections.md) | Section definitions and ordering | | [references/syn-safety.md](references/syn-safety.md) | 18 rendering safety rules (Incorrect/Correct) | | [references/_presets.md](references/_presets.md) | 5 copy-paste skinparam presets per diagram type | | [references/_conversation.md](references/_conversation.md) | 5 decision tables for conversation loop | | [references/_design.md](references/_design.md) | 4 heuristics with thresholds | | [assets/templates/_template.md](assets/templates/_template.md) | Template for adding new rules | | [metadata.json](metadata.json) | Version and reference information |
© pproenca · MIT · pproenca/dot-skills