How do I install the Conversion skill?

Run npx skillmds@latest add stencila/conversion in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Conversion safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Conversion?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Conversion free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Conversion?

stencila (@stencila) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Conversion by stencila — Agent Skill

Name: Conversion
Author: stencila

Conversion

Converting documents between formats with stencila convert - lossless vs lossy targets, quantifying conversion losses, decoding options, and ingesting documents by DOI, arXiv, or PubMed Central identifier. Use when converting to or from DOCX, PDF, LaTeX, JATS, IPYNB, MyST, Quarto or other formats, or importing published papers.

stencila 51d6cbd 3.2 KB Updated Sep 17, 2026

File contents

Converting Stencila documents

NO_COLOR=1 stencila convert input.docx output.smd --yes

Formats are inferred from file extensions; --from/--to override. The input may be a path, a URL, or a bare identifier (see Ingestion below). stencila formats list prints the live capability table — which formats decode (From), encode (To), and are lossless. Consult it rather than guessing.

Lossless vs lossy

Only the data formats round-trip losslessly: CBOR, CBOR+Zstd, JSON, JSON+Zip, JSON5, JSON-LD, YAML. Everything else — DOCX, PDF, LaTeX, JATS, HTML, Markdown flavours, IPYNB — is lossy to some degree.

When converting to a lossy target, quantify what is dropped:

--input-losses — action on losses decoding the input
--output-losses — action on losses encoding the output

Both accept ignore, trace, debug (default), info, warn, error, abort, or a .json/.yaml filename to write the losses to. After a lossy conversion, tell the user what was lost rather than silently producing a smaller document.

Decoding options that matter

--fine / --coarse — decoding granularity. Fine (the default for most formats) decodes to the finest structure; coarse preserves un-modelled markup in larger blocks and is the default for LaTeX. Use --coarse when fine decoding of a partially supported format mangles structure.
--pages N-M / --exclude-pages — page selection for multi-page inputs (e.g. PDFs): --pages 1,3,5-7, --pages 2-, keywords odd/even.
--include-structuring / --exclude-structuring — structuring operations that infer document structure (sections, abstracts, references) from loosely structured input. Example: --include-structuring sections-to-abstract.
--ignore-artifacts — re-download / re-process instead of using cached intermediate artifacts in .stencila/artifacts/.

Ingesting published papers

convert accepts identifiers directly as the input — a DOI, arXiv id, or PubMed Central id — and fetches the document:

NO_COLOR=1 stencila convert 10.1371/journal.pcbi.1011999 paper.smd --yes
NO_COLOR=1 stencila convert arxiv:2004.10643 paper.smd --yes
NO_COLOR=1 stencila convert PMC7067710 paper.smd --yes

DOIs may be bare, doi:-prefixed, or https://doi.org/… URLs; arXiv ids may be arXiv:-prefixed or arxiv.org URLs. OpenAlex work ids (e.g. W2741809807) are also accepted.

External tools

Some formats encode via external tools. --tool pandoc selects Pandoc for encoding, --from-tool for decoding, and arguments after -- pass through to the tool:

NO_COLOR=1 stencila convert doc.smd doc.docx --tool pandoc --yes -- --reference-doc=style.docx

Checking a conversion

Round-trip through JSON to see exactly what Stencila modelled:

NO_COLOR=1 stencila convert doc.docx --to json --yes | head -100

---name: conversiondescription: Converting documents between formats with stencila convert - lossless vs lossy targets, quantifying conversion losses, decoding options, and ingesting documents by DOI, arXiv, or PubMed Central identifier. Use when converting to or from DOCX, PDF, LaTeX, JATS, IPYNB, MyST, Quarto or other formats, or importing published papers.---# Converting Stencila documents```shNO_COLOR=1 stencila convert input.docx output.smd --yes```Formats are inferred from file extensions; `--from`/`--to` override. Theinput may be a path, a URL, or a bare identifier (see Ingestion below).`stencila formats list` prints the live capability table — which formatsdecode (`From`), encode (`To`), and are lossless. Consult it rather thanguessing.## Lossless vs lossyOnly the data formats round-trip losslessly: **CBOR, CBOR+Zstd, JSON,JSON+Zip, JSON5, JSON-LD, YAML**. Everything else — DOCX, PDF, LaTeX, JATS,HTML, Markdown flavours, IPYNB — is lossy to some degree.When converting to a lossy target, quantify what is dropped:- `--input-losses` — action on losses decoding the input- `--output-losses` — action on losses encoding the outputBoth accept `ignore`, `trace`, `debug` (default), `info`, `warn`, `error`,`abort`, or a `.json`/`.yaml` filename to write the losses to.After a lossy conversion, tell the user what was lost rather than silentlyproducing a smaller document.## Decoding options that matter- `--fine` / `--coarse` — decoding granularity. Fine (the default for most formats) decodes to the finest structure; coarse preserves un-modelled markup in larger blocks and is the default for LaTeX. Use `--coarse` when fine decoding of a partially supported format mangles structure.- `--pages N-M` / `--exclude-pages` — page selection for multi-page inputs (e.g. PDFs): `--pages 1,3,5-7`, `--pages 2-`, keywords `odd`/`even`.- `--include-structuring` / `--exclude-structuring` — structuring operations that infer document structure (sections, abstracts, references) from loosely structured input. Example: `--include-structuring sections-to-abstract`.- `--ignore-artifacts` — re-download / re-process instead of using cached intermediate artifacts in `.stencila/artifacts/`.## Ingesting published papers`convert` accepts identifiers directly as the input — a DOI, arXiv id, orPubMed Central id — and fetches the document:```shNO_COLOR=1 stencila convert 10.1371/journal.pcbi.1011999 paper.smd --yesNO_COLOR=1 stencila convert arxiv:2004.10643 paper.smd --yesNO_COLOR=1 stencila convert PMC7067710 paper.smd --yes```DOIs may be bare, `doi:`-prefixed, or `https://doi.org/…` URLs; arXiv idsmay be `arXiv:`-prefixed or arxiv.org URLs. OpenAlex work ids (e.g.`W2741809807`) are also accepted.## External toolsSome formats encode via external tools. `--tool pandoc` selects Pandoc forencoding, `--from-tool` for decoding, and arguments after `--` pass throughto the tool:```shNO_COLOR=1 stencila convert doc.smd doc.docx --tool pandoc --yes -- --reference-doc=style.docx```## Checking a conversionRound-trip through JSON to see exactly what Stencila modelled:```shNO_COLOR=1 stencila convert doc.docx --to json --yes | head -100```

Frequently asked questions