AutoGineer
Generated banner for Plantuml Ascii
Generated logo for Plantuml Ascii

Plantuml Ascii

GitHubOfficialFirst committed by AungMyoKyawDistributed by GitHub

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk
Download ZIP

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/github/plantuml-ascii/download

  2. 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

FlagFormatDescription
-txtASCIIPure ASCII characters
-utxtUnicode ASCIIEnhanced 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

  1. Keep it simple: Complex diagrams don't render well in ASCII

  2. Short labels: Long text breaks ASCII alignment

  3. Use Unicode (-utxt): Better visual quality with box-drawing chars

  4. Test before sharing: Verify in terminal with fixed-width font

  5. 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

SKILL.md

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

FlagFormatDescription
-txtASCIIPure ASCII characters
-utxtUnicode ASCIIEnhanced 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

  1. Keep it simple: Complex diagrams don't render well in ASCII

  2. Short labels: Long text breaks ASCII alignment

  3. Use Unicode (-utxt): Better visual quality with box-drawing chars

  4. Test before sharing: Verify in terminal with fixed-width font

  5. 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

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.

Attribution and licence

First committed by
GitHub avatar of AungMyoKyawAungMyoKyaw
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/plantuml-ascii · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
AungMyoKyaw

AutoGineer is not affiliated with or endorsed by AungMyoKyaw or GitHub.

Download ZIP

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