What formats does it handle?

Images (PNG, JPG, WEBP, BMP, TIFF, GIF, ICO, AVIF, HEIC/HEIF); Markdown to PDF/HTML; HTML to Markdown; CSV/JSON/YAML/TOML/XML; SVG to raster; Base64; text encoding.

How do I run batch conversions?

Use directory or glob patterns and the --output-dir option as shown in Quick Routing; for example: python3 scripts/convert_image.py ./photos/ --output-dir ./webp --format webp.

Do I need to install dependencies?

Yes. Each task lists required packages in Install Deps. Install all with the recommended command or per-task minimal installs to keep the environment lean.

file-converter

Scanned

npx machina-cli add skill georgekhananaev/claude-skills-vault/file-converter --openclaw

Files (1)

SKILL.md

9.1 KB

File Converter

Convert files between formats w/ single & batch support. All scripts use consistent CLI patterns.

When to Use

Convert images between PNG, JPG, WEBP, BMP, TIFF, GIF, ICO, AVIF, HEIC/HEIF
Resize/crop images w/ fit modes (contain, cover, fill, inside, outside)
Convert markdown -> PDF or HTML w/ themes
Convert HTML -> markdown (w/ tag stripping control)
Transform CSV <-> JSON <-> YAML <-> TOML <-> XML
SVG <-> raster conversion (PNG, JPG, WEBP, BMP, TIFF)
Base64 encode/decode files (w/ data URI support, stdin)
Fix text encoding issues (detect, convert w/ error handling strategies)

Quick Routing

Task	Script	Deps
Image convert/resize	`convert_image.py`	Pillow, pillow-heif (opt)
Markdown -> HTML	`md_to_html.py`	markdown, pygments
Markdown -> PDF	`md_to_pdf.py`	markdown + weasyprint\|pdfkit
HTML -> Markdown	`html_to_md.py`	markdownify, bs4
CSV/JSON/YAML/TOML/XML	`csv_json_yaml.py`	pyyaml, tomli-w, xmltodict, dicttoxml (per format)
SVG convert	`svg_convert.py`	cairosvg, Pillow
Base64 encode/decode	`base64_codec.py`	(none)
Text encoding	`text_encoding.py`	chardet (opt)
Cross-platform utils	`platform_utils.py`	(none) - shared by pdf/svg scripts

Install Deps

# All deps (recommended)
pip install Pillow markdown pygments weasyprint markdownify beautifulsoup4 cairosvg pyyaml chardet tomli-w xmltodict dicttoxml

# Optional
pip install pillow-heif                    # HEIC/HEIF support

# Minimal (per task)
pip install Pillow                          # Images only
pip install markdown pygments               # MD -> HTML only
pip install markdown weasyprint             # MD -> PDF only (macOS: brew install pango)
pip install markdownify beautifulsoup4      # HTML -> MD only
pip install pyyaml                          # YAML support
pip install tomli-w                         # TOML write (read: Python 3.11+ built-in)
pip install xmltodict dicttoxml             # XML support
pip install cairosvg                        # SVG -> raster (macOS: brew install cairo)
pip install chardet                         # Encoding detection

CLI Patterns

All scripts share consistent arg patterns:

# Single file
python3 scripts/<script>.py input.ext output.ext

# Batch (directory or glob)
python3 scripts/<script>.py *.ext --output-dir ./out
python3 scripts/<script>.py ./dir/ --output-dir ./out --format ext

1. Image Convert & Resize

# Format conversion
python3 scripts/convert_image.py photo.png photo.webp
python3 scripts/convert_image.py photo.jpg photo.avif --quality 80

# Resize
python3 scripts/convert_image.py photo.jpg thumb.jpg --width 300
python3 scripts/convert_image.py photo.png banner.png --width 1200 --height 400 --fit cover

# Batch convert directory
python3 scripts/convert_image.py ./photos/ --output-dir ./webp --format webp --width 1200 --quality 85
python3 scripts/convert_image.py *.png --output-dir ./thumbs --format jpg --width 300 --height 300 --fit cover

Fit modes:

Mode	Behavior
contain	Fit inside bounds, preserve ratio (def)
cover	Fill bounds, crop overflow
fill	Stretch to exact dimensions
inside	Like contain, but only shrink (never enlarge)
outside	Like cover, but never crop

