aifmt

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.