Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill diagram-quality -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/diagram-quality/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/diagram-quality/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →
diagram-architect davila7 diagram-architect is a Claude Code subagent that creates technical diagrams in ASCII, Mermaid, PlantUML, and Draw.io. It activates for architecture views, database schemas, process flows, and dependency maps. CX Codex 1,178installs markdown-viewer-skills podo markdown-viewer-skills — a router skill for diagrams written as Markdown text: PlantUML for UML and networks, Vega-Lite and ECharts for charts, HTML/CSS for infographics and cards. Useful when docs need figures. CX Codex +1 202installs plantuml-skill Agents365-ai plantuml-skill — a coding-agent skill that writes .puml files and exports them to PNG or SVG. Useful when you need a diagram from code or from a text description. CX Codex +1 4,200installs diagram-generator zhaoxuya520 diagram-generator is a Claude Code skill that generates, checks, and renders diagrams from text, code, schemas, and tables for architecture, process, and UML modeling. CX Codex +1 1,500installs plantuml-diagram-generator Jeremy Longshore plantuml-diagram-generator automates creating PlantUML diagrams and visual documentation. It triggers automatically whenever you mention PlantUML or diagram generation in your prompt. CX Codex +1 123installs uml-and-software-architecture-visualization official OpenAI The uml-and-software-architecture-visualization skill helps choose a notation and format for UML diagrams, architecture maps, workflows, and data models. Use it when you need to describe how a system is structured or behaves. CX Codex GP ChatGPT +1 24installs

From the same set139

The whole set →
clean-code-ts-react clean-code-ts-react adapts Robert C. Martin's Clean Code principles for TypeScript 5.x and React 19. Guides code reviews, component architecture, and refactoring sessions. CX Codex +1 238installs cli-for-agents cli-for-agents is a Claude Code skill for designing and reviewing CLIs used by AI agents and automation. It applies to work on subcommands, flags, help text, and error messages. CX Codex +1 237installs eval-mcp eval-mcp measures MCP tool schema quality and Claude's tool selection accuracy. Detects confusing descriptions and runs intent benchmarks. CX Codex +1 234installs threat-patch threat-patch turns scanner findings or a threat model into small code patches, each with a short write-up and test steps. CX Codex +1 232installs drizzle-sqlite drizzle-sqlite — a Drizzle ORM skill for SQLite schema design, migrations, queries, transactions, and types. Use it when writing or reviewing SQLite-backed code. CX Codex +1 221installs cli-review-runner The cli-review-runner skill for Claude Code checks a CLI command against 45 rules from the cli-for-agents catalog to assess whether an agent can use it safely in a pipeline. CX Codex +1 219installs openai-codex-rust-patterns openai-codex-rust-patterns applies 63 production Rust patterns distilled from the OpenAI Codex codebase. Helps build resilient async workflows, process sandboxes, and panic-free error architectures. CX Codex +1 219installs marketplace-search-recsys-planning marketplace-search-recsys-planning is a skill for planning and diagnosing marketplace search and recommendations on OpenSearch, from index design to quality measurement. CX Codex +1 211installs

Project sponsors

Companies that keep this analytics open