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.

3.40x

Quality

66%

Does it follow best practices?

Impact

85%

3.40x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./scientific-skills/markitdown/SKILL.md

Quality

Discovery

82%

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

This is a strong description with excellent specificity and trigger term coverage across a wide range of file formats. Its main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know precisely when to select this skill. The description clearly communicates what the skill does but relies on implicit triggers rather than explicit guidance.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to convert a file to Markdown, extract text from documents, transcribe audio, or process any supported file format into readable Markdown.'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions and formats: 'Convert files and office documents to Markdown' with explicit support for PDF, DOCX, PPTX, XLSX, images with OCR, audio with transcription, HTML, CSV, JSON, XML, ZIP, YouTube URLs, EPubs.	3 / 3
Completeness	Clearly answers 'what does this do' (convert files to Markdown with support for many formats), but lacks an explicit 'Use when...' clause or equivalent trigger guidance. The when is only implied by the list of supported formats.	2 / 3
Trigger Term Quality	Excellent coverage of natural terms users would say: PDF, DOCX, PPTX, XLSX, images, OCR, audio, transcription, HTML, CSV, JSON, XML, ZIP, YouTube, EPub, Markdown, convert. These are all terms users would naturally use when needing file conversion.	3 / 3
Distinctiveness Conflict Risk	The specific niche of converting diverse file formats to Markdown is quite distinct. The combination of 'convert to Markdown' plus the extensive format list makes it unlikely to conflict with other skills like general PDF processing or audio transcription tools.	3 / 3
	Total	11 / 12 Passed

Implementation

50%

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

The skill provides excellent actionable code examples covering CLI, Python API, and advanced features like AI-enhanced descriptions, but is severely bloated with redundant use cases, irrelevant sections (scientific schematics), and explanations of concepts Claude already understands. The content would benefit from being cut by 50-60% and having its many similar examples consolidated, while the referenced supporting files don't actually exist in the bundle.

Suggestions

Remove the entire 'Visual Enhancement with Scientific Schematics' section — it's unrelated to file-to-markdown conversion and belongs in a separate skill or integration guide.

Consolidate the 6 'Common Use Cases' into 1-2 examples maximum; the pattern is identical (call md.convert(), write output) and Claude can generalize from a single example.

Remove the 'Key Benefits' list, 'Performance Considerations' prose, and explanatory text like 'Markdown is token-efficient and well-understood by modern language models' — Claude already knows these things.

Either provide the referenced bundle files (references/api_reference.md, scripts/batch_convert.py, etc.) or remove those references to avoid broken navigation.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~300+ lines. It includes unnecessary sections like 'Visual Enhancement with Scientific Schematics' (irrelevant to the core skill), explains obvious concepts ('Markdown is token-efficient and well-understood by modern language models'), repeats similar code patterns across 6+ use cases that are trivially different, and includes a 'Key Benefits' list that tells Claude things it already knows. The 'Optimize for Token Efficiency' section is ironic given the skill's own verbosity.	1 / 3
Actionability	The skill provides fully executable, copy-paste ready Python code and CLI commands throughout. Installation commands, API usage, streaming, batch processing, error handling, and Docker usage are all concrete and complete with real code examples.	3 / 3
Workflow Clarity	Individual operations are clear, but there's no cohesive workflow with validation checkpoints. The batch processing examples lack verification steps (e.g., checking if conversion produced valid output). The 'Best Practices' section lists tips but doesn't sequence them into a validated workflow. Error handling is shown but not integrated into a feedback loop.	2 / 3
Progressive Disclosure	The skill references external files (references/api_reference.md, references/file_formats.md, scripts/batch_convert.py) in the 'Next Steps' section, but no bundle files are provided to support these references. The main body contains extensive inline content (6 use cases, troubleshooting, performance notes) that could be split into separate files. The scientific schematics section is a large tangential block that should be elsewhere.	2 / 3
	Total	8 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning

	Total	10 / 11 Passed

Repository: K-Dense-AI/claude-scientific-skills
Commit: cbcae7b

Reviewed: 1 day 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.