Plantuml Ascii — Agent Skill by GitHub

From the author

Generate ASCII art diagrams using PlantUML text mode. Use when user asks to create ASCII diagrams, text-based diagrams, terminal-friendly diagrams, or mentions plantuml ascii, text diagram, ascii art diagram. Supports: Converting PlantUML diagrams to ASCII art, Creating sequence diagrams, class diagrams, flowcharts in ASCII format, Generating Unicode-enhanced ASCII art with -utxt flag

— the description by AungMyoKyaw

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides instructions and commands for using PlantUML to generate diagrams in plain text formats. It is designed for developers and technical writers who need to include visual representations of system architectures, sequences, or workflows in environments where graphical images are not supported, such as terminal outputs, Git commit messages, or plain-text documentation files.

What it does

Converts standard PlantUML diagram definitions into ASCII art files.
Supports Unicode-enhanced box-drawing characters for improved visual clarity.
Handles various diagram types including sequence, class, activity, state, component, and deployment.
Provides command-line interface usage for batch processing and directory-based generation.
Offers guidance on terminal font requirements to ensure proper diagram alignment.

When to use it

When you need to include diagrams in README files or documentation that must remain plain text.
When working in terminal-only environments where graphical image viewers are unavailable.
When you want to version-control diagrams alongside code without binary image files.
When creating logs or reports that need to be readable directly in a console.

Advantages

Ensures diagrams are readable in any fixed-width font environment.
Eliminates the need for external image rendering tools in the final output.
Integrates seamlessly into existing command-line and CI/CD workflows.
Supports both simple ASCII and more readable Unicode box-drawing styles.

Usage examples

“Create a sequence diagram for a login process in ASCII format.”: The agent provides a PlantUML snippet and the command to generate a .atxt file, resulting in a text-based sequence diagram.
“How do I make my PlantUML diagrams look better in the terminal?”: The agent explains the use of the -utxt flag to enable Unicode box-drawing characters and recommends using a fixed-width font.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/github/plantuml-ascii/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip plantuml-ascii.zip -d .agents/skills

Documentation by AungMyoKyaw

PlantUML ASCII Art Diagram Generator

Overview

Create text-based ASCII art diagrams using PlantUML. Perfect for documentation in terminal environments, README files, emails, or any scenario where graphical diagrams aren't suitable.

What is PlantUML ASCII Art?

PlantUML can generate diagrams as plain text (ASCII art) instead of images. This is useful for:

Terminal-based workflows
Git commits/PRs without image support
Documentation that needs to be version-controlled
Environments where graphical tools aren't available

Installation

# macOS
brew install plantuml

# Linux (varies by distro)
sudo apt-get install plantuml  # Ubuntu/Debian
sudo yum install plantuml      # RHEL/CentOS

# Or download JAR directly
wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar

Output Formats

Flag	Format	Description
`-txt`	ASCII	Pure ASCII characters
`-utxt`	Unicode ASCII	Enhanced with box-drawing characters

Basic Workflow

1. Create PlantUML Diagram File

@startuml
participant Bob
actor Alice

Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml

2. Generate ASCII Art

# Standard ASCII output
plantuml -txt diagram.puml

# Unicode-enhanced output (better looking)
plantuml -utxt diagram.puml

# Using JAR directly
java -jar plantuml.jar -txt diagram.puml
java -jar plantuml.jar -utxt diagram.puml

3. View Output

Output is saved as diagram.atxt (ASCII) or diagram.utxt (Unicode).

Diagram Types Supported

Sequence Diagram

@startuml
actor User
participant "Web App" as App
database "Database" as DB

User -> App : Login Request
App -> DB : Validate Credentials
DB --> App : User Data
App --> User : Auth Token
@enduml

Class Diagram

@startuml
class User {
  +id: int
  +name: string
  +email: string
  +login(): bool
}

class Order {
  +id: int
  +total: float
  +items: List
  +calculateTotal(): float
}

User "1" -- "*" Order : places
@enduml

Activity Diagram

