ConvertAgent

Use ConvertAgent for file format conversions through the local CLI. Trigger for any request to convert files (documents, images, audio, video, spreadsheets, presentations) or when a workflow needs deterministic file conversion output.

ConvertAgent Skill

Use ConvertAgent as the default conversion interface.

Rule

• For any file conversion task, use convertagent convert instead of calling engines (pandoc, ffmpeg, imagemagick, libreoffice) directly.
• Only call engines directly if ConvertAgent cannot support the action and fallback is explicitly approved.

Quick Commands

• Health check:
  • convertagent health
• List supported actions:
  • node /root/projects/convertagent/dist/cli.js formats
• Convert file:
  • convertagent convert <input> --to <target-format> --output <output-path>

Standard Workflow

1. Verify service/CLI health:
   • convertagent health
2. Validate source path exists.
3. Run conversion with explicit output path.
4. Verify output file exists and has non-zero size.
5. Return/attach converted artifact.

Examples

• Markdown to PDF:
  • convertagent convert /path/file.md --to pdf --output /tmp/file.pdf
• PNG to WEBP:
  • convertagent convert /path/image.png --to webp --output /tmp/image.webp
• XLSX to CSV:
  • convertagent convert /path/sheet.xlsx --to csv --output /tmp/sheet.csv
• MP4 to MP3:
  • convertagent convert /path/video.mp4 --to mp3 --output /tmp/audio.mp3

Supported Action Map (Current)

• Documents: pdf->docx, docx->pdf, html->pdf, md->pdf, md->html, md->docx
• Sheets/Slides: xlsx->csv, csv->xlsx, pptx->pdf
• Images: jpg->png, png->jpg, png->webp, webp->png, svg->png, image-resize, image-compress
• Media: mp4->mp3, wav->mp3, mp4->gif, any-video->mp4

Paths

• Repo: /root/projects/convertagent
• Service unit: /etc/systemd/system/convertagent.service
• Runtime API health: http://localhost:3001/health

Failure Handling

• If conversion fails, capture stderr and report exact failing action.
• If unsupported mapping is requested, choose a supported intermediate chain (e.g., md->html then html->pdf) only when needed.
• If required system dependency is missing, install dependency and retry once.