CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

53%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 delivers genuinely executable, copy-paste-ready guidance for the common conversion cases with clean section structure and no conceptual over-explanation. Its weaknesses are the orphaned bundle (references/, scripts/, and assets/ files are never mentioned, so progressive disclosure breaks down), a batch example with no validation of conversion results, and feature facts repeated across up to three sections.

Suggestions

Link the bundle files from SKILL.md (e.g., "**API reference**: See [references/api_reference.md](references/api_reference.md)", "**Format support**: See [references/file_formats.md](references/file_formats.md)", "**Batch/AI scripts**: See scripts/") and trim the inlined examples and implementation details that duplicate them.

Add validation to the batch and stream examples before writing outputs (check result.text_content is non-empty, wrap the loop in try/except and report failures) to clear the batch-operation workflow cap.

Consolidate the OCR, AI-image-description, and plugin facts that currently repeat across "When to Use", "Key Features", and "Implementation Details" into a single section.

DimensionReasoningScore

Conciseness

The body is mostly efficient and library-specific (no padding about what a PDF is or how libraries work), but the same facts are repeated three times across sections: OCR appears in "When to Use", "Key Features", and "Implementation Details"; AI image descriptions and plugins likewise appear in both "Key Features" and "Implementation Details". This matches anchor 3's "mostly efficient but... could be tightened" rather than anchor 2, since there is no explanation of concepts Claude already knows.

3 / 5

Actionability

The install ("pip install 'markitdown[all]'"), CLI ("markitdown document.pdf -o output.md"), and Python examples (multi-file loop, convert_stream, OpenAI-compatible client) are complete and copy-paste executable, matching anchor 4. It falls short of anchor 5 because OCR, Azure Document Intelligence ("When configured with a Document Intelligence endpoint..."), and plugins ("--list-plugins", "--use-plugins") are described with no executable example, leaving minor gaps.

4 / 5

Workflow Clarity

The core action is unambiguous (install, then convert), but the batch example ("for path in files: ... out.write_text(result.text_content...)" and the stream example) writes outputs with no validation — no check that result.text_content is non-empty, no per-file failure handling. Per the guidelines, missing validation in batch operations caps workflow clarity at 3, which overrides the simple-skill exception; it is not a 2 because the sequences that are present are clear and complete.

3 / 5

Progressive Disclosure

The bundle contains references/api_reference.md, references/file_formats.md, three scripts, and assets/example_usage.md, yet the body never links to any of them — zero references, not even buried ones. Meanwhile ~90 lines of usage examples and API details are inlined that duplicate assets/example_usage.md and references/api_reference.md, matching anchor 2's "content that clearly belongs in separate files is inlined". It is not anchor 3 because that anchor requires references to be present (even if unclearly signaled); here they are entirely absent, and the scripts are undiscoverable.

2 / 5

Total

12

/

20

Passed

Description

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

A serviceable description with a clear what and an explicit when-clause anchored to LLM use cases, but it is thin on trigger terms: no file-format keywords (PDF, .docx, PPTX) that users would naturally say, only one concrete action, and a second-person "when you need" construction that the guidelines penalize. It sits noticeably above the vague bad examples but clearly below the multi-action, format-anchored good examples.

Suggestions

Rewrite in third person to remove the second-person clause (e.g., "Converts files and Office documents... Use when the user wants..."), which is currently costing a specificity point under the judging guidelines.

Add a 'Use when...' clause with concrete format trigger terms users actually say: PDF, .docx, .pptx, spreadsheets, slide decks, audio/YouTube transcripts, scanned-document OCR.

List the concrete capabilities (extract tables and structured content from spreadsheets, OCR scanned documents, transcribe audio, pull YouTube transcripts) instead of the single generic "convert" action.

DimensionReasoningScore

Specificity

The description names the domain and a single concrete action ("Convert files and Office documents into clean Markdown"), matching anchor 3, but it is penalized one point per the judging guidelines because "when you need LLM-friendly, token-efficient text" uses second person voice ("you") rather than third person. It is not anchor 4 because only one action is listed, with no per-capability actions (no table extraction, OCR, or transcription mentioned).

2 / 5

Completeness

Both what ("Convert files and Office documents into clean Markdown") and when ("when you need LLM-friendly, token-efficient text (e.g., for summarization, search, RAG ingestion, or dataset preparation)") are explicitly present, so it clears the cap. It is not a 5 because the when-clause is goal-based rather than the concrete user-mention triggers of the anchor 5 example ("when the user mentions PDFs, forms, or document extraction").

4 / 5

Trigger Term Quality

Phrases like "clean Markdown", "summarization", "search", "RAG ingestion", "dataset preparation" give some relevant keywords, but every format-level natural trigger is missing — no "PDF", ".docx", "PPTX", "Word", "Excel", or "PowerPoint", which are what users would most naturally say. This matches anchor 3 ("some relevant keywords but missing common variations or synonyms") and falls short of anchor 4's good keyword coverage.

3 / 5

Distinctiveness Conflict Risk

"Convert files and Office documents into clean Markdown" with the LLM-pipeline framing (RAG ingestion, token-efficient text) carves a clear niche with minimal conflict risk, matching anchor 4's "mostly distinct; minor overlap risk with closely related skills". It is not a 5 because "files" is broad and the description omits the audio/YouTube/OCR capabilities that would sharpen its distinct triggers.

4 / 5

Total

13

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

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

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.