markitdown

Convert files and office documents to Markdown. Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription), HTML, CSV, JSON, XML, ZIP, YouTube URLs, EPubs and more.

Quality

65%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./bundled/skills/markitdown/SKILL.md

Quality

Content

65%

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

The body is highly actionable with complete, executable code and commands, but it is verbose and monolithic: a tangential schematics section, repeated boilerplate, and inline content that belongs in the existing reference/script files. A broken script reference and missing batch-validation checkpoints hold back two dimensions.

Suggestions

Move the use-case, integration, and best-practice sections into the existing references/scripts bundle files so SKILL.md stays a lean overview with well-signalled one-level-deep links.

Remove the 'Visual Enhancement with Scientific Schematics' section and the broken scripts/generate_schematic.py reference, or move them to a separate optional file; this is off-topic for a file-conversion skill.

Add explicit output validation/verification to the batch and multi-document workflows (e.g., confirm each output file is non-empty and well-formed) to lift workflow clarity.

Dimension	Reasoning	Score
Conciseness	Mostly actionable but padded: a large tangential 'Visual Enhancement with Scientific Schematics' section, repeated `from markitdown import MarkItDown; md = MarkItDown()` boilerplate across many examples, and statements Claude already knows ('Markdown is token-efficient and well-understood by modern language models').	2 / 3
Actionability	Provides fully executable, copy-paste-ready guidance throughout — pip install commands, the markitdown CLI, and complete Python API snippets including streaming, plugins, and AI-enhanced conversion.	3 / 3
Workflow Clarity	Steps are present and a batch example includes try/except error handling, but batch/multi-document operations lack explicit validation or verification checkpoints, which caps workflow clarity at 2 per the rubric's batch-operation rule.	2 / 3
Progressive Disclosure	Real bundle files exist and are pointed to in 'Next Steps', but most material (six inline use cases, integration workflows, best practices) should be split out, references are signposted only at the very end, and the body references a non-existent scripts/generate_schematic.py.	2 / 3
	Total	9 / 12 Passed

Description

65%

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

The description clearly communicates the conversion capability and lists an excellent range of natural trigger terms, but it omits any explicit 'when to use' guidance, which caps both completeness and distinctiveness. Adding a 'Use when...' clause would lift it to a strong description.

Suggestions

Add an explicit 'Use when ...' trigger clause (e.g., 'Use when converting PDFs, Office documents, images, or audio to Markdown') to satisfy the completeness requirement.

Reframe capabilities as multiple concrete actions rather than a single 'Convert' verb followed by a format list to reach the specificity score-3 anchor.

Tie distinctiveness to specific trigger phrases so it is clearly separable from generic document-processing skills.

Dimension	Reasoning	Score
Specificity	Names the domain ('Convert files and office documents to Markdown') and several concrete capabilities (OCR, transcription), but the framing is a single primary verb with a format list rather than multiple distinct actions as in the score-3 anchor.	2 / 3
Completeness	Clearly states what the skill does, but there is no 'Use when...' clause or equivalent explicit trigger guidance for when Claude should invoke it, capping completeness at 2 per the judging guidelines.	2 / 3
Trigger Term Quality	Covers many natural terms users would actually say — 'files and office documents', 'PDF, DOCX, PPTX, XLSX, images, audio, HTML, CSV, JSON, XML, ZIP, YouTube URLs, EPubs' — giving strong trigger coverage.	3 / 3
Distinctiveness Conflict Risk	The file-to-Markdown niche is fairly specific, but without explicit use-when triggers it could still overlap with generic document-processing skills, matching the 'somewhat specific but could overlap' anchor.	2 / 3
	Total	9 / 12 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	14 / 16 Passed

Repository: foryourhealth111-pixel/Vibe-Skills
Path: bundled/skills/markitdown/SKILL.md
Commit: f627ab5

Reviewed: about 7 hours 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.