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.
74
66%
Does it follow best practices?
Impact
85%
3.40xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./scientific-skills/markitdown/SKILL.mdQuality
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 with real, executable Python and CLI commands covering a wide range of use cases. However, it is severely bloated with redundant examples, an irrelevant 'Scientific Schematics' section that appears injected from another skill, and explanatory text that doesn't respect Claude's existing knowledge. Trimming to ~30-40% of current length while keeping the Quick Start, Advanced Features, and key references would dramatically improve quality.
Suggestions
Remove the entire 'Visual Enhancement with Scientific Schematics' section - it's unrelated to file-to-markdown conversion and wastes significant tokens.
Consolidate the 6 'Common Use Cases' into 2-3 representative examples; the batch processing pattern appears multiple times with trivial variations.
Remove the 'Key Benefits' list, the supported formats table descriptions (just list format names), and explanatory prose like 'Markdown is token-efficient and well-understood by modern language models' - Claude already knows this.
Add a validation step after conversion (e.g., check result.text_content is non-empty, verify expected sections exist) to improve workflow clarity for batch operations.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. The 'Visual Enhancement with Scientific Schematics' section is entirely irrelevant to the core skill. Multiple use cases are near-duplicates (e.g., batch convert appears twice). Explains obvious concepts like what PDF is, why Markdown is token-efficient, and includes 'Key Benefits' marketing copy. The 'Optimize for Token Efficiency' section ironically wastes tokens explaining basic regex cleanup. | 1 / 3 |
Actionability | Provides fully executable, copy-paste ready Python code and CLI commands throughout. Installation commands, API usage, streaming, error handling, and batch processing are all concrete and complete with real import statements and method calls. | 3 / 3 |
Workflow Clarity | Steps for individual tasks are clear, but there's no overarching workflow with validation checkpoints. The batch processing examples lack verification that conversions succeeded beyond catching exceptions. No validation step to confirm output quality or completeness after conversion. | 2 / 3 |
Progressive Disclosure | References external files at the end (references/api_reference.md, scripts/batch_convert.py) which is good, but the main file is monolithic with too much inline content. The supported formats table, 6+ use cases, troubleshooting, and performance considerations could be split into separate reference files. The scientific schematics section adds significant noise. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
90%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
25e1c0f
- Reviewed
Table of Contents
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.