markdown-converter: documented commands fail on PDF/Office — uvx never installs the extras

Every command in skills/markdown-converter/SKILL.md uses a bare uvx markitdown, which installs the core package only. That works for HTML/CSV/JSON/XML/text, but fails on every binary format the skill advertises — PDF, .docx, .xlsx, .pptx — because the optional extras are never pulled in.

So the skill's own headline example does not run:

$ uvx markitdown input.pdf
Traceback (most recent call last):
  ...
  File ".../markitdown/_markitdown.py", line 360, in convert_local
    return self._convert(file_stream=fh, stream_info_guesses=guesses, **kwargs)
  ...
    raise FileConversionException(attempts=failed_attempts)
markitdown._exceptions.FileConversionException: File conversion failed after 1 attempts:
 - PdfConverter threw MissingDependencyException with message: PdfConverter recognized the
   input as a potential .pdf file, but the dependencies needed to read .pdf files have not
   been installed. To resolve this error, include the optional dependency [pdf] or [all]
   when installing MarkItDown.

Same failure for .docx, .xlsx and .pptx.

Fix — pass the extras through uvx:

uvx --with 'markitdown[all]' markitdown input.pdf -o output.md

Verified working on the same file that produced the traceback above. uv caches the environment, so only the first run pays the download. Per-format extras (markitdown[pdf], [docx], [xlsx], [pptx]) are lighter when the input type is known, but [all] is the safe default for a general-purpose skill.

Since the "no installation required" framing is what makes the skill attractive, it might be worth keeping that line and just moving the extras into every example, rather than adding a separate install step.

Environment: markitdown 0.1.7, uv/uvx 0.11.23, Windows 11.

Secondary, and a documentation suggestion rather than a bug in the skill: for text-based inputs containing Cyrillic, charset auto-detection misreads UTF-8 and writes mojibake into the output file. A CSV containing Переponkin (verified valid UTF-8, no BOM — bytes start d0 9f) converts to –ü–µ—Ä–µponkin. Passing -c UTF-8 fixes it. The corruption lands in the file itself, not just terminal display, so it propagates into whatever consumes the Markdown. -c is already in the options list; one line noting when it is needed would save people the debugging. Binary formats carry their own encoding and are unaffected.

Written by Claude (Anthropic) at the request of the repo user who hit this; they reviewed and consented to filing it. Both issues were reproduced locally before reporting.

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 16, 2026, 10:33 AM ET / 14:33 UTC.

Summary
The documented commands remain broken on current main and release 0.12.0. The reporter’s open fix PR now owns the repair; keep this issue open pending its outcome, consistent with the repository’s conservative cleanup policy.

Reproducibility: yes. source provides a high-confidence path: run the documented bare command on a PDF with only MarkItDown’s base dependencies. Upstream packaging and the reporter’s failure/success results establish the mechanism; this review did not execute conversions.

Next step
Review and resolve #43 before revisiting this issue; a second repair would duplicate the reporter’s work.

Review details

Best possible solution:

Use consistent, double-quoted extras selection throughout the skill while retaining on-demand execution and conditional advice for known text encodings.

Do we have a high-confidence way to reproduce the issue?

Yes, source provides a high-confidence path: run the documented bare command on a PDF with only MarkItDown’s base dependencies. Upstream packaging and the reporter’s failure/success results establish the mechanism; this review did not execute conversions.

Is this the best way to solve the issue?

Yes. The linked PR uses uv’s documented extras mechanism and confines charset guidance to an existing option, avoiding changes to upstream conversion behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 2784a3898df4.

Label changes

Label changes:

remove clawsweeper:fix-shape-clear: Current issue advisory state no longer selects this label.
remove clawsweeper:queueable-fix: Current issue advisory state no longer selects this label.

Label justifications:

P2: The advertised document conversions fail through the supplied commands, but a verified command workaround and focused implementation PR exist.
impact:ux-friction: Users must discover optional-dependency syntax to make the skill’s advertised examples work.

Evidence reviewed

What I checked:

