CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

64

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/markdown-converter/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

An excellent, execution-first reference for a simple tool-wrapping skill: complete copy-paste commands, a full options list, and practical notes (caching, charset fallback, Azure fallback for poor PDFs) with no filler. The only notable weaknesses are the partial redundancy between the Basic Usage and Examples sections and a description-level gap handled by the other judge.

Suggestions

Consolidate the Examples section — the docx/xlsx/pptx examples repeat the -o and redirect patterns already demonstrated in Basic Usage; keep only the stdin-hint and Azure Document Intelligence examples, which add new information.

If the skill grows (e.g., plugin usage or per-format caveats), move that detail into a references/ file to keep SKILL.md a lean overview.

DimensionReasoningScore

Conciseness

The body is lean — commands, an options table, and short notes with zero concept explanations Claude already knows — matching 'Efficient; minor instances of over-explanation that could be trimmed'. The Examples section largely duplicates patterns already shown in Basic Usage (e.g. 'markitdown report.docx -o report.md' repeats the -o and redirect forms), which keeps it from anchor 5's 'every token earns its place'.

4 / 5

Actionability

Every command is fully executable and copy-paste ready — 'uvx --from "markitdown[all]" markitdown input.pdf -o output.md' including stdin usage, extension/MIME/charset hints, and the Azure Document Intelligence variant — covering the common cases, which matches the top anchor exactly. Not anchor 4 because there are no gaps: even the no-install story is handled via uvx.

5 / 5

Workflow Clarity

This is a simple, single-purpose skill where the single action (run one markitdown command) is unambiguous, and the simple-skill exception applies since no multi-step process is needed. It even includes a fallback loop for the main failure mode ('For complex PDFs with poor extraction, use -d with Azure Document Intelligence'), and the operation is non-destructive so no validation cap applies.

5 / 5

Progressive Disclosure

The body (~63 lines) is well-organized into clearly labeled sections with all content appropriately inlined for a single-command tool, matching 'Good structure; most content is appropriately placed... minor organization gaps'. It falls short of anchor 5 because it slightly exceeds the under-50-line simple-skill threshold and carries a minor redundancy: the Examples section repeats Basic Usage patterns that could be consolidated.

4 / 5

Total

18

/

20

Passed

Description

61%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 terse, information-dense description that clearly names the domain and input formats, but it reads as a feature inventory rather than a trigger-optimized description. It is missing the explicit 'when to use' clause, which caps completeness, and it omits common natural synonyms and file extensions users would say (Word, .docx, Excel, .pptx, transcription).

Suggestions

Add an explicit trigger clause, e.g. 'Use when converting PDFs, Word/Excel/PowerPoint documents, HTML pages, images, audio, ZIP archives, or YouTube videos to Markdown.'

Include natural synonyms and file extensions users actually say — Word/.docx, Excel/.xlsx, PowerPoint/.pptx, 'transcribe audio', 'extract text' — alongside the current format nouns.

State the concrete actions more fully rather than one verb plus a noun list (e.g., 'Converts documents to Markdown, extracts text via OCR, transcribes audio').

DimensionReasoningScore

Specificity

The description states one concrete action ("Markdown conversion") plus an explicitly named second capability ("OCR"), matching the anchor 'Names domain and 1-2 concrete actions, but not comprehensive'. The long format list ("PDF, Office, HTML, data, OCR, audio, ZIP, YouTube") covers input objects broadly but adds no additional action verbs, so it does not reach anchor 4's 'several specific actions'.

3 / 5

Completeness

The 'what' is clear ('Markdown conversion' with an explicit format inventory), but there is no 'Use when...' clause or equivalent trigger guidance anywhere in the description, so per the judging guidelines completeness is capped at 3 ('Has a clear what but when is missing or only weakly implied'). Not anchor 4 because that requires both what and when to be present.

3 / 5

Trigger Term Quality

Includes good natural keywords users would actually say — "PDF", "HTML", "ZIP", "YouTube", "audio", "OCR", "data" — matching 'Good keyword coverage; a few natural terms missing'. It misses anchor 5 because natural synonyms and file extensions are absent ("Word"/".docx", "Excel"/".xlsx", "PowerPoint"/".pptx", "transcription", "convert to Markdown").

4 / 5

Distinctiveness Conflict Risk

'Markdown conversion' with a specific format list carves out a mostly distinct niche, matching 'Mostly distinct; minor overlap risk with closely related skills' — the OCR and audio terms could overlap with dedicated OCR/transcription skills. Not anchor 5 because it lacks the explicit 'Use when' trigger phrasing that further isolates the niche.

4 / 5

Total

14

/

20

Passed

Validation

100%

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

steipete/agent-scripts

Path

skills/markdown-converter/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.