plantuml-ascii_skill

Overview

This skill generates terminal-friendly ASCII art diagrams from PlantUML text. It converts PlantUML source into plain ASCII (-txt) or Unicode-enhanced ASCII (-utxt) output, producing text files that work well in READMEs, email, or environments without image support. It supports sequence, class, activity, state, component, use case, and deployment diagrams in text form.

How this skill works

Provide a PlantUML diagram in .puml/.puml or as inline text and run PlantUML with the -txt or -utxt flag. The tool renders the diagram as a text file (diagram.atxt or diagram.utxt) using either pure ASCII or box-drawing Unicode characters. You can run the plantuml CLI, use the JAR via java -jar, or integrate with build tools like Ant to produce ASCII outputs automatically.

When to use it

• Embedding diagrams in Markdown/README files where images are undesirable or blocked
• Creating diagrams for terminal-first workflows or documentation viewed in SSH sessions
• Including diagrams in Git commit messages, PR descriptions, or code comments
• Sharing diagrams by email or plain-text channels where images can’t be embedded
• Generating quick previews of diagrams without a graphical renderer

Best practices

• Keep diagrams simple; complex layouts degrade in text rendering
• Use short labels to avoid breaking ASCII alignment
• Prefer -utxt (Unicode) for clearer box-drawing if viewers support UTF-8
• Verify output in a fixed-width font terminal (Courier, Monaco, Consolas)
• Test output before sharing to catch alignment or encoding issues

Example use cases

• Convert a sequence diagram to ASCII for inclusion in a repository README
• Produce a Unicode-enhanced class diagram for an RFC sent by email
• Automatically generate ASCII activity diagrams during CI and attach to build logs
• Render a deployment diagram as plain text for offline or low-bandwidth review
• Use Ant task to output ASCII diagrams as part of documentation builds