markitdown

Convert files and Office documents into clean Markdown when you need LLM-friendly, token-efficient text (e.g., for summarization, search, RAG ingestion, or dataset preparation).

Quality

68%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./scientific-skills/Other/markitdown/SKILL.md

Quality

Content

65%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.

The body is actionable and well-organized with executable examples for install, CLI, batch, stream, and AI-enhanced conversion. It loses points for duplicated material between Key Features and Implementation Details, a batch workflow with no validation checkpoint, and orphaned bundle files that the body never references.

Suggestions

Link the existing bundle files from the body — e.g. point detailed format support to references/file_formats.md and API details to references/api_reference.md — instead of inlining that material in Implementation Details.

Add a verification step to the batch-conversion example (e.g. checking result.text_content is non-empty or reporting failures) so the batch workflow has an explicit validation checkpoint.

De-duplicate Key Features and Implementation Details so OCR, AI image descriptions, and plugins are documented once rather than restated.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with clean headers and code blocks, but 'Key Features' and 'Implementation Details' restate the same OCR, AI-description, and plugin material, and the long supported-format list appears redundantly.	3 / 5
Actionability	It provides multiple fully executable, copy-paste-ready examples (pip install, markitdown CLI, a batch Python loop, stream conversion, and an AI-enhanced OpenAI-client example) covering the common cases.	5 / 5
Workflow Clarity	The single convert-to-text action is coherent, but the batch example iterates files with no validation or verification of outputs, and the rubric caps batch operations lacking validation at 3.	3 / 5
Progressive Disclosure	Section structure is good, but the bundle files (references/api_reference.md, references/file_formats.md, scripts/*.py, assets/example_usage.md) are never linked from the body, and API/format detail that belongs in those files is inlined rather than signaled.	3 / 5
	Total	14 / 20 Passed

Description

71%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.

The description cleanly answers both what the skill does and when to use it, with concrete use-case triggers and a distinct LLM-pipeline niche. Its main weakness is keyword breadth — it leans on abstract use-case terms while omitting the everyday file extensions and verb forms a user is most likely to say.

Dimension	Reasoning	Score
Specificity	Names the domain (files and Office documents to Markdown) and one concrete action (convert), but does not enumerate multiple specific actions like extract/fill/merge, so it is not comprehensive.	3 / 5
Completeness	It explicitly states what it does ('Convert files and Office documents into clean Markdown') and when to use it ('when you need LLM-friendly, token-efficient text (e.g., for summarization, search, RAG ingestion, or dataset preparation)'), answering both with concrete trigger phrases.	5 / 5
Trigger Term Quality	Relevant use-case keywords appear (summarization, search, RAG ingestion, dataset preparation), but common natural variations and file extensions users say (.pdf, .docx, 'turn into markdown') are missing.	3 / 5
Distinctiveness Conflict Risk	It targets a clear niche (Markdown conversion for LLM pipelines) with distinct triggers, with only minor overlap risk against closely related document-extraction skills; not maximally narrow, so not a 5.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: aipoch/medical-research-skills
Path: scientific-skills/Other/markitdown/SKILL.md
Commit: f5ef65b

Reviewed: ~18 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.