MicrosoftKnown publishermicrosoft/devsquad-copilot/.github/plugins/devsquad/skills/diagram-design/SKILL.mddiagram-design
Skill50 starsChanged 16 days agoMITView on GitHub
Design and review guidance for software architecture diagrams (Mermaid, Draw.io). Use when creating, reviewing, or editing diagrams in any markdown documentation. Triggered by: diagram, flowchart, sequence diagram, mermaid, drawio, architecture diagram, data flow, state machine, ER diagram, class diagram, C4 model, system context, high-level overview. Covers readability, accessibility, notation, abstraction levels, tool selection (mermaid vs drawio), and platform-specific rendering rules (GitHub vs Azure DevOps). Do not use for markdown text formatting rules (use documentation-style) or for code visualization/debugging.
We split this skill into the rules it gives an agent
7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 40 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Keep it simple: When a diagram feels cluttered, split it.
- Distinctive: line 31
Diagrams complement text: Add a short paragraph for context the visual cannot convey (why, constraints, what is not shown).
- Distinctive: line 39
Labeled relationships: every arrow has a verb phrase ("sends events to", "reads from")
- Distinctive: line 42
No orphan elements: every element has at least one relationship
- Distinctive: line 61
Start with Mermaid. Switch to Draw.io when the diagram needs spatial freedom, icons, or more than ~15 elements.
- Very specific: line 65
Line breaks: use <br/> inside labels and node text.
- Very specific: line 78
Use LR (left-to-right) for flows and pipelines.
“Common” is measured: kept by at least 6 in 10 of the 40 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Diagram Design
Principles
A diagram exists to help someone understand something. Before creating one, ask: who is the audience and what question does this diagram answer?
- Business stakeholders need system context: what the system does, who uses it, what it connects to. Omit internals and technology.
- Developers need technical clarity: components, data flows, technology choices.
- A diagram that tries to serve both audiences usually serves neither.
Zoom, don't cram. Each diagram should answer one question at one level of abstraction. Use separate diagrams for context, containers, components, and code, like zooming into a map.
Keep it simple. When a diagram feels cluttered, split it. Avoid crossing arrows, limit to ~15 elements, and prefer clarity over completeness.
Every element must be meaningful. Each box needs a name and a responsibility (one sentence). Add technology labels only for technical audiences. If you cannot describe what an element does, remove it.
Diagrams complement text. Add a short paragraph for context the visual cannot convey (why, constraints, what is not shown). Do not repeat in text what the diagram already shows.
Review Checklist
Apply before considering a diagram done:
- Title: describes what the diagram shows, not a generic label
- Legend: present if the diagram uses colors, shapes, line styles, or icons
- Labeled relationships: every arrow has a verb phrase ("sends events to", "reads from")
- Consistent arrow direction: one convention (data flow or dependency), stated explicitly
- Boundaries: elements that share a deployment unit or logical grouping are visually grouped
- No orphan elements: every element has at least one relationship
Visual Design
Shapes help distinguish element types at a glance (rectangle for services, cylinder for data stores, person for actors, cloud for external systems). Pick a consistent mapping and apply it throughout the project.
Colors add information but should not be the only differentiator (~8% of males have color vision deficiency). Pair color with shape, pattern, or label so diagrams remain readable in grayscale. Limit to 4-5 colors, avoid red/green as sole distinguishing pair, and document the mapping in the legend.
Icons (Draw.io) add recognition but must complement text labels, not replace them. Use official service icon sets and do not mix providers. Read references/drawio-guide.md for creation and export workflow.
Tool Selection: Mermaid vs Draw.io
| Factor | Mermaid | Draw.io |
| Complexity | Simple to medium (< 15 elements) | Medium to complex, or spatial layout matters |
| Icons | No native support | Rich icon libraries (cloud providers, UML) |
| Version control | Text-based diff in markdown | Binary .drawio (XML, harder to review) |
| Rendering | Inline in GitHub/Azure DevOps | Exported as .drawio.png, referenced as image |
Start with Mermaid. Switch to Draw.io when the diagram needs spatial freedom, icons, or more than ~15 elements.
Mermaid Syntax Notes
- Line breaks: use
<br/>inside labels and node text. Mermaid does not interpret\nas a line break; it renders as literal text.
Mermaid Diagram Types
| What you want to show | Mermaid type |
| System context, containers, components | C4Context, C4Container, C4Component |
| Request/response flow between services | sequenceDiagram |
| Process or data flow | flowchart LR or flowchart TD |
| State transitions | stateDiagram-v2 |
| Entity relationships | erDiagram |
| Class structure | classDiagram |
Use LR (left-to-right) for flows and pipelines; TD (top-down) for hierarchies.
Mermaid Platform Rendering
Detect from the git remote (git config --get remote.origin.url):
- GitHub (
github.com): use code block with```mermaidand``` - Azure DevOps (
dev.azure.comorvisualstudio.com): use:::mermaidand:::
Convert existing Mermaid blocks to the correct platform format when editing markdown files.
Other versions43 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 43
- cathrynlavery/diagram-design★ 64ksame name
- kdlbs/kandev★ 1ksame name
- chenjackle45/html-visualizer★ 95same name
- baekenough/oh-my-customcode★ 42same name
- tsukhani/jclaw★ 41same name
- spmtitsolution/OpenBA-Kit★ 38same name
- Fioooooooo/FylloCode★ 29same name
- ivanrvpereira/.agents★ 19same name
- delorenj/skills★ 18same name
- JuankCadavid/akili-specs★ 9same name
33 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use i-have-adhd, show-me and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
PydanticSkilli-have-adhd
Shape every response for an ADHD reader who reviews the work but does not do the coding — the agent does. Use whenever responding to ANY message — coding, debugging, planning, casual. Lead with the result or the decision. Surface anything needing the user's input as a structured question, never buried in prose they'll skim past. No preamble, no recap, no closers. State errors matter-of-factly. Make finished work visible. Trigger even on casual messages and even when brevity wasn't requested.
Also in 4 projects that use this
AnasX7Skillshow-me
Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
Also in 4 projects that use this
- AnasX7Skill
minimalist-ui
Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
Also in 4 projects that use this
GoogleSkillponytail
Forces the laziest solution that actually works, simplest, shortest, most minimal. Channels a senior dev who has seen everything: question whether the task needs to exist at all (YAGNI), reach for the standard library before custom code, native platform features before dependencies, one line before fifty. Supports intensity levels: lite, full (default), ultra. Use on ANY coding task: writing, adding, refactoring, fixing, reviewing, or designing code, and choosing libraries or dependencies. Also use whenever the user says "ponytail", "be lazy", "lazy mode", "simplest solution", "minimal solution", "yagni", "do less", or "shortest path", or complains about over-engineering, bloat, boilerplate, or unnecessary dependencies. Do NOT use for non-coding requests (general knowledge, prose, translation, summaries, recipes).
Also in 4 projects that use this
OpenAISkillimage-to-code
Implement a selected image, screenshot, mockup, or Image Gen reference as a faithful, responsive frontend.
Also in 3 projects that use this
- GoogleSkill
to-tickets
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in one file per ticket locally, or native blocking links on a real tracker.
Also in 4 projects that use this
- +3 more from AnasX7
- +2 more from google
In this repository26 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- .github/plugins/devsquad/hooks/templates/.github/copilot-instructions.mdCopilot instructions
- adr-workflowSkill
- board-configSkill
- complexity-analysisSkill
- debugging-recoverySkill
- deep-clarificationSkill
- documentation-styleSkill
- domain-glossarySkill
- engineering-practicesSkill
- git-branchSkill
- git-commitSkill
- harness-learningsSkill
- init-configSkill
- init-docsSkill
- init-scaffoldSkill
- lsp-setupSkill
- next-taskSkill
- pull-requestSkill
- quality-gateSkill
- reasoningSkill
- security-reviewSkill
- test-disciplineSkill
- triage-workflowSkill
- work-item-creationSkill
- work-item-workflowSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.