convert-to-md
Convert various file formats to Markdown using markitdown MCP, optimized for AI readability
Install with Tessl CLI
npx tessl i github:sc30gsw/claude-code-customes --skill convert-to-md65
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 provides a basic understanding of the skill's purpose but lacks critical elements for effective skill selection. It fails to include explicit trigger conditions and doesn't enumerate the specific file formats supported, making it difficult for Claude to confidently choose this skill over alternatives.
Suggestions
Add a 'Use when...' clause specifying trigger scenarios like 'Use when the user wants to convert documents to Markdown, mentions .docx, .pdf, .html to .md conversion, or needs AI-readable document output'
List specific supported input formats (e.g., 'Converts PDF, Word, HTML, Excel files to Markdown') to improve specificity and trigger term coverage
Include common user phrases like 'convert to markdown', 'make readable', or specific file extensions users might mention
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (file format conversion to Markdown) and mentions the tool (markitdown MCP), but doesn't list specific concrete actions like which formats are supported or what conversion capabilities exist. | 2 / 3 |
Completeness | Describes what it does (converts files to Markdown) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. | 1 / 3 |
Trigger Term Quality | Includes 'Markdown', 'file formats', and 'convert' which are relevant, but misses common variations users might say like specific format names (PDF, Word, HTML), 'transform', 'export', or file extensions. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'markitdown MCP' and 'AI readability' provides some distinction, but 'file formats' is generic and could overlap with other document processing or conversion skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is well-structured and concise, effectively documenting a CLI interface for markdown conversion. However, it falls short on actionability by not showing the actual MCP tool call syntax, and the workflow lacks validation/error handling steps critical for batch file operations.
Suggestions
Add an executable example showing the actual `mcp__markitdown__convert_to_markdown` call with parameters and expected response format
Add validation/error handling to the workflow: what to do when a file fails to convert, how to verify output quality, and how to handle partial batch failures
Show a concrete code example of what 'AI optimization' transformations look like (before/after) rather than just describing them
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, documenting only the CLI interface, options, and workflow without explaining what markdown is or how file conversion works conceptually. Every section serves a clear purpose. | 3 / 3 |
Actionability | Provides concrete CLI examples that are copy-paste ready, but the workflow step 3 references `mcp__markitdown__convert_to_markdown` without showing the actual MCP call syntax or parameters. The 'AI Optimization Features' section describes what happens but not how to implement it. | 2 / 3 |
Workflow Clarity | Steps are listed in sequence but lack validation checkpoints. No error handling guidance for failed conversions, no verification step to confirm output quality, and no feedback loop for handling partial failures in batch operations. | 2 / 3 |
Progressive Disclosure | For a skill of this size (~50 lines), the content is well-organized with clear sections (Arguments, Options, Examples, Workflow, AI Optimization). No unnecessary nesting or external references needed for this scope. | 3 / 3 |
Total | 10 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- 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.