Supported: PNG, JPG, WEBP, BMP, TIFF, GIF, ICO, AVIF, HEIC/HEIF (w/ pillow-heif)

Auto-fixes EXIF orientation. Guards against decompression bombs (300M pixel limit).

2. Markdown -> HTML

# Single file
python3 scripts/md_to_html.py README.md readme.html
python3 scripts/md_to_html.py doc.md doc.html --theme dark

# Batch
python3 scripts/md_to_html.py ./docs/ --output-dir ./site --theme github

Themes: github (def), dark, minimal, print

Features: fenced code blocks, syntax highlighting, tables, TOC w/ permalinks, responsive CSS.

3. Markdown -> PDF

# Single file
python3 scripts/md_to_pdf.py report.md report.pdf
python3 scripts/md_to_pdf.py spec.md spec.pdf --theme report

# Batch
python3 scripts/md_to_pdf.py ./docs/ --output-dir ./pdfs --theme report

Themes: default, report (formal w/ serif), minimal

PDF engines: weasyprint (preferred, no external deps on macOS) or pdfkit (requires wkhtmltopdf). Script auto-detects available engine.

4. HTML -> Markdown

# Single file
python3 scripts/html_to_md.py page.html page.md

# Strip unwanted tags (default: script, style, noscript)
python3 scripts/html_to_md.py page.html page.md --strip script style nav footer

# Keep all HTML tags (no stripping)
python3 scripts/html_to_md.py page.html page.md --keep-all

# Batch
python3 scripts/html_to_md.py ./site/ --output-dir ./docs

5. Data Formats (CSV/JSON/YAML/TOML/XML)

# Any direction
python3 scripts/csv_json_yaml.py data.csv data.json
python3 scripts/csv_json_yaml.py data.json data.yaml
python3 scripts/csv_json_yaml.py config.yaml config.json
python3 scripts/csv_json_yaml.py config.toml config.json
python3 scripts/csv_json_yaml.py data.json data.xml

# Batch
python3 scripts/csv_json_yaml.py *.csv --output-dir ./json --format json

Supported: CSV, JSON, YAML (.yaml/.yml), TOML (.toml), XML (.xml). All directions supported where deps are installed.

6. SVG Conversion

# SVG -> raster
python3 scripts/svg_convert.py icon.svg icon.png --width 512
python3 scripts/svg_convert.py logo.svg logo.jpg --width 1024 --quality 90

# Raster -> SVG (embedded image wrapper)
python3 scripts/svg_convert.py photo.png photo.svg

# Batch
python3 scripts/svg_convert.py *.svg --output-dir ./png --format png --width 256

7. Base64 Encode/Decode

# Encode to stdout
python3 scripts/base64_codec.py encode image.png

# Encode to data URI (for HTML/CSS embedding)
python3 scripts/base64_codec.py encode image.png --data-uri

# Encode to file
python3 scripts/base64_codec.py encode image.png -o image.b64

# Decode
python3 scripts/base64_codec.py decode image.b64 -o image.png

# Batch
python3 scripts/base64_codec.py encode *.png --output-dir ./b64

8. Text Encoding

# Detect encoding
python3 scripts/text_encoding.py detect file.txt
python3 scripts/text_encoding.py detect *.txt

# Convert encoding (single mode requires -o to prevent accidental overwrite)
python3 scripts/text_encoding.py convert file.txt --to utf-8 -o output.txt
python3 scripts/text_encoding.py convert file.txt --from latin-1 --to utf-8 -o output.txt

# Handle unmappable characters
python3 scripts/text_encoding.py convert file.txt --to ascii --errors replace -o clean.txt
python3 scripts/text_encoding.py convert file.txt --to ascii --errors ignore -o clean.txt

# Batch convert to UTF-8
python3 scripts/text_encoding.py convert *.txt --to utf-8 --output-dir ./utf8

Error modes: strict (default, fail on unmappable), replace (use ? placeholder), ignore (skip unmappable chars).

Common Workflows

Web optimization pipeline

# Convert photos to WEBP, resize for web, generate thumbnails
python3 scripts/convert_image.py ./photos/ --output-dir ./web --format webp --width 1200 --quality 80
python3 scripts/convert_image.py ./photos/ --output-dir ./thumbs --format webp --width 300 --height 300 --fit cover --quality 75

