arxiv-doc-builder
Convert an arXiv paper to Markdown for reading or implementation reference. Use when asked to convert, fetch, or create documentation for an arXiv paper by its ID, or when a paper with a known arXiv ID needs to be read or referenced. Fetches the LaTeX source when available (plus
Install
npx skills add https://github.com/ultimatile/arxiv-skills/tree/main/skills/arxiv-doc-builder
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ultimatile-arxiv-skills@llmmart
git clone https://github.com/ultimatile/arxiv-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole ultimatile/arxiv-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
arXiv Document Builder
Procedure
Run the converter:
# Using global command (recommended) convert-paper ARXIV_ID [--output-dir DIR] # Using script directly uv run --project "SKILL_DIR" "SKILL_DIR/arxiv_doc_builder/convert_paper.py" ARXIV_ID [--output-dir DIR]SKILL_DIR: replace with the absolute path of the directory this SKILL.md is in. It is a placeholder, not a shell variable. Keep the double quotes around it, so a path containing spaces stays one argument. The command then runs from any working directory.--output-dir: Directory where{SAFE_ID}/{SAFE_ID}.mdwill be created. Default: current working directory (not apapers/subdirectory).{SAFE_ID}, here and below, isARXIV_IDwith/replaced by_, as inhep-th/9711200→hep-th_9711200. A new-style ID contains no/, so it is used unchanged.- Use absolute paths to control output location precisely.
convert-paperdoes the metadata lookup, downloads, extraction, and directory creation itself; do not run curl, tar, or mkdir for them.On success,
convert-paperprints the Markdown file's path on itsOutput:line. The file opens with a YAML frontmatter block of provenance metadata;references/output-format.mddocuments its fields, including whatmetadata_statusrecords. The File Organization section ofreferences/output-format.mdshows the layout of the paper's directory,{SAFE_ID}/.
When Conversion Fails or Falls Back to PDF
If you edited a file under {SAFE_ID}/source/ and re-ran convert-paper, read references/source-edits.md first and follow it before any line below.
When you made no such edit, or once that file no longer tells you to edit again or re-run, read the file that the line matching the output points to. For an output not listed here, act on what the output itself says.
Whichever file you follow, change the source only as it directs. Do NOT attempt broad preprocessing (replacing documentclass, expanding \newcommand, removing environments, etc.) — pandoc handles revtex4/revtex4-2, custom commands, picture environments, and theorem environments correctly.
convert-paperexits with code 2 after printingError: Found N files with \documentclass→references/multiple-documentclass.md- It prints
Pandoc conversion failed:, and the pandoc message after it containsunexpected (orunexpected [→references/unknown-arity-macros.md - It prints
Pandoc conversion failed:, and the pandoc message after it contains neither →references/pandoc-failures.md - It prints
Pandoc did not finish withinorPandoc exceeded the <N> MB memory watchdog, or a pandoc run has not returned →references/pandoc-runaway.md - It prints
No LaTeX source, falling back to naive PDF conversion...→references/pdf-conversion.md
Files (arxiv-skills)
-
arxiv_doc_builder
-
arxiv_id.py 5.4 KB
Loading… -
arxiv_metadata.py 33.8 KB
Loading… -
convert_latex.py 20.9 KB
Loading… -
convert_paper.py 7.1 KB
Loading… -
convert_pdf_double_column.py 1.6 KB
Loading… -
convert_pdf_extract.py 2.4 KB
Loading… -
convert_pdf_simple.py 2.2 KB
Loading… -
convert_pdf_split_columns.py 2.6 KB
Loading… -
convert_pdf_with_vision.py 2.8 KB
Loading… -
fetch_paper.py 15.8 KB
Loading… -
pdf_converter_lib.py 12.6 KB
Loading… -
pdf_image_lib.py 6.3 KB
Loading… -
_version.py 3.2 KB
Loading… -
__init__.py 0 B
Loading…
-
-
references
-
multiple-documentclass.md 1.3 KB
Loading… -
output-format.md 9.8 KB
Loading… -
pandoc-failures.md 1.1 KB
Loading… -
pandoc-runaway.md 5.8 KB
Loading… -
pdf-conversion.md 3.5 KB
Loading… -
source-edits.md 1.1 KB
Loading… -
unknown-arity-macros.md 1.9 KB
Loading…
-
-
tests
-
fixtures
-
datacite
-
0705.1442.json 2 KB
Loading… -
1207.7214.json 3.2 KB
Loading… -
2203.02155.json 6.1 KB
Loading… -
2409.03108.json 4 KB
Loading… -
2609.14487.json 2.4 KB
Loading… -
hep-th_9711200.json 3.5 KB
Loading…
-
-
-
conftest.py 8.1 KB
Loading… -
test_arxiv_id.py 3.7 KB
Loading… -
test_arxiv_metadata.py 59.9 KB
Loading… -
test_cli_contracts.py 10.3 KB
Loading… -
test_convert_pandoc_bounds.py 13.5 KB
Loading… -
test_convert_paper_handoff.py 2.1 KB
Loading… -
test_convert_paper_routing.py 5.1 KB
Loading… -
test_dual_import_parity.py 4.6 KB
Loading… -
test_extract_title.py 1.7 KB
Loading… -
test_fetch_paper_main.py 7.8 KB
Loading… -
test_fetch_source_host.py 882 B
Loading… -
test_find_main_tex.py 4.4 KB
Loading… -
test_metadata_status_latex.py 4.1 KB
Loading… -
test_metadata_status_pdf.py 4.5 KB
Loading… -
test_network_guard.py 2 KB
Loading… -
test_packaging.py 1.6 KB
Loading… -
test_pdf_converter_lib.py 4.2 KB
Loading… -
test_pdf_image_lib.py 3.8 KB
Loading… -
test_skill_placeholders.py 1.7 KB
Loading… -
test_skill_references.py 9 KB
Loading… -
test_version.py 8.5 KB
Loading… -
test_version_drift.py 10.9 KB
Loading…
-
-
pyproject.toml 1.7 KB
Loading… -
SKILL.md 3.2 KB
--- name: arxiv-doc-builder description: Convert an arXiv paper to Markdown for reading or implementation reference. Use when asked to convert, fetch, or create documentation for an arXiv paper by its ID, or when a paper with a known arXiv ID needs to be read or referenced. Fetches the LaTeX source when available (plus the PDF) and converts it with pandoc; PDF-only papers get a naive single-column fallback. --- # arXiv Document Builder ## Procedure 1. Run the converter: ```bash # Using global command (recommended) convert-paper ARXIV_ID [--output-dir DIR] # Using script directly uv run --project "SKILL_DIR" "SKILL_DIR/arxiv_doc_builder/convert_paper.py" ARXIV_ID [--output-dir DIR] ``` - `SKILL_DIR`: replace with the absolute path of the directory this SKILL.md is in. It is a placeholder, not a shell variable. Keep the double quotes around it, so a path containing spaces stays one argument. The command then runs from any working directory. - `--output-dir`: Directory where `{SAFE_ID}/{SAFE_ID}.md` will be created. **Default: current working directory** (not a `papers/` subdirectory). `{SAFE_ID}`, here and below, is `ARXIV_ID` with `/` replaced by `_`, as in `hep-th/9711200` → `hep-th_9711200`. A new-style ID contains no `/`, so it is used unchanged. - Use absolute paths to control output location precisely. `convert-paper` does the metadata lookup, downloads, extraction, and directory creation itself; do not run curl, tar, or mkdir for them. 2. On success, `convert-paper` prints the Markdown file's path on its `Output:` line. The file opens with a YAML frontmatter block of provenance metadata; `references/output-format.md` documents its fields, including what `metadata_status` records. The File Organization section of `references/output-format.md` shows the layout of the paper's directory, `{SAFE_ID}/`. ## When Conversion Fails or Falls Back to PDF If you edited a file under `{SAFE_ID}/source/` and re-ran `convert-paper`, read `references/source-edits.md` first and follow it before any line below. When you made no such edit, or once that file no longer tells you to edit again or re-run, read the file that the line matching the output points to. For an output not listed here, act on what the output itself says. Whichever file you follow, change the source only as it directs. Do NOT attempt broad preprocessing (replacing documentclass, expanding `\newcommand`, removing environments, etc.) — pandoc handles revtex4/revtex4-2, custom commands, `picture` environments, and theorem environments correctly. - `convert-paper` exits with code 2 after printing `Error: Found N files with \documentclass` → `references/multiple-documentclass.md` - It prints `Pandoc conversion failed:`, and the pandoc message after it contains `unexpected (` or `unexpected [` → `references/unknown-arity-macros.md` - It prints `Pandoc conversion failed:`, and the pandoc message after it contains neither → `references/pandoc-failures.md` - It prints `Pandoc did not finish within` or `Pandoc exceeded the <N> MB memory watchdog`, or a pandoc run has not returned → `references/pandoc-runaway.md` - It prints `No LaTeX source, falling back to naive PDF conversion...` → `references/pdf-conversion.md` -
uv.lock 124.6 KB · in bundle
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.