---
name: aifmt
description: >
  Fix, validate, and generate visual text content — diagrams, tables, boxes, and bars.
  Use when the user asks to "fix diagrams", "fix tables", "fix alignment", "validate
  mermaid", "check ascii art", "fix emoji spacing", "realign table", "fix box drawing",
  "fix progress bars", or any request about broken visual alignment in text content.
  Also use proactively after generating markdown tables, ASCII art, or diagrams to
  validate they are correct.
---

# aifmt

> Make visual text content just work.

## When to Use This Skill

**Fixing existing content:**
- "Fix the diagrams in this file"
- "The table in README.md is misaligned"
- "Fix the ASCII boxes in the output"
- "The emoji columns don't line up"
- "Fix the progress bars"

**Validating content you just generated:**
- After writing a markdown table with emoji → validate alignment
- After generating ASCII art → validate box borders
- After writing Mermaid → validate syntax

**Generating diagrams:**
- "Create a flowchart showing the auth flow"
- "Generate a sequence diagram for the API"

## Available MCP Tools

This skill requires the `aifmt` MCP server. Use its tools:

### `fix` — Repair broken visual content

```
fix(content="<file contents>", mode="all", target="github")
```

Modes: `"all"`, `"boxes"`, `"tables"`, `"bars"`, `"trees"`
Targets: `"github"` (default), `"terminal"`, or a custom profile name

**Workflow:**
1. Read the file with broken content
2. Call `fix` with the file contents and the appropriate `target`
3. **Check the response for ⚠ warnings** (see "Handling Warnings" below)
4. Write the fixed content back to the file
5. Report what was fixed — and any warnings

### `validate` — Check for issues without modifying

```
validate(content="<file contents>", checks=["tables", "mermaid", "boxes", "bars"], target="github")
```

**Workflow:**
1. Read the file to check
2. Call `validate` with the contents and the appropriate `target`
3. Report issues found (or confirm all clear), including any ⚠ warnings

### `generate` — Create diagrams using rendering engines

```
generate(description="auth login flow", format="mermaid", diagram_type="flowchart")
```

Formats: `"mermaid"`, `"plantuml-ascii"`, `"plantuml-unicode"`
Types: `"flowchart"`, `"sequence"`, `"class"`, `"state"`, `"er"`, `"architecture"`

### `targets` — List available rendering profiles

```
targets()
```

Returns the list of known rendering targets and their emoji width settings.
Use this to discover available profiles or verify width assumptions.

## Key Principles

1. **Never use `len()` for visual alignment.** Emoji and CJK characters occupy more
   than 1 column but `len()` counts them as 1. Always measure visual width.

2. **Emoji width depends on the rendering target.**
   - **Terminal emulators:** emoji = 2 monospace columns (Unicode standard).
   - **GitHub markdown code blocks:** emoji = 2.5 monospace columns (empirically measured).
   - Always pass the correct `target` so the fixer uses the right width.

3. **Use EVEN emoji counts per line/cell for GitHub markdown.** When each emoji is 2.5
   cols, an even count (0, 2, 4…) produces an integer total width — perfect alignment.
   An odd count (1, 3, 5…) produces a fractional (x.5) total — **impossible** to align
   perfectly with spaces alone.

4. **Prefer Mermaid over ASCII art** for diagrams in markdown files. Mermaid renders
   correctly on GitHub, GitLab, Obsidian, and VS Code. ASCII art will always have
   alignment issues when generated by LLMs.

5. **When you must use ASCII art**, delegate to PlantUML (`plantuml -utxt`) which has
   a real layout engine. Don't have the LLM guess column positions.

6. **Validate after generating.** After writing any table, diagram, or box-drawing
   content, call `validate` to catch issues before the user sees them.

## Handling Warnings

The `fix` and `validate` tools may return ⚠ warnings when **perfect alignment is not
possible** — most commonly due to odd emoji counts on GitHub where fractional column
widths prevent exact spacing.

**Do NOT ignore warnings.** When the tool returns warnings:

1. **Inform the user.** Explain that perfect alignment cannot be achieved and why.
2. **Suggest alternatives:**
   - Remove emoji from the affected lines/cells
   - Adjust to an **even** number of emoji per line/cell
   - Use Mermaid instead of ASCII art/tables for complex visual content
3. **Never silently present warned content as "fixed."** The user deserves to know
   the content has a known limitation.