@startuml
start
:Initialize;
if (Is Valid?) then (yes)
  :Process Data;
  :Save Result;
else (no)
  :Log Error;
  stop
endif
:Complete;
stop
@enduml

State Diagram

@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@enduml

Component Diagram

@startuml
[Client] as client
[API Gateway] as gateway
[Service A] as svcA
[Service B] as svcB
[Database] as db

client --> gateway
gateway --> svcA
gateway --> svcB
svcA --> db
svcB --> db
@enduml

Use Case Diagram

@startuml
actor "User" as user
actor "Admin" as admin

rectangle "System" {
  user -- (Login)
  user -- (View Profile)
  user -- (Update Settings)
  admin -- (Manage Users)
  admin -- (Configure System)
}
@enduml

Deployment Diagram

@startuml
actor "User" as user
node "Load Balancer" as lb
node "Web Server 1" as ws1
node "Web Server 2" as ws2
database "Primary DB" as db1
database "Replica DB" as db2

user --> lb
lb --> ws1
lb --> ws2
ws1 --> db1
ws2 --> db1
db1 --> db2 : replicate
@enduml

Command-Line Options

# Specify output directory
plantuml -txt -o ./output diagram.puml

# Process all files in directory
plantuml -txt ./diagrams/

# Include dot files (hidden files)
plantuml -txt -includeDot diagrams/

# Verbose output
plantuml -txt -v diagram.puml

# Specify charset
plantuml -txt -charset UTF-8 diagram.puml

Ant Task Integration

<target name="generate-ascii">
  <plantuml dir="./src" format="txt" />
</target>

<target name="generate-unicode-ascii">
  <plantuml dir="./src" format="utxt" />
</target>

Tips for Better ASCII Diagrams

Keep it simple: Complex diagrams don't render well in ASCII
Short labels: Long text breaks ASCII alignment
Use Unicode (-utxt): Better visual quality with box-drawing chars
Test before sharing: Verify in terminal with fixed-width font
Consider alternatives: For complex diagrams, use Mermaid.js or graphviz

Example Output Comparison

Standard ASCII (-txt):

     ,---.          ,---.
     |Bob|          |Alice|
     `---'          `---'
      |   hello      |
      |------------->|
      |              |
      |  Is it ok?   |
      |<-------------|
      |              |

Unicode ASCII (-utxt):

┌─────┐        ┌─────┐
│ Bob │        │Alice│
└─────┘        └─────┘
  │   hello      │
  │─────────────>│
  │              │
  │  Is it ok?   │
  │<─────────────│
  │              │

Quick Reference

# Create sequence diagram in ASCII
cat > seq.puml << 'EOF'
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml
EOF

plantuml -txt seq.puml
cat seq.atxt

# Create with Unicode
plantuml -utxt seq.puml
cat seq.utxt

Troubleshooting

Problem: Garbled Unicode characters

Solution: Ensure terminal supports UTF-8 and has proper font

Problem: Diagram looks misaligned

Solution: Use fixed-width font (Courier, Monaco, Consolas)

Problem: Command not found

Solution: Install PlantUML or use Java JAR directly

Problem: Output file not created

Solution: Check file permissions, ensure PlantUML has write access

Files

ATTRIBUTION.mdAdded by AutoGineer824 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md6.0 KiB

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Needs network access, Needs a command-line tool, Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Setup TS Deep Modules
Matt Pocock· Community
Configures dependency-cruiser to enforce deep module boundaries in TypeScript repositories.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository317.5k
To Spec
Matt Pocock· Community
Synthesizes conversation context into a structured technical specification and publishes it to a project issue tracker.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Improve Codebase Architecture
Matt Pocock· Community
A systematic process to identify, visualize, and refine architectural deepening opportunities in a codebase.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Domain Modeling
Matt Pocock· Community
An expert assistant for defining project terminology, maintaining a glossary, and documenting architectural decisions.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Codebase Design
Matt Pocock· Community
A shared vocabulary and set of principles for designing deep, testable, and maintainable software modules.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Prototype
Matt Pocock· Community
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download plantuml-ascii.zip