Current commands still omit extras: All ten command mentions use bare uvx markitdown despite advertising PDF, Word, Excel, and PowerPoint conversion. (skills/markdown-converter/SKILL.md:14, 2784a3898df4)
Dependency contract confirms the defect: The skill explicitly executes MarkItDown, making its packaging contract relevant. Version v0.1.7 places PDF and Office libraries in optional dependencies, including the all extra, rather than base dependencies. (packages/markitdown/pyproject.toml, fd239d5d2be4)
Supported extras invocation: The official tools guide documents isolated uvx environments and --from package[extras] as the supported way to request a tool’s optional dependencies. (docs/guides/tools.md)
Released skill also remains affected: The skill in release 0.12.0 contains the same bare commands; the tag resolves to b7f7269. (skills/markdown-converter/SKILL.md:14, b7f726924927)
Open implementation candidate: fix(skills): request markitdown extras in markdown-converter commands #43 is open and unmerged. Its single-file patch updates all ten invocations to request markitdown[all] and adds the conditional charset note. The supplied body records successful Windows PDF, DOCX, and XLSX conversions. (skills/markdown-converter/SKILL.md, b2e82f20eb70)
Reporter follow-up narrows the charset advice: The supplied discussion reports successful --from conversion and a short UTF-8 CSV misdetected on Windows and Ubuntu; explicitly selecting UTF-8 preserves the text. The reporter appropriately leaves upstream detection unchanged. See markdown-converter: documented commands fail on PDF/Office — uvx never installs the extras #41 (comment).

Likely related people:

unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Adding the reproduction for the secondary charset point, since the review noted it wasn't independently verified.

Input file, 42 bytes, valid UTF-8 with no BOM:

$ head -c 40 t.csv | od -An -tx1
 6e 61 6d 65 2c 72 6f 6c 65 0a d0 9f d0 b5 d1 80
 d0 b5 70 6f 6e 6b 69 6e 2c 6f 77 6e 65 72 0a 43

$ file t.csv
t.csv: CSV Unicode text, UTF-8 text

d0 9f is U+041F CYRILLIC CAPITAL LETTER PE — so the input is unambiguous.

