Ascii Art

ASCII Art Converter

Setup

Before first use, run the environment setup (idempotent, `. Do NOT proceed to options until you have a valid file path on disk.

1. Plain text (no file, or file doesn't exist) → text (FIGlet banner)
2. Nothing provided → ask what they want to convert

Options Prompt

Parse the user's message for pre-specified options. Then prompt for unspecified options using AskUserQuestion.

• "defaults" or "just do it" → skip prompting, use all defaults
• "random" or "surprise me" → skip prompting, use --random
• All options specified → skip prompting

Use questions array (max 4 per call, 3 options per question). List ALL choices with numbers in the question text. Top 3 as selectable options — user can type any number/name in free-text. No "Other" option. Default as option 1.

Image/video — ask in two rounds:

1. Round 1 (4 questions): Style → Color → Export → Background
2. Round 2 (only if export is interactive or tsx): Mouse Mode → Animation

Text: Font → Color → Export → Background (single round).

Image/video options

| Option | Choices | Default | |--------|---------|---------| | Style | classic, braille, block, edge, dot-cross, halftone, particles, retro-art, terminal | classic | | Color | grayscale, original, matrix, amber, custom (hex/named) | grayscale | | Ratio | original, 16:9, 4:3, 1:1, 3:4, 9:16 | original | | Background | dark, light, transparent | dark | | Dither | none, floyd-steinberg, bayer, atkinson | none | | Font size | 6-30 px | 14 | | Export | png, html, svg, txt, md, clipboard, interactive, tsx | auto (image→png, video→gif) | | Mouse mode | push, attract | push | | Animation | none, noise-field, intervals, beam-sweep, glitch, crt | none |

Mouse mode and animation only apply to interactive/tsx exports. Only ask when export is interactive or tsx. Don't ask for --hover-strength, --area-size, or --spread — use defaults.

Text options

| Option | Choices | Default | |--------|---------|---------| | Font | standard, doom, banner, slant, big, small, block, lean, mini, script, shadow, speed, ansishadow, ansiregular | standard | | Color | grayscale, original, matrix, amber, custom | grayscale | | Background | dark, light, transparent | dark | | Export | terminal (stdout), txt, md, png, html, svg, clipboard | terminal |

Interactive/tsx exports require image or video input — text is not supported.

Disambiguation

• "block" as a style = Unicode block elements (█▓▒░) for images
• "block" as a font = block-letter FIGlet font for text
• For block-style text art, use --font ansi_shadow or --font block
• Custom colors: hex (#ff6600) or named (coral, skyblue). Translate creative descriptions to hex.

Running the Conversion

{{SKILL_DIR}}/scripts/.venv/bin/python {{SKILL_DIR}}/scripts/convert.py \
  --input "" \
  --type  \
  --style  \
  --color  \
  --background  \
  --export  \
  [--dither ] \
  [--ratio ] \
  [--font-size ] \
  [--cols ] \
  [--font ] \
  [--custom-color ""] \
  [--mouse-mode ] \
  [--animation ] \
  [--invert] [--random] \
  [--fps ] \
  [--filename ]

Output

All files save to an ascii/ folder in the current working directory (created automatically).

• Text (terminal): prints to stdout + auto-copies to clipboard. Show in a code block.
• File exports (png, html, svg, txt, md, gif): show the file path. Use Read tool to display images inline.
• Interactive HTML: show the file path. Suggest: open to view in browser.
• React TSX: show the file path. Show usage: import { AsciiArt } from './'
• Never preview in terminal for image/video/interactive exports.

Error Handling

• Video fails: likely missing ffmpeg or opencv. Suggest: pip install opencv-python-headless
• Image fails: check file exists and is a valid image format
• Interactive/tsx + text: prints error — interactive requires image/video input

Follow-up

After showing the result, offer to: try a different style/color, adjust settings, export in another format, or try random mode. Remember the previous input path for re-runs.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: neethanwu
• Source: neethanwu/ascii-art
• License: MIT

Install and usage instructions live in the source repository linked above.