Table of contents
uml-skill: Instructions with a small encoding fallback
uml-skill packages diagram-writing instructions and a small Python helper. It is a skill bundle, not an MCP server or an image-generation model. The helper can produce a Kroki URL from diagram source.
- Languages
- 1Code breakdown
- Documented components
- 2Explore modules
- Source documents
- 2Read the instructions
Repository languagesPython 100%1
Shares calculated from GitHub Linguist bytes.
| Language | % | Bytes |
|---|---|---|
| Python | 2,870 |
1. Overview
1.1. Why it exists
Agent skill bundle providing direct tool definitions and prompt guides for diagram generation.
1.2. Best fit
Drop-in diagram generation capabilities for LLM agent frameworks.
2. Use cases
Agent skill (diagramming-uml) that guides AI coding agents to write diagram source and render it via uml-mcp or Kroki.
- Install the skill
- DeveloperAI coding agent
The README lists npx @smithery/cli@latest skill add antoinebou12/uml, or copying the folder into .cursor/skills/diagramming-uml/ so the agent loads SKILL.md.
- Plan and write diagram code
- AI coding agent
SKILL.md walks the agent through purpose, diagram type, outline and readability rules (about 25 Mermaid or 30 PlantUML nodes, labelled transitions) before it writes source.
- Pick a diagram_type
- AI coding agent
references/DIAGRAM-TYPES.md maps intents such as sequence, swimlane, ER or architecture to a Kroki diagram_type and Mermaid or PlantUML form, to be confirmed with uml://types.
- Render through uml-mcp
- AI coding agentuml-mcp / Kroki
When uml-mcp is connected, the skill tells the agent to call validate_uml then generate_uml or generate_uml_batch and to return the Kroki url and playground link.
- Build a Kroki URL offline
- Developeruml-mcp / Kroki
Without MCP, scripts/kroki_url.py compresses the source with zlib, encodes it in base64url and prints a https://kroki.io/<backend>/<format>/... URL.
2.1. Scenario: Get a shareable sequence diagram link
- Install the skill with npx @smithery/cli@latest skill add antoinebou12/uml.
- Ask the agent for a sequence diagram of a checkout flow; the skill activates on the diagram request.
- The agent picks sequence or Mermaid sequenceDiagram from the intent table and writes the source.
- With uml-mcp connected, it calls validate_uml and generate_uml and replies with the url, the playground link and a copy of the code.
- Without uml-mcp, run python scripts/kroki_url.py -t mermaid diagram.mmd to get the link.
Files readREADME.mdSKILL.mdAGENTS.mdreferences/DIAGRAM-TYPES.mdscripts/README.mdscripts/kroki_url.py
3. Getting started
These commands come from the repository documentation. They were not run during this review.
python kroki_url.py --helppython kroki_url.py -t mermaid diagram.mmd
python kroki_url.py -t plantuml -f png diagram.pumlGet-Content diagram.puml -Raw | python kroki_url.py -t plantumlcat diagram.puml | python kroki_url.py -t plantuml4. Repository references
Excerpts from the repository’s guides, in their original language. Links open the inspected source revision.
Prerequisites and first run
4.1. Install
README.md
| Route | What to do |
|---|---|
| Smithery (recommended for many agents) | Run npx @smithery/cli@latest skill add antoinebou12/uml. Open the Smithery skill page and use Install for client-specific steps (Cursor, Claude Code, Codex, Windsurf, Continue, GitHub Copilot, and others). |
| Cursor (manual) | Copy this repository (or the uml-skill folder) into .cursor/skills/diagramming-uml/ (or add a symlink). See Cursor · Rules & skills. |
| Other clients | Prefer the Smithery CLI and your product’s skill directory; paths and filenames vary. |
Configuration and usage
4.2. Usage
scripts/README.md
5. Features and components 2
- Instruction layer
- SKILL.md describes the workflow and points to diagram references. An agent can use those instructions with available diagram tools. References supply syntax guidance without becoming an application runtime.
- Encoding helper
- scripts/kroki_url.py uses standard-library compression and encoding to construct a rendering URL. Generating that URL and requesting the rendered image are separate operations.
6. Architecture
Expand a component to follow its connections, or explore the full diagram.
Diagram request
Skill and syntax references
- From Diagram request
- To Diagram source
Diagram source
Kroki URL helper
- From Diagram source
- To Rendering endpoint
Rendering endpoint
- From Kroki URL helper
Mermaid Interactive diagram
System overview of the components and connections verified in the repository.
flowchart LR
n0["Diagram request"]
n1["Skill and syntax references"]
n2["Diagram source"]
n3["Kroki URL helper"]
n4["Rendering endpoint"]
n0 --> n1
n1 --> n2
n2 --> n3
n3 --> n4
Text version of the diagram
- Diagram request → Skill and syntax references
- Skill and syntax references → Diagram source
- Diagram source → Kroki URL helper
- Kroki URL helper → Rendering endpoint
Follow one path through the code
Read the encoder to see how source becomes a URL-safe payload. The helper transports the source; syntax validation and visual quality still depend on the diagram language and renderer.
7. Technical dossier
Built from the source at commit 05b27cd (3 files). Each item comes from a pattern match in the code, so open the linked file before relying on it.
7.1. Layers and modules
Folders are sorted into layers by name, from the user interface down to data access. Because the sorting uses names only, the diagram says nothing about calls between layers.
Mermaid Layered view
flowchart TB
subgraph L_application["Application services"]
direction TB
application_0["scripts<br/>1 file"]
end
| Module | Layer | Files | Types | Extensions |
|---|---|---|---|---|
scripts | Application services | 1 | 0 | .py |
7.2. C4 model
From system context to code declarations. Each level reflects the available source evidence.
UML 1 · System context
The widest C4 view: who uses the project and which outside systems and data stores it relies on. Rendered with uml-mcp.
PlantUML source
@startuml
!include <C4/C4_Context>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System(SYS, "uml-skill", "uml-skill packages diagram-writing instructions and a small Python he…")
System_Ext(E0, "Kroki")
Rel(P_cli, SYS, "Uses")
Rel(SYS, E0, "Calls")
@enduml
UML 2 · Containers
One level closer: the parts that run separately inside the project, their main language and how calls flow between them. Rendered with uml-mcp.
PlantUML source
@startuml
!include <C4/C4_Container>
LAYOUT_LEFT_RIGHT()
Person(P_cli, "CLI user")
System_Boundary(SYS, "uml-skill") {
Container(APP, "uml-skill", "Python")
}
System_Ext(E0, "Kroki")
Rel(P_cli, APP, "Uses")
Rel(APP, E0, "Calls")
@enduml
UML 3 · Components and layers
Modules grouped by source-layer classification. Boundaries show organization, not runtime isolation or call relationships. Rendered with uml-mcp.
PlantUML source
@startuml
!include <C4/C4_Component>
LAYOUT_TOP_DOWN()
System_Boundary(SYS, "uml-skill") {
Boundary(L0, "Application services", "layer") {
Component(M0_0, "scripts", "Python", "1 files")
}
}
@enduml
UML 4 · Code
Selected declarations, fields and methods grouped by source file. No inheritance or call edges are inferred. Rendered with uml-mcp.
PlantUML source
@startuml
skinparam backgroundColor transparent
skinparam shadowing false
skinparam roundCorner 10
skinparam defaultFontName Arial
skinparam defaultFontSize 13
skinparam ArrowColor #4e6070
skinparam ArrowFontColor #3d4f5f
skinparam titleFontSize 14
skinparam actorBorderColor #006a62
skinparam actorBackgroundColor #e9f3f4
skinparam usecaseBorderColor #006a62
skinparam usecaseBackgroundColor #e9f3f4
skinparam componentBorderColor #006a62
skinparam componentBackgroundColor #e9f3f4
skinparam interfaceBorderColor #006a62
skinparam interfaceBackgroundColor #ffffff
skinparam nodeBorderColor #4e6070
skinparam nodeBackgroundColor #f4f8fb
skinparam databaseBorderColor #006a62
skinparam databaseBackgroundColor #ffffff
skinparam cloudBorderColor #4e6070
skinparam cloudBackgroundColor #f0f5fa
skinparam artifactBorderColor #006a62
skinparam artifactBackgroundColor #ffffff
skinparam rectangleBorderColor #b0c2d3
skinparam activityBorderColor #006a62
skinparam activityBackgroundColor #e9f3f4
skinparam partitionBorderColor #b0c2d3
skinparam stereotypeCBackgroundColor #ffffff
top to bottom direction
hide empty members
package "uml-skill" {
object "scripts/kroki_url.py" as FN0 {
encode_for_kroki()
kroki_url()
main()
}
}
@enduml
7.3. Public interface
Outside code can use everything listed here. The project also declares 0 public types.
Command line 3
7.4. Business logic
No classes were extracted, so these are the largest source files and their functions.
scripts/kroki_url.pyencode_for_kroki, kroki_url, main
7.5. External integrations
Hosts named in the code
kroki.io1 filesscripts/kroki_url.py:36
7.6. CI/CD pipeline
No CI/CD pipeline in the repository. The code is built and run by hand, as described above.
7.7. Deployment
Mermaid Deployment diagram
flowchart LR
repo[("GitHub repository")]
local["Local machine"]
repo -->|"clone and run"| local
The repository has no Dockerfile, Compose file or hosting configuration, so the code runs on the machine that clones it.
The available sources do not document the remaining sections.
8. Reference
3 / 3 eligible files read (8 in the tree); 0 oversized, 0 failed reads and 0 syntax diagnostics.
What the scan covers
Known dependency/build folders, credential files and binaries are excluded. The scan covers READMEs, recognized manifests and parser-supported source files.
Linguist statistics cover the whole repository and may include other languages.
10. Files to read 2
11. Glossary
Repository
The versioned source files, configuration, and history of a project.
README
The repository’s entry document, usually covering its purpose and initial setup.
Dependency
A library, tool, or service that another component needs to build or run.
API
An interface through which software components exchange requests and results. An API does not have to use HTTP.
Published port
A host port mapped to a service’s container port. Publishing a port can expose that service beyond its container network.
CLI
A text interface in which commands and arguments select operations. Exit codes let scripts detect success or failure.
Continuous integration
Automated checks that run when source changes, such as building, testing, and linting. Passing checks cover only what those checks exercise.
MCP
Model Context Protocol: a protocol through which an AI client discovers and calls tools and reads resources from a server.
Mermaid
A text-based diagram language. Nodes and connections describe a model; the diagram itself does not execute the project.
GPU
A processor designed for parallel workloads, including graphics rendering and many numerical operations.
12. References
- antoinebou12. (2026, November 5). uml-skill. [Software repository] github.com.
- antoinebou12. (2026, November 5). uml-skill: README. [Repository documentation] github.com.
- antoinebou12. (2026, November 5). scripts/kroki_url.py. [Source file] github.com.
- antoinebou12. (2026, November 5). README.md. [Source file] github.com.
- Boucher, A. (2026, October 23). uml-skill: Instructions with a small encoding fallback. [Project article] antoineboucher.info.
Sources without a publication date show the date they were last checked, November 5, 2026. File links retain the inspected revision where available.