Documentation pipeline

# Generate HTML site from markdown docs
python3 scripts/md_to_html.py ./docs/ --output-dir ./site --theme github

# Generate PDF reports
python3 scripts/md_to_pdf.py ./docs/ --output-dir ./pdfs --theme report

Data migration pipeline

# CSV -> JSON for API import
python3 scripts/csv_json_yaml.py ./exports/ --output-dir ./json --format json

# JSON config -> YAML
python3 scripts/csv_json_yaml.py config.json config.yaml

Icon generation pipeline

# SVG -> multiple PNG sizes for app icons
for size in 16 32 64 128 256 512; do
  python3 scripts/svg_convert.py icon.svg "icon-${size}.png" --width $size
done

Error Handling

All scripts:

Print errors per-file in batch mode, continue w/ remaining files
Exit 1 on fatal errors (missing deps, no input)
Print size before/after for each conversion
Create output directories automatically
Handle KeyboardInterrupt gracefully (exit 130)

Cross-Platform Support

Scripts work on macOS, Linux, and Windows. Native library paths (cairo, pango, gobject) are auto-configured via platform_utils.py:

macOS: /opt/homebrew/lib, /usr/local/lib
Linux: /usr/local/lib, /usr/lib/x86_64-linux-gnu
Windows: GTK runtime, MSYS2, Conda paths + os.add_dll_directory()

Stdin Support

md_to_html.py and base64_codec.py accept - for stdin input:

cat README.md | python3 scripts/md_to_html.py - output.html
cat file.bin | python3 scripts/base64_codec.py encode - -o file.b64

Integration

Pairs with: token-optimizer (compress markdown before PDF), code-quality (validate scripts)

Source

git clone https://github.com/georgekhananaev/claude-skills-vault/blob/main/.claude/skills/file-converter/SKILL.mdView on GitHub

Overview

File Converter enables seamless conversion and transformation of diverse file types—images, Markdown, data formats, SVG, base64, and text encodings—using single-file or batch workflows. It unifies image resizing, Markdown-to-PDF/HTML, data format interchanges (CSV/JSON/YAML/TOML/XML), and SVG rasterization across platforms, streamlining content and data pipelines.

How This Skill Works

The skill uses a collection of Python scripts (e.g., convert_image.py, md_to_html.py, md_to_pdf.py, html_to_md.py, csv_json_yaml.py, svg_convert.py, base64_codec.py, text_encoding.py, platform_utils.py) that expose consistent CLI interfaces. Each script is invoked as python3 scripts/<script>.py input.ext output.ext, with batch support via directory or glob patterns and an --output-dir option. Dependencies are installed per task following the Install Deps guidance, enabling cross-task functionality across environments.

When to Use It

Resize and convert product photos for web storefronts (PNG/JPG/WEBP, etc.).
Generate HTML or PDF outputs from Markdown with themes.
Transform data between CSV, JSON, YAML, TOML, and XML.
Convert SVG assets to PNG/JPG/WebP for apps or websites.
Base64 encode/decode files or fix text encoding issues in localization pipelines.

Quick Start

Step 1: Pick the task and script (e.g., convert_image.py, md_to_pdf.py, csv_json_yaml.py).
Step 2: Run a single-file conversion: python3 scripts/convert_image.py input.png output.webp (adjust options as needed).
Step 3: For batch processing, use a directory or glob and --output-dir to collect results.

Best Practices

Test with a representative sample before batch runs to verify format and options.
When resizing images, specify width/height and a fit mode to control output (contain, cover, etc.).
Use --output-dir for batch runs to keep originals intact and outputs organized.
For encoding tasks, leverage data URI support and implement error handling strategies.
Install only the necessary dependencies per task to minimize footprint and avoid conflicts.

Example Use Cases

Batch resize PNG/JPG images to web-optimized sizes and convert to WEBP for a product catalog.
Generate HTML and PDF outputs from a set of Markdown docs with a chosen theme.
Convert a dataset across CSV, JSON, YAML, and XML for a data pipeline.
Convert SVG icons to PNG for a responsive web app and ensure crisp raster output.
Base64-encode a file for embedding in a data URI within a web page or email.

Frequently Asked Questions

Add this skill to your agents