| name | converting-files |
| description | Convert a file from one format to another inside the container — documents, images, audio, video. Routes to the right engine (pandoc, LibreOffice, ImageMagick, ffmpeg) by format pair. Triggers on "convert X to Y", "turn this docx into a pdf", "make a gif from this mp4", "md to docx", "batch-convert these images", or any single-file or batch format change where the source and target extensions differ. NOT for editing content (use docx/pptx/xlsx/pdf skills), creating files from scratch, or reading a file you already have in context. |
| metadata | {"version":"0.1.1"} |
converting-files
Four conversion engines are already in this container — pandoc, libreoffice
(headless), ImageMagick's convert, and ffmpeg. The hard part isn't running
them; it's picking the right one. pandoc mangles a real .docx into PDF;
LibreOffice is the tool for that. pandoc is better than LibreOffice for
md → docx. Neither touches mp4 → gif. This skill encodes that routing so the
choice isn't re-derived (often wrongly) each time.
scripts/convert.py is a dispatcher over those four binaries, not a new engine.
Use it for the common cases; drop to the raw engine when you need flags it
doesn't pass through.
Is this the right skill?
| You want to… | Use instead |
|---|
| Change a file's format (ext A → ext B) | this skill |
| Edit/author a Word/PPT/Excel/PDF's content | docx / pptx / xlsx / pdf skills |
| Read a file already shown in context | just read it — no conversion |
| Extract text/tables from a PDF | pdf-reading skill |
| Fill or merge PDFs | pdf skill |
Format change = here. Content change = a content skill. A docx → pdf is a
format change; "fix the grammar in this docx" is not.
Engine routing (the actual content of this skill)
Source family → target family decides the engine. The dispatcher applies this;
the table is here so the reasoning is auditable and so you can call the engine
directly when needed.
| From → To | Engine | Why |
|---|
| markup → markup (md, html, rst, latex, org, epub, rtf, ipynb…) | pandoc | what it's built for |
| markup → Office (md → docx/pptx/odt) | pandoc | cleaner than LibreOffice from markup |
| Office → markup (docx/odt/pptx → md/html…) | pandoc | reads modern OOXML well |
| Office → PDF (docx/pptx/xlsx → pdf) | LibreOffice | preserves layout; pandoc mangles it |
| Office ↔ Office, or legacy (.doc/.ppt/.xls) anything | LibreOffice | pandoc can't read legacy binary formats at all |
| markup → PDF (md → pdf) | pandoc (+pdflatex/xelatex) | lighter than LibreOffice for plain markup |
| image ↔ image (png, jpg, gif, webp, tiff, heic, svg…) | ImageMagick | convert in out |
| image → PDF | ImageMagick | |
| audio ↔ audio (mp3, wav, flac, ogg, aac, m4a, opus…) | ffmpeg | |
| video ↔ video, mp4 → gif, gif → mp4 | ffmpeg | gif-from-video is an ffmpeg job, not ImageMagick |
gif lives in both image and video worlds: png → gif is ImageMagick (still
image), mp4 → gif is ffmpeg (animation). The dispatcher handles the split by
the source family.
Usage
python3 /mnt/skills/user/converting-files/scripts/convert.py --plan in.docx out.pdf
python3 /mnt/skills/user/converting-files/scripts/convert.py in.docx out.pdf
python3 /mnt/skills/user/converting-files/scripts/convert.py notes.md notes.docx
python3 /mnt/skills/user/converting-files/scripts/convert.py clip.mp4 clip.gif
python3 .../convert.py photo.png photo.jpg -quality 85
python3 .../convert.py song.wav song.mp3 -b:a 192k
python3 .../convert.py paper.md paper.pdf --pdf-engine=xelatex
python3 .../convert.py weird.docx weird.md --engine pandoc
Exit codes: 0 ok, 2 no route exists, 3 engine failed (stderr tail
printed), 4 bad args / missing input.
Batch
The dispatcher is one file at a time by design — batch is a shell loop so each
file's failure is visible:
for f in *.png; do
python3 /mnt/skills/user/converting-files/scripts/convert.py "$f" "${f%.png}.webp" || echo "FAILED: $f"
done
Gotchas (the things that cost a re-run)
- LibreOffice names the output itself — it writes
<input-stem>.<ext> into
--outdir, ignoring your chosen filename. The dispatcher renames to your
OUTPUT after. If you call libreoffice raw, expect the input-stem name.
- LibreOffice headless is single-instance. Two concurrent
--headless calls
collide on the user profile and one silently does nothing. Run them serially
(the batch loop above is serial — fine).
- markup → pdf needs a LaTeX engine.
pdflatex/xelatex are present, but
exotic Unicode wants --pdf-engine=xelatex. If LaTeX chokes on the content,
route through docx first: md → docx (pandoc) then docx → pdf (LibreOffice).
- ImageMagick here is IM6 (
convert, not magick). Policy may block some
formats; if convert refuses a PDF/PS op, that's the /etc/ImageMagick-6/policy.xml
security policy, not a missing codec.
- markup → jira emits heading anchors.
md → jira works (both are pandoc
formats), but headings come out as h1. {anchor:slug}Title — pandoc materializing
the auto-generated heading ID. Suppress with
--engine pandoc ... -f markdown-auto_identifiers (pass the format-with-extension
yourself, since the dispatcher infers a bare markdown).
--plan lies about nothing but runs nothing — it can't tell you the
content will survive (e.g. a pptx → md drops all layout). Plan checks the
route; only a real run checks the result.
Why not VERT (or any web converter) as the skill
VERT (vert.sh) is a Svelte/WASM browser app wrapping these same engines
(libvips, ffmpeg.wasm, Pandoc-wasm) for a human at a tab who wants local privacy.
There's no library or CLI to import — the app is the UI. In-container we
already have the native binaries with full filesystem access and no browser
memory ceiling, so the WASM wrappers would be strictly slower and weaker. VERT is
a good recommendation to a person; it's the wrong shape for a skill. This skill
is the in-container equivalent of what VERT does in a tab.
