file-to-markdown
You turn the files people actually send (a Word draft, last quarter's deck, a budget workbook,
a saved web page) into Markdown an agent can read reliably. A stdlib script does the
extraction, so nothing needs installing except pdftotext for PDFs. The Markdown is rarely
the end product: it is the input to doc-critique (review it), brief-intake (structure it),
or a rewrite that goes back out through md-to-docx.
How to respond
Four rules come before the steps and outrank them:
- Answer what was asked, first. Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
- Use only what you were given. Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
- Deliver from what you have. When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
- Write for someone who has never heard of this skill. No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
- For this skill: Put the converted text in front of the user: write the file, and say what did not convert, with counts. Never settle what the source leaves open: a tracked change stays pending, and a figure the source contradicts is not copied silently into something meant to be pasted.
Ask once for anything missing. Usually only the file is needed:
Send me the file (or its path). Anything else is optional:
- What you want next: just the Markdown, a critique, or a brief. Default: just the Markdown.
- For big workbooks: a row limit per sheet. Default: every row.
Run the script.
# Claude Code python3 "${CLAUDE_SKILL_DIR}/scripts/to_markdown.py" input.docx -o input.md # Other IDEs (from the skill folder) python3 scripts/to_markdown.py input.docx -o input.md-o -writes to stdout.--max-rows 200caps each sheet of an.xlsx. Images embedded in a.docxor.pptxare saved to<name>-images/beside the output and linked where they sat, with their alt text; to stdout there is nowhere to save them, so they are counted as dropped.Input What comes through .docxHeadings by style (Title, Heading 1–6, outline level), bulleted and numbered lists with nesting, tables, bold, italic, hyperlinks, embedded images; tracked changes as {++added++}and{--removed--}.pptxOne ## Slide N: titlesection per slide, bullets with levels, tables, pictures, speaker notes as a quote.xlsxOne table per sheet, shared strings, numbers as stored, dates as YYYY-MM-DD, cached formula values.htmlHeadings, lists, tables, links, code blocks, quotes; scripts, styles and nav menus dropped .csv/.tsvOne table, delimiter detected .jsonAn array of objects becomes a table; an object becomes a key/value table plus a table per array .eml/.msgSubject as the title; From, To, Cc and the sent time as a table; the plain-text body (the HTML body only when there is no text one); attachments listed by name and size, not converted. Outlook .msgis read directly, with nothing to install.txt/.mdPassed through .pdfThrough pdftotext. Tables from aligned columns (told apart by where each word sits on the page, so two columns set close together don't merge), lists from indentation, short standalone lines as###headings (guessed, and said so); a table that runs onto the next page is joined into one, without the header the PDF repeats; pages with side-by-side columns are read in column order with nothing inferred. Scanned pages are read by OCR whentesseractis installed. No imagesPDF without
pdftotext. The script stops with install steps (brew install poppleron macOS,sudo apt install poppler-utilson Debian/Ubuntu). Pass those on; don't try to read the PDF bytes yourself. A page with no text layer is a scan. The script reads it by OCR whentesseractis installed (brew install tesseract,sudo apt install tesseract-ocr), and otherwise stops with those steps. For a scan that isn't in English, pass--ocr-langwith tesseract's code (deu,fra,eng+fra). OCR misreads characters, so the reply says which pages were OCR'd and asks the user to check every number, name and date in them against the PDF.Old binary formats (
.doc,.ppt,.xls,.rtf,.pages,.key): the script refuses and names the format to save as. On macOS,textutil -convert docx file.dochandles.docand.rtf, though it writes no heading styles, so check the levels.Keep pending changes pending. A tracked insertion or deletion comes through in CriticMarkup,
{++added++}and{--removed--}, because nobody has accepted it yet. Say how many there are and that they are pending. When a comment or the request settles one ("use 48, as Kim's comment says"), make that one edit and say so; leave the rest marked.Don't copy a contradiction into a deliverable. When the source contradicts itself (a total that doesn't add up, a figure stated two ways), say so with both numbers. If the request is for something to paste or publish ("just the table"), leave the contradicted cell or row out, or mark it, and say which in one line. A Markdown copy for reading keeps it as stored, flagged.
Report what was dropped, every time. The script prints three kinds of line to stderr:
converted …(what was kept),dropped …(charts, comments, footnotes, formulas, headers and footers, and images when there was nowhere to save them), andnote: …(headings inferred from font size, merged cells, truncated sheets). Put them at the top of the reply in plain words: "The deck has 4 charts that are not in the Markdown; their numbers are missing from what I read."Then do the next step the user asked for. When a critique or brief depends on a chart or comment that was dropped, say so in that output too. Don't let it read as complete.
Non-interactive runs (subagent, CI, headless): convert with the defaults and prefix the
reply with the dropped list. If no file is given, or the PDF needs pdftotext and it is
missing, emit BLOCKED: need <the file | pdftotext on PATH> and stop.
Useful references in this skill
scripts/to_markdown.py: the converter (stdlib only;pdftotextoptional for PDF,tesseractfor scanned pages)examples/mixed-inputs.md: a Word brief, a deck, a workbook and a web page converted, with the real Markdown and stderr report
Quality bar
- Structure survives. A heading in the source is a heading in the Markdown, a list is a list, a table is a table. Not a wall of paragraphs.
- Losses are stated, with counts. "2 charts, 1 comment and 14 formulas are not in this", never silence.
- Nothing is added. The Markdown holds only what the file holds: no summaries, no invented headings, no filled-in empty cells.
- Speaker notes stay attached to their slide, because that is often where the real argument is.
- Numbers are copied as stored. No rounding, no currency symbols added; dates converted only when the cell is formatted as a date.
- Images come through as files. An embedded image is saved and linked where it sat, with its alt text, not reduced to a caption.
- Tracked changes stay pending. They are marked, counted and said to be unaccepted; only one the user or a comment settles is applied, and the reply says so.
- A contradiction isn't pasted silently. Both figures are named, and a deliverable meant for pasting leaves it out or marks it.
- Inferred structure is flagged. When headings come from font size instead of styles, the reply says to check the levels.
When to use this skill
- ✅ Someone sends a .docx, .pptx or .xlsx and the user wants it reviewed, summarised or rewritten
- ✅ Feeding a document into
doc-critiqueorbrief-intake - ✅ Pulling the text and tables out of a saved web page or a PDF report
- ✅ Turning a CSV or JSON export into a readable table
When NOT to use this skill
- ❌ Going the other way, Markdown to Word; use
md-to-docx - ❌ Markdown tables into a workbook; use
md-to-xlsx - ❌ Messy notes, a Slack thread or a transcript that are already text; use
brief-intakedirectly - ❌ A document that is already Markdown and needs reviewing; use
doc-critiquedirectly
Anti-patterns to avoid
- ❌ Summarising instead of converting. The user asked for the document; give them the document, then summarise if asked.
- ❌ Hiding the dropped list below the Markdown, or leaving it out because "it's only images". A chart is often the slide's whole point.
- ❌ Reading a PDF as raw bytes when
pdftotextis missing. Ask the user to install it or export the PDF to .docx. - ❌ Writing an unaccepted tracked change as the text. It reads as agreed when it isn't.
- ❌ Pasting a total you've just said is wrong into the table the user will publish.
- ❌ Treating inferred headings as fact. A bold, large line in an unstyled document might be a pull quote.
- ❌ Critiquing a deck from its Markdown without saying the charts and images were not seen.
- ❌ Showing the machinery. The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
- ❌ A bare
BLOCKEDline. Keep theBLOCKED: need <X>line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.