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

62%

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 ./.claude/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 skill is highly actionable with executable code throughout, but it is padded with redundant examples, off-topic schematic guidance, and explanations Claude already knows, while batch workflows lack validation checkpoints. Tightening the body and pushing detail into the existing references would improve conciseness and progressive disclosure.

Suggestions

Remove the unrelated "Visual Enhancement with Scientific Schematics" section or relocate it to a separate reference, since it is not part of file-to-Markdown conversion.

De-duplicate the repeated basic MarkItDown() Python examples and move advanced AI/Azure examples into references/api_reference.md to reduce inline bulk.

Add a validate/retry checkpoint to the batch and directory-conversion examples (e.g. confirm output file is non-empty before marking success).

Delete explanatory padding Claude already knows (e.g. what Markdown is, why it is token-efficient).

Dimension	Reasoning	Score
Conciseness	The body is very long with redundant repeated Python API examples and explanations Claude already knows ("Markdown is token-efficient and well-understood by modern language models"), plus an off-topic scientific-schematics section that bloats the document, but the core content is still genuinely useful and executable.	2 / 3
Actionability	It provides fully executable install commands, CLI usage, and copy-paste-ready Python examples across many formats with specific options and flags.	3 / 3
Workflow Clarity	Quick start sequencing is clear (install -> CLI -> Python API), but batch operations like the directory/batch examples have no validation or verify-retry checkpoints, capping workflow clarity at 2 for batch contexts.	2 / 3
Progressive Disclosure	A Next Steps section signals real one-level-deep bundle files (references/api_reference.md, references/file_formats.md, scripts/batch_convert.py, scripts/convert_with_ai.py, assets/example_usage.md), but extensive API detail and examples remain inline rather than split into those references, and the schematic material is out of place.	2 / 3
	Total	9 / 12 Passed

Description

60%

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 is specific and format-rich but lacks an explicit "when to use" trigger clause and uses technical extension tokens over natural user phrasings. Adding a "Use when..." clause with everyday terms would raise completeness and trigger quality.

Suggestions

Append an explicit trigger clause, e.g. "Use when converting PDFs, Word, PowerPoint, Excel, images, or audio into Markdown for LLM processing."

Replace some extension-only tokens with natural terms users would say ("Word documents" alongside DOCX, "Excel" alongside XLSX).

Trim the trailing "and more" to keep the claim concrete and reduce vague over-claim.

Dimension	Reasoning	Score
Specificity	"Convert files and office documents to Markdown" plus an enumerated list of 13+ formats with concrete sub-actions ("with OCR", "with transcription") names multiple specific actions rather than vague language.	3 / 3
Completeness	It clearly answers "what" (convert files/documents to Markdown with format coverage) but has no "Use when..." clause or equivalent explicit trigger, which caps completeness at 2 per the guidelines.	2 / 3
Trigger Term Quality	It includes relevant terms (PDF, DOCX, PPTX, images, audio, YouTube) but leans on technical extension tokens (XLSX, PPTX) and omits common natural phrasings users would say ("Word documents", "PowerPoint", "Excel"), so coverage is only partial.	2 / 3
Distinctiveness Conflict Risk	The file-to-Markdown conversion niche is fairly distinct, but the generic opener "Convert files and office documents" and the absence of explicit triggers mean it could still overlap with general document-handling skills.	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_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: K-Dense-AI/claude-scientific-writer
Path: .claude/skills/markitdown/SKILL.md
Commit: 4717803

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