convert-to-md

Convert various file formats to Markdown using markitdown MCP, optimized for AI readability

Quality

33%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/convert-to-md/SKILL.md

Quality

Discovery

32%

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 identifies the core purpose (converting files to Markdown via markitdown MCP) but is too vague about supported formats and lacks explicit trigger guidance. It would benefit significantly from listing specific supported file types and adding a 'Use when...' clause to help Claude select it appropriately.

Suggestions

Add a 'Use when...' clause specifying trigger scenarios, e.g., 'Use when the user wants to convert PDF, DOCX, HTML, PPTX, or other documents to Markdown format.'

Replace 'various file formats' with specific supported formats (e.g., PDF, Word, HTML, Excel, PowerPoint) to improve both specificity and trigger term quality.

Include natural user terms like 'convert to markdown', '.md', and specific file extensions (.pdf, .docx, .html) that users would mention.

Dimension	Reasoning	Score
Specificity	Names the domain (file format conversion to Markdown) and mentions the tool (markitdown MCP), but doesn't list specific actions or supported formats (e.g., PDF, DOCX, HTML). 'Various file formats' is vague.	2 / 3
Completeness	Describes what it does (convert file formats to Markdown) but has no explicit 'Use when...' clause or equivalent trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also vague, so this scores a 1.	1 / 3
Trigger Term Quality	Includes 'Markdown', 'convert', and 'file formats' which are somewhat relevant, but misses natural user terms like specific format names (PDF, DOCX, HTML), 'convert to md', or '.md'. 'AI readability' is not a typical user trigger term.	2 / 3
Distinctiveness Conflict Risk	Mentioning 'markitdown MCP' and 'Markdown' conversion gives it some distinctiveness, but 'various file formats' is broad enough to potentially overlap with other file processing or conversion skills.	2 / 3
	Total	7 / 12 Passed

Implementation

35%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill reads more like a CLI help page than an actionable skill for Claude. It defines an interface with arguments and options but provides no concrete implementation code, no example of the actual MCP tool call with its parameters, and no error handling or validation steps. The content describes what should happen rather than showing Claude how to do it.

Suggestions

Add a concrete, executable code example showing how to call `mcp__markitdown__convert_to_markdown` with actual parameters and handle its response.

Include error handling and validation steps in the workflow—e.g., what to do when a file fails to convert, how to verify the output is valid markdown.

Replace the abstract 'AI Optimization Features' bullet points with concrete examples showing input/output transformations (e.g., before and after AI optimization).

Show the actual MCP tool call signature and expected response format so Claude knows exactly what parameters to pass and what to expect back.

Dimension	Reasoning	Score
Conciseness	The content is reasonably efficient but includes some unnecessary detail. The options section is extensive for what appears to be a wrapper around a single MCP tool call. The 'AI Optimization Features' section describes features at a high level without adding much actionable value.	2 / 3
Actionability	The skill lacks executable code or concrete implementation details. It describes a CLI-like interface but never shows how to actually implement any of it—no code for parsing arguments, no concrete example of calling `mcp__markitdown__convert_to_markdown`, no example of what AI optimization actually does in practice. The workflow is descriptive rather than instructive.	1 / 3
Workflow Clarity	The workflow has a clear sequence of steps, but lacks validation checkpoints. There's no error handling guidance, no validation of conversion output, and no feedback loop for failed conversions. The 'Report summary' step mentions failed counts but doesn't explain how to handle failures.	2 / 3
Progressive Disclosure	The content is organized into logical sections (Arguments, Options, Examples, Workflow, AI Optimization), which is decent structure. However, it's somewhat monolithic—the options list is long and could benefit from being separated or condensed, and there are no references to external files for advanced usage or detailed API documentation.	2 / 3
	Total	7 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: sc30gsw/claude-code-customes
Commit: 7aff694

Reviewed: 7 days 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.