Universal file converter

Universal File Converter

Convert files through a capability-driven workflow. Treat this skill as a safe router over local conversion engines, not as a promise that every proprietary, encrypted, damaged, or DRM-protected format can be converted.

Non-negotiable rules

1. Preserve the source. Never overwrite or delete an input unless the user explicitly requests an in-place operation and the tool supports it safely.
2. Inspect before converting. Do not trust the extension alone; check the signature and use a format-aware probe when available.
3. Check actual capabilities. Tool support varies by build, delegates, codecs, plugins, and operating system.
4. Disclose trade-offs before lossy, layout-changing, metadata-dropping, color-changing, archive-repacking, or schema-changing conversions.
5. Never weaken a security policy, bypass DRM, expose credentials, execute embedded macros, or install software without explicit authorization.
6. Avoid shell interpolation and eval. Pass paths as literal arguments and quote them for the active shell.
7. Write to a distinct output path or temporary output, validate it, then report success. A zero exit code alone is not proof of a valid conversion.
8. For batches, test one representative file first and keep per-file success and failure records.

Workflow

1. Resolve intent

Determine the source, target format, destination, quality-versus-size preference, metadata policy, transparency or color requirements, batch scope, and device or application compatibility target. Use conservative defaults when the request is ordinary and reversible.

2. Inspect the input

Run the portable inspector with the available Python launcher:

python scripts/inspect_file.py INPUT

Then use the category-native inspector when possible:

• Video/audio: ffprobe
• Raster image: magick identify
• PDF: pdfinfo or qpdf --check
• Archive: 7z l or the platform archive tool
• Office/ebook container: ZIP integrity plus format-specific inspection

Treat an extension/signature mismatch as suspicious and stop before opening untrusted content with a complex parser.

3. Probe available engines

python scripts/probe_tools.py

Do not assume an installed program supports a requested codec or delegate. Query native capability lists when the conversion depends on them, such as ffmpeg -encoders, ffmpeg -muxers, magick identify -list format, or pandoc --list-output-formats.

4. Build a conversion plan

python scripts/plan_conversion.py INPUT OUTPUT

Use the plan as routing guidance, then load the matching reference below. If no compatible local engine is available, explain the missing capability and propose the smallest suitable dependency or a safe intermediate format.

5. Execute safely

• Prefer direct, single-generation conversion over chains of lossy intermediates.
• Prefer stream copy or lossless paths only when container and codec compatibility is confirmed.
• Use a new filename by default, such as name.converted.ext.
• Keep temporary files beside the output when atomic replacement is required.
• Do not place secrets such as stream keys or document passwords directly in logged commands.

6. Verify the result

python scripts/verify_output.py OUTPUT

Also perform format-native checks when material quality matters: compare duration, stream counts, dimensions, page counts, archive members, row counts, color profile, alpha channel, metadata, or a rendered sample.

7. Report precisely

Report the source and output paths, selected engine, source and target formats, whether the conversion was lossy, important metadata or fidelity changes, validation performed, and any warnings. Never claim unsupported fidelity.

Routing map

Family	Preferred engines	Load
Video and audio	FFprobe + FFmpeg	references/media.md
Raster images and vector graphics	ImageMagick + Inkscape	references/images-vectors.md
Documents, Office, PDF, ebooks	Pandoc + LibreOffice + Poppler/qpdf + Calibre	references/documents-pdf-ebooks.md
Archives and structured data	7-Zip/tar + bundled structured converter	references/archives-data.md
3D, CAD, fonts, GIS and uncommon formats	Blender/Assimp + FreeCAD + FontForge + GDAL	references/specialist-formats.md

Always load references/safety-quality.md for untrusted files, recursive batches, in-place requests, public upload services, credentials, encrypted files, or high-fidelity requirements. Load references/platform-installation.md only when a required executable is missing.

Bundled scripts

• scripts/inspect_file.py: inspect size, extension, MIME guess, signature, and category without modifying the file.
• scripts/probe_tools.py: discover supported local conversion engines and versions.
• scripts/plan_conversion.py: recommend candidate engines and surface fidelity risks; it never performs the conversion.
• scripts/convert_structured.py: safely convert CSV, TSV, JSON, JSONL, and NDJSON with Python only.
• scripts/verify_output.py: perform structural and tool-assisted output validation.

Resolve all resource paths relative to this skill directory. Other Agent Skills-compatible clients may ignore agents/openai.yaml; the workflow and scripts do not depend on it.