markdown-converter

Convert binary documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, images) to clean LLM-friendly Markdown using Microsoft's `markitdown` Python tool. Use when a user attaches a binary file and you need to read its contents.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

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

A tight, actionable skill body with executable examples, a useful flags table, and thoughtful 'when NOT to use' and troubleshooting sections. The main improvement is adding a quick validation step to the read-attached-file workflow.

Suggestions

Add a brief validation checkpoint in the 'Reading a user-attached file' workflow (e.g., check the output .md is non-empty before summarizing) to lift workflow clarity to a 5.

Reconcile the supported-formats list between the description and the body so they agree (the body adds CSV, JSON, audio transcripts, and ZIP not mentioned in the description), avoiding drift.

Dimension	Reasoning	Score
Conciseness	Largely lean with executable commands and a compact flags table, but the intro paragraph mildly restates what the format list already shows and the supported-formats list is duplicated between the description and body with slight discrepancies, leaving minor trimming opportunity.	4 / 5
Actionability	Provides copy-paste-ready `markitdown` commands covering the common cases (stdout, save-to-file, pipe, reading an attached file) plus a concrete flags table, all directly executable.	5 / 5
Workflow Clarity	The 'Reading a user-attached file' section gives a clear two-step sequence (convert, then read) and the single action is unambiguous, but there is no explicit validation checkpoint confirming the conversion succeeded, leaving a minor validation gap.	4 / 5
Progressive Disclosure	A compact, well-organized single-file skill with clear section headers and no need for external references; per the under-50-line simple-skill guidance, well-organized sections alone justify a top score.	5 / 5
	Total	18 / 20 Passed

Description

83%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 strong description that explicitly states the action, tool, and a concrete use-when trigger, with broad file-format coverage. Minor gains are possible by adding everyday synonyms (document, spreadsheet, presentation) for stronger trigger matching.

Suggestions

Add natural-language synonyms like 'documents, spreadsheets, presentations' alongside the file extensions to improve trigger matching for users who say those words.

Consider tightening 'a user attaches a binary file and you need to read its contents' to also mention converting files already on disk, broadening the trigger beyond just attached files.

Dimension	Reasoning	Score
Specificity	Names one concrete action ('Convert binary documents ... to clean LLM-friendly Markdown') plus the specific tool and output format, with several input formats enumerated; falls just below a 5 because it is a single action rather than multiple distinct actions.	4 / 5
Completeness	Clearly answers 'what' (convert binary docs to Markdown via markitdown) and explicitly answers 'when' with a concrete trigger phrase ('Use when a user attaches a binary file and you need to read its contents').	5 / 5
Trigger Term Quality	Strong keyword coverage including natural file extensions (PDF, DOCX, XLSX, PPTX, HTML, EPUB) and the natural phrase 'a user attaches a binary file', though common synonyms like 'document', 'spreadsheet', or 'presentation' are absent.	4 / 5
Distinctiveness Conflict Risk	Has a clear niche (binary→Markdown conversion via a named tool) with minimal overlap risk; the broad term 'binary file' leaves minor overlap with general file-reading skills, keeping it just below a 5.	4 / 5
	Total	17 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: Team-Commonly/commonly
Path: backend/commonly-bundled-skills/markdown-converter/SKILL.md
Commit: e701dba

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.