ASCII Diagram Creator Skill

ASCII Diagram Creator

Overview

This skill is a visual generator agent that creates clear, terminal-compatible ASCII diagrams to communicate system changes, migrations, and architectural decisions. It analyzes your context, selects the appropriate diagram type, generates the diagram, and refines based on feedback.

Key Capabilities:

Codebase auto-discovery: Automatically scan project structure, detect architecture patterns, and populate diagrams
Project-type templates: Pre-built templates for Bulletproof React, Next.js, Express, Monorepos
Context-aware diagram selection: Automatically choose the best diagram type for your use case
Professional ASCII formatting: Box-drawing characters, arrows, and status indicators
Diagram versioning: Metadata tracking for diagram freshness and staleness detection
Mermaid export: Convert ASCII diagrams to Mermaid syntax for graphical rendering
Git-aware staleness detection: Automatically flag outdated diagrams based on file changes
PR template integration: Auto-include relevant diagrams in pull request descriptions
CLAUDE.md directive setup: Optionally configure proactive diagram suggestions
Iterative refinement: Adjust width, alignment, and content based on feedback
Five diagram types: Architecture, Before/After, Phased Migration, Data Flow, Relationship/Synergy
Terminal-compatible: 80-character max width, works in any terminal/markdown

When to Use This Skill

Trigger Phrases:

"create an ascii diagram" / "make a text diagram"
"create a diagram showing..."
"visualize this architecture"
"show how X connects/synergizes/relates"
"diagram the workflow/phases/flow"
"illustrate the relationships between"
"show before and after"

Use PROACTIVELY when:

User is planning a major refactoring or migration
User is restructuring directories or file organization
User needs to communicate system changes in a PR description
User is explaining architecture to team members
User mentions "show me", "visualize", or "diagram"

Do NOT use when:

User wants graphical/image output (use Mermaid or external tools)
User needs flowcharts with complex branching (consider Mermaid)
User is asking about code, not structure or flow
Simple lists would suffice instead of visual diagrams

Response Style

Visual Generator Agent: Analyze context to determine what needs visualization, select appropriate diagram type, generate ASCII diagram, and refine through iteration.

Execution Pattern:

Analyze context: Understand what the user wants to visualize
Select diagram type: Choose Architecture, Before/After, Phased, or Data Flow
Generate diagram: Create initial diagram with proper formatting
Present with explanation: Show diagram and explain visual elements
Refine on request: Adjust based on user feedback ("make it wider", "add status")
MANDATORY - Output & Integration: Execute Phase 4 completely:
- Offer Mermaid export for graphical rendering
- Run staleness detection if existing diagrams found
- Offer PR integration if user is working on a PR
- Ask about CLAUDE.md directive setup
- Output completion checklist (see below)

CRITICAL: The skill is NOT complete until the Completion Checklist is output.

Workflow

| Phase | Description | Details | |-------|-------------|---------| | 0 | Context Analysis | → workflow/phase-0-context-analysis.md | | 1 | Diagram Type Selection | → workflow/phase-1-diagram-selection.md | | 2 | Diagram Generation | → workflow/phase-2-generation.md | | 3 | Iterative Refinement | → workflow/phase-3-refinement.md | | 4 | Output & Integration (MANDATORY) | → workflow/phase-4-output-integration.md |

⚠️ IMPORTANT: Phase 4 must ALWAYS be executed. Do not consider the skill complete until you have offered all integration options and output the completion checklist.

Quick Reference

Diagram Types

| Type | Purpose | Best For | |------|---------|----------| | Architecture | System components and relationships | Showing how modules connect | | Before/After | Compare current vs proposed state | Migration plans, refactoring | | Phased Migration | Step-by-step progression | Multi-phase projects | | Data Flow | How data moves through system | API flows, pipelines | | Relationship/Synergy | How elements interact or complement | SDLC phases, skill workflows, team structures |

Visual Elements

| Category | Elements | Usage | |----------|----------|-------| | Box Drawing | ┌─┬─┐ │ │ │ ├─┼─┤ └─┴─┘ | Component boundaries | | Arrows | ──► ◄── ◄─► ──✗ ──✓ | Relationships, flow | | Status | ✓ ✗ ⏳ 🔄 ⚠️ 🔴 | Progress indicators |

Formatting Rules

| Rule | Value | Reason | |------|-------|--------| | Max width | 80 characters | Terminal compatibility | | Box alignment | Vertical centers | Visual clarity | | Spacing | Between sections | Readability | | Legends | When using symbols | Self-documenting |

Diagram Versioning

Add metadata to track diagram freshness and enable staleness detection:

<!-- diagram-meta
  type: architecture
  created: 2025-01-23
  last-verified: 2025-01-23
  source-patterns: [src/features/*, src/app/routes/*]
  stale-after: 30d
-->

Metadata Fields: | Field | Purpose | |-------|---------| | type | Diagram type (architecture, data-flow, etc.) | | created | Initial creation date | | last-verified | Last time diagram was confirmed accurate | | source-patterns | Glob patterns of directories diagram represents | | stale-after | Days until diagram should be re-verified |

Staleness Detection: When files matching source-patterns are modified after stale-after days from last-verified, the diagram should be re-verified.

Reference Materials

Workflow Automation

This skill can be integrated into your workflow automatically. See the README for:

Hook-based auto-triggers when creating feature branches
CLAUDE.md directives for proactive diagram suggestions
Sub-agent integration for feature planning workflows

Mandatory Completion Checklist

You MUST output this checklist before the skill is complete. This ensures all integration options are offered.

## Diagram Generation Complete

### Outputs
- [ ] ASCII diagram generated (80-char width)
- [ ] Diagram metadata added (if saving to file)

### Integration Options Offered (Phase 4)
- [ ] Mermaid export: [offered/accepted/declined/not applicable]
- [ ] PR integration: [offered/accepted/declined/not applicable]
- [ ] CLAUDE.md directive: [offered/accepted/declined/already configured]

### Next Steps
- Recommended save location: [path]
- Staleness tracking: [enabled/disabled]

Example completed checklist:

## Diagram Generation Complete

### Outputs
- [x] ASCII diagram generated (80-char width)
- [x] Diagram metadata added

### Integration Options Offered (Phase 4)
- [x] Mermaid export: offered, user declined
- [x] PR integration: accepted, added to PR description
- [x] CLAUDE.md directive: offered, user accepted (added to ~/.claude/CLAUDE.md)

### Next Steps
- Recommended save location: docs/architecture/auth-flow.md
- Staleness tracking: enabled (30 days)

Metadata

Category: planning Source: Protocol conversion from ~/.claude/protocols/ASCII_DIAGRAM_PROTOCOL.yaml Version: 0.3.1

Agent Skills: ASCII Diagram Creator

Install this agent skill to your local

Skill Files