markdown-converter

Convert binary documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, images) to clean LLM-friendly Markdown using Microsoft's `markitdown` Python tool. Use when a user attaches a binary file and you need to read its contents.

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A tight, self-contained skill body that gives copy-runnable commands, a clear two-step workflow for the main use case, and genuinely useful troubleshooting and routing guidance. The only deductions are minor: a redundant sentence about what to do with the output and an awkward repeated path expression.

Suggestions

Replace the repeated "/workspace/$(basename "$PWD")/" construct with a simple placeholder like `<path/to/file>` — it reads more clearly and saves tokens (addresses conciseness and actionability).

Delete "Then summarize, answer questions about it, or feed sections back to the user" — Claude already knows what to do with converted content (addresses conciseness).

Add one short example of invoking markitdown on an image or scanned PDF alongside the note about its OCR limits, since images are advertised as a supported input (addresses actionability).

Dimension	Reasoning	Score
Conciseness	The body is lean — executable command examples, a compact flags table, and pointed troubleshooting with no explanations of concepts Claude already knows. It falls short of anchor 5 only by minor trims: "Then summarize, answer questions about it, or feed sections back to the user" states the obvious, and the repeated "/workspace/$(basename "$PWD")/" path construct spends tokens without adding clarity.	4 / 5
Actionability	Concrete, runnable commands throughout ("markitdown /workspace/.../uploads/report.pdf > /tmp/report.md", piped usage, flag table) match anchor 4's mostly-executable guidance. It misses anchor 5 because the "$(basename "$PWD")" path wrapper is confusing to copy verbatim and there is no invocation example for the advertised image/OCR or audio/ZIP cases.	4 / 5
Workflow Clarity	As a simple single-purpose skill, the core action is unambiguous and "Reading a user-attached file" lays out a clean numbered two-step sequence (convert, then read). The Troubleshooting section adds feedback for the known failure modes (OCR-heavy PDFs return garbage; XLSX charts need officecli) with concrete recovery paths, and no destructive or batch operations require validation checkpoints.	5 / 5
Progressive Disclosure	The self-contained ~60-line body is organized into well-labeled sections (formats, basic usage, attached files, flags, when not to use, troubleshooting) with no nested references and no inline content that belongs in separate bundle files. No bundle files exist or are needed, and the pointers to other skills (pdf, officecli) are routing hints rather than buried detail, fitting the simple-skill case for anchor 5.	5 / 5
	Total	18 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description that explicitly states both what the skill does and when to use it, with a concrete trigger scenario (user attaches a binary file). Keyword coverage is good though it misses natural synonyms and dotted file extensions, and it describes one conversion action rather than multiple distinct capabilities.

Dimension	Reasoning	Score
Specificity	"Convert binary documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, images) to clean LLM-friendly Markdown using Microsoft's `markitdown`" names a concrete action, tool, and comprehensive input formats, but describes only a single action rather than several specific operations. It exceeds anchor 3 (1-2 concrete actions) thanks to full format coverage but does not list multiple distinct actions required for anchor 5.	4 / 5
Completeness	It explicitly answers both parts: "what" (convert binary documents to LLM-friendly Markdown using markitdown) and "when" ("Use when a user attaches a binary file and you need to read its contents"). The 'when' clause is concrete and explicit, matching the anchor 5 example rather than the weaker 'when' of anchor 4.	5 / 5
Trigger Term Quality	Keywords like "PDF, DOCX, XLSX, PPTX, HTML, EPUB, images", "binary file", "Markdown", and "attaches a binary file" give good natural coverage, but common synonyms ("Word document", "spreadsheet", "presentation", "slides") and dotted extensions (".pdf", ".docx") are missing. This matches anchor 4 (good coverage, a few natural terms missing) rather than anchor 5's comprehensive synonym/extension list.	4 / 5
Distinctiveness Conflict Risk	The named tool, enumerated binary formats, and the specific trigger of reading a user-attached binary file carve out a clear niche with minimal conflict risk; only the broadest overlap with generic pdf/office skills exists. This fits anchor 5 (clear niche, distinct triggers) and is clearly above anchor 4's minor-overlap framing.	5 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: Team-Commonly/commonly
Path: backend/commonly-bundled-skills/markdown-converter/SKILL.md
Commit: 5bd4f1a

Reviewed: 7 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.