Pandoc Convert

intent

use this skill when a user needs to convert documents between formats using pandoc. covers single-file conversions (markdown to docx, html to pdf, etc.), batch directory conversions, pdf engine setup, citation handling, templates, table of contents generation, and troubleshooting. prefer the bundled wrapper scripts because they add dependency checks, safer defaults, progress output, retries, and detailed reports. do not silently install pandoc; report missing dependencies and ask first.

inputs

pandoc installation: pandoc binary must be available in PATH. if missing, the skill will report validation error and offer installation help via ${CLAUDE_SKILL_DIR}/scripts/install_pandoc.sh.

pdf engine (conditional): for pdf output, a pdf engine is required. common engines: pdflatex (ascii/latin only), xelatex (unicode, chinese, arabic), lualatex (unicode). for chinese documents, xelatex is preferred. user must install separately; the skill does not install pdf engines.

input file or directory: path to source document(s). single file (e.g. README.md) or directory glob (e.g. docs/*.md). must exist and be readable.

output format: target format (html, docx, pdf, epub, latex, typst, rst, asciidoc, org, odt, rtf, ipynb, or json). inferred from output filename extension or explicitly specified via --to flag.

optional external files (conditional):

• bibliography file (refs.bib, .json, or .yaml) for --citeproc citations
• csl style file (.csl) for citation formatting
• reference docx (reference.docx) for word styling via --reference-doc
• html or latex template file (.html, .tex) via --template
• css stylesheet (.css) for html/epub via --css
• resource directories (images, assets) reachable via --resource-path

bash tools: bash shell, python3 (for batch conversion), file operations (glob, grep, find).

environment variable: ${CLAUDE_SKILL_DIR} points to the skill directory containing scripts/ subdirectory.

procedure

step 1: validate inputs and confirm scope

inputs: user request (file path or directory, desired output format, any special options).

action: check whether this is a single-file or batch conversion. if user says "batch", "directory", "multiple files", or "glob", prepare batch workflow. otherwise, assume single-file workflow.

outputs: confirmed scope (single or batch), input path(s), target format.

step 2: check pandoc availability and report status

inputs: confirmed scope, paths.

action: run validation script to detect pandoc and any missing dependencies.

bash ${CLAUDE_SKILL_DIR}/scripts/validate.sh

if pandoc is missing, show validation error. do not silently install. ask user whether they want installation help and offer the dry-run command:

bash ${CLAUDE_SKILL_DIR}/scripts/install_pandoc.sh

only run with --yes flag after explicit user approval.

if pandoc is present, continue.

outputs: pandoc availability confirmed (or installation guidance offered), list of detected dependencies.

step 3a (single-file): infer output path and options

inputs: input file path, requested output format (inferred from user request or filename extension).

action: if output path not specified, suggest default (same directory, same basename, new extension). ask user to confirm or provide explicit path.

gather any special options user mentioned: citations, toc, pdf engine, templates, css, resource paths, extraction of media.

outputs: confirmed input file, confirmed output path, option list.

step 3b (batch): prepare batch parameters

inputs: input directory, output directory, target format, any special options (retries, fail-fast, continue-on-error, report format).

action: confirm output directory path. ask whether user wants a progress report (markdown or json).

outputs: confirmed input directory, output directory, format, options, report preference.

step 4: run conversion

single-file: execute convert wrapper with confirmed parameters.

bash ${CLAUDE_SKILL_DIR}/scripts/convert.sh <input> -o <output> [--pdf-engine xelatex] [--toc] [--citeproc --bibliography refs.bib --csl style.csl] [other options]

batch: execute python batch wrapper.

python3 ${CLAUDE_SKILL_DIR}/scripts/batch_convert.py <input-dir> --output-dir <output-dir> --to <format> [--pdf-engine xelatex] [--retries 2] [--report report.md] [--json-report report.json]

inputs: input file(s), output path(s), format, all options from step 3a or 3b.

outputs: converted file(s) written to disk, command output showing success/failure, progress (for batch).

step 5: report results and handle failures

inputs: command exit status, output file path(s), error messages (if any).

single-file success: report the output file path. user can open/download immediately.

single-file failure: show the actionable error message from pandoc. suggest the smallest fix (missing dependency, format mismatch, file not found, etc.). offer retry command.

batch success: report summary (X files converted, Y skipped, Z failed). list output directory. if report was generated, note its path.

batch partial failure: never claim full success if any files failed. list failed files with paths. show the error for each failure. provide retry command that re-runs only failed files.

outputs: user-facing result summary, file path(s) or directory, any error details and recovery steps.

decision points

single-file vs. batch: if user says "batch", "directory", "glob", "multiple files", or "批量", use batch workflow (step 3b + batch conversion). otherwise use single-file workflow (step 3a + single conversion).

pandoc missing: if validation reports pandoc not found, stop and ask user whether to install. do not proceed with conversion. only install after explicit user approval.

pdf engine missing for pdf output: if user requests pdf output and --pdf-engine not provided, check if xelatex is available (preferred for unicode/chinese). if not available, ask user to install it or specify a fallback engine. do not attempt pdf conversion without a working pdf engine.

output path conflict: if output file already exists, ask user whether to overwrite. do not overwrite silently.

citations requested but bibliography missing: if user asks for citations (--citeproc) but no bibliography file is provided, ask for the file path or confirm that user wants citation processing without a bibliography (which will search for references.bib in the current directory).

template or css requested but file missing: if user specifies --template or --css and the file does not exist, report error and do not attempt conversion.

batch with failures and continue-on-error: if batch conversion has partial failures and --continue-on-error is active, list failed files. do not claim batch succeeded. provide a retry command that converts only the failed subset.

resource paths and relative directories: if conversion references images or assets in sibling directories or parent paths, confirm --resource-path includes those directories. if user does not specify it, infer common paths (., assets, images) and suggest the option.

extract media from docx: if user converts from docx to markdown and does not specify --extract-media, warn that embedded images will be lost. suggest --extract-media media to extract and preserve images.

output contract

single-file success: one file written to the confirmed output path. file is valid in the target format. example output paths:

• README.docx (docx format)
• output.pdf (pdf format)
• index.html (html format)

batch success: directory tree created at the output directory path, with converted files preserving relative paths from the input directory.

• input: docs/chapter1/intro.md, output dir: out, target: pdf → output: out/chapter1/intro.pdf
• skipped files, hidden directories (.git, node_modules, etc.), and the output directory itself are not processed.

batch reports (optional): if --report or --json-report flags provided:

• markdown report: human-readable summary of success, failure, skipped counts; lists failed files with error messages.
• json report: structured data with counts, file list, timestamps, and per-file status and error details.

on failure: no file is written. pandoc error message is returned as-is. user receives actionable guidance (missing dependency, format mismatch, invalid option, file not found, network timeout for remote resources, rate-limited citation server, etc.).

outcome signal

user knows the skill worked when:

• single-file: user can see the converted file in the confirmed output location and open it in the target application (word, browser, pdf viewer, epub reader, etc.).
• batch: user can list the output directory and see the converted file tree with all expected files present. if a report was requested, user can read it to confirm per-file status.
• no errors: conversion command exits with code 0, no error message in stdout/stderr.
• progress feedback: for batch conversions, user sees progress output like [3/28] converting docs/a.md -> out/a.pdf in real-time.

on failure: user sees the specific error (e.g. "pandoc not found", "xelatex not installed", "input file not found", "bibliography file not found") and a recovery step (install pandoc, install xelatex, check path, provide file).