Converting to a file (not stdout, so terminal rendering can't be blamed):

$ uvx markitdown t.csv -o a.md && cat a.md
| name | role |
| --- | --- |
| –ü–µ—Ä–µponkin | owner |
| Claude | agent |

$ uvx markitdown t.csv -c UTF-8 -o b.md && cat b.md
| name | role |
| --- | --- |
| Переponkin | owner |
| Claude | agent |

The mojibake is written into a.md itself, so it propagates into whatever consumes the Markdown downstream — which is the part that makes it worth a line of documentation rather than leaving people to notice it later.

This is markitdown's own charset detection, not anything the skill does, and I haven't checked whether it's platform- or locale-dependent — this was markitdown 0.1.7 on Windows 11. So the conditional wording the review asked for seems right: something like "for text formats with non-Latin content, pass -c UTF-8 if you know the input encoding" rather than a blanket instruction.

Environment as before: markitdown 0.1.7, uv/uvx 0.11.23, Windows 11.

Separately, on the main point — the review is right that --from is the better shape, and I've switched to it locally:

uvx --from 'markitdown[all]' markitdown input.pdf -o output.md

Verified byte-identical output and the same runtime as the --with variant on a 1.2 MB PDF, so --from looks like the one to document.

Follow-up written by Claude (Anthropic) at the reporter's request, same as the original issue.

Follow-up on the charset point: the review asked to keep it conditional because it wasn't independently reproduced, and I'd flagged that I hadn't checked platform dependence. Both gaps are now closed, and the conclusion is narrower and more useful than "Cyrillic breaks".

It reproduces on a second platform, and locale is not the variable. A clean Ubuntu 24.04 / Python 3.11 environment, same 42-byte fixture:

$ grep -c 'Переponkin' a.md b.md
a.md:0
b.md:1

Setting LANG=C.UTF-8 LC_ALL=C.UTF-8 explicitly changed nothing.

It is not a detector regression. Both environments run charset_normalizer 3.5.1; pinning charset-normalizer==3.3.2 produces the same mojibake.

What the detector actually decides, on those exact bytes:

$ uvx --from markitdown python -c "
from charset_normalizer import from_bytes
r = from_bytes(open('t.csv','rb').read())
print('best:', r.best().encoding)
print('candidates:', [(m.encoding, round(m.chaos,3)) for m in list(r)[:4]])
"
best: mac_iceland
candidates: [('mac_iceland', 0.0), ('cp850', 0.044), ('cp852', 0.044), ('utf_8', 0.108)]

mac_iceland scores a perfect 0.0 chaos on the sample; utf_8 comes fourth. markitdown then decodes with that guess, so the mojibake is written into the output file.

The variable is sample length, not language. An 11 KB Russian CSV built the same way is detected as utf_8 and converts cleanly with no flag — 60/60 rows intact. So full documents are not at risk; short files are. That is a much smaller blast radius than my original comment implied.

Given that, the conditional wording the review asked for looks right, with length as the condition rather than alphabet — something like: "Short text files (CSV/JSON/XML/HTML/TXT) with non-Latin content can be mis-detected; pass -c UTF-8 when you know the encoding." No change to detection behaviour, just a line that saves someone the debugging.

Environments: markitdown 0.1.7 + charset_normalizer 3.5.1 on both Windows 11 / Python 3.12 and Ubuntu 24.04 / Python 3.11.

Follow-up written by Claude (Anthropic) at the reporter's request, as with the earlier comments. The Ubuntu reproduction was run independently in a second environment.

A PR implementing the reviewed fix is now open: #43.

It follows the shape the review settled on — uvx --from "markitdown[all]" markitdown used consistently across all ten invocations in skills/markdown-converter/SKILL.md, including the two piped/stdin forms, plus a conditional -c UTF-8 note that leaves upstream charset detection alone. A CHANGELOG.md entry under Unreleased is included per AGENTS.MD.

One deliberate deviation from the review's wording: double quotes rather than single. In cmd.exe single quotes are literal characters, and uv rejects the argument outright with Expected package name starting with an alphanumeric character, found '. Double quotes work in bash, PowerShell and cmd.exe alike, and the original report came from Windows, so the documented form should survive there. Both forms were run side by side to confirm it rather than reasoned about.

The three acceptance conversions were executed on Windows 11 with uv 0.11.23 and MarkItDown 0.1.7 — PDF, DOCX and XLSX all convert, and git diff --check is clean. scripts/validate-skills is Ruby and could not be run here; rather than claim otherwise, its three checks were reimplemented and run against the whole tree (54 skills, no errors, identical before and after). Worth running the real one on your side, since CI does not cover it either.

CI on the PR is currently held at action_required — first-time-contributor approval, not a failure.

Referenced as Refs #41 rather than Fixes, since the repository profile prohibits automatic closure; closing this stays with you.

Written by Claude (Anthropic) at the reporter's request, as with the earlier comments on this issue.

fix(skills): install Markdown conversion extras (#43)

Fixed in #43, merged as d15557c. The documented commands now request markitdown[all], including stdin examples; the notes also explain the charset override for misdetected text files. Thanks for the report and fix.

Reproduced the base-only PDF MissingDependencyException with MarkItDown 0.1.7. On a clean Linux environment, the updated command preserved a known synthetic marker in PDF, DOCX, XLSX, PPTX, and piped PDF output. Skill validation and independent review passed. Exact-head CI is green: https://github.com/steipete/agent-scripts/actions/runs/36652176521.

Navigation Menu

Repository navigation

markdown-converter: documented commands fail on PDF/Office — uvx never installs the extras #41

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

markdown-converter: documented commands fail on PDF/Office — uvx never installs the extras #41

Description

Activity

clawsweeper commented on Sep 11, 2026

pereponkin commented on Sep 11, 2026

pereponkin commented on Sep 11, 2026

pereponkin commented on Sep 16, 2026

steipete commented on Sep 30, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions