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

[pereponkin]

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.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 11, 2026, 12:20 PM ET / 16:20 UTC.

Summary
The reported command defect remains on current main and in release 0.12.0. Upstream packaging confirms the missing extras, and the reporter supplies a successful workaround; no open replacement PR was found. The repository profile also prohibits automatic closure.

Reproducibility: yes. source establishes the missing-extras path: the current PDF command installs the base package, while the converter requires optional dependencies. No conversion was executed during this read-only review.

Next step
A manually promoted, focused skill correction is safe; skill classification excludes automatic strict-bug intake.

Review details

Best possible solution:

Use an extras-bearing uvx invocation consistently, preserve the no-separate-install workflow, and add a brief conditional -c UTF-8 note without changing upstream detection.

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

Yes, source establishes the missing-extras path: the current PDF command installs the base package, while the converter requires optional dependencies. No conversion was executed during this read-only review.

Is this the best way to solve the issue?

Yes, requesting existing extras is the narrow repair; uv’s documented --from syntax expresses it directly, while the reporter’s --with variant is also supported. Charset guidance should remain conditional.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The secondary charset misdetection was not independently reproduced; keep any note conditional on the input’s known encoding.

Codex review notes: model internal, reasoning medium; reviewed against 15bcfe33f597.

Label changes

Label changes:

• add P2: Advertised PDF and Office conversions fail under the documented commands, with a narrow instruction repair and a working workaround.
• add impact:ux-friction: Users must discover missing extras outside the skill before its examples work.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: Advertised PDF and Office conversions fail under the documented commands, with a narrow instruction repair and a working workaround.
• impact:ux-friction: Users must discover missing extras outside the skill before its examples work.

Evidence reviewed

Acceptance criteria:

• scripts/validate-skills
• git diff --check
• uvx --from 'markitdown[all]' markitdown input.pdf -o output.md
• uvx --from 'markitdown[all]' markitdown input.docx -o output.md
• uvx --from 'markitdown[all]' markitdown input.xlsx -o output.md

What I checked:

• Current commands establish the dependency boundary: The skill directly invokes uvx markitdown throughout its PDF and Office examples without requesting extras, while explicitly advertising those formats. This establishes why the MarkItDown packaging and uvx contracts apply. (skills/markdown-converter/SKILL.md:14, 15bcfe33f597)
• Reported dependency version confirms optional format support: The v0.1.7 tag resolves to this commit. Its package metadata places PDF, Word, Excel, and PowerPoint dependencies under optional extras, including all, rather than the base dependency list. (packages/markitdown/pyproject.toml:38, fd239d5d2be4)
• PDF failure matches the reported exception: PdfConverter accepts PDF input and raises MissingDependencyException before conversion when its optional imports failed, matching the supplied traceback. (packages/markitdown/src/markitdown/converters/_pdf_converter.py:526, fd239d5d2be4)
• Supported extras invocation: The official tools guide documents isolated uvx environments, --from for requesting package extras, and --with for additional dependencies. A direct extras-bearing invocation is uvx --from 'markitdown[all]' markitdown. (docs/guides/tools.md, fb1439e3f881)
• Release still contains the commands: The skill at release 0.12.0 also uses bare uvx markitdown for the advertised binary formats; no released correction was established. (skills/markdown-converter/SKILL.md:14, b7f726924927)
• Discussion and canonical search: The supplied report includes a Windows 11 traceback with MarkItDown 0.1.7 and uv 0.11.23, plus successful conversion after requesting extras. The repository-wide issue/PR listing found no open fix PR. Feedback on your markdown-converter skill #3 is closed promotional feedback, not the same defect; the supplied merged PR references concern unrelated features.

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.

[pereponkin]

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.

[pereponkin]

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.