markdown-tools

I took a look at your markdown-tools skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 80/100, solid B-grade territory. This skill covers a real gap in document-to-markdown conversion (especially with WSL path handling), which is genuinely useful. Your strongest area is Ease of Use (21/25)—the metadata and trigger coverage are strong. The weakest spot is Spec Compliance (11/15), mainly because you're missing trigger phrases in the description.

What's Working Well

• Metadata is thorough: Your description includes specific document types (PDFs, Word docs, PowerPoint, Confluence exports) and even mentions WSL path handling. That specificity helps activation.
• Progressive disclosure structure: SKILL.md gives a quick overview while conversion-examples.md handles 347 lines of reference material. That separation works.
• Practical problem-solving: WSL path conversion is a nice touch—it's addressing a real Windows developer pain point that generic tools miss.
• Examples are grounded: The command examples show real workflow patterns, not just syntax.

The Big One: Add Trigger Phrases to Description

Your description currently reads: "Converts documents to markdown (PDFs, Word docs, PowerPoint, Confluence exports)..." But it doesn't tell Claude when to invoke this skill.

Why it matters: Without explicit trigger phrases, the skill relies on fuzzy matching. A developer asking "convert my PDF to markdown" might not surface your skill at all.

The fix (in SKILL.md frontmatter):

description: "Converts documents to markdown (PDFs, Word docs, PowerPoint, Confluence exports) with Windows/WSL path support. Use when asked to 'convert document to markdown', 'markdown tools', 'extract text from PDF', or 'convert Word doc to markdown'."

This gives you a +2 point bump (description_quality: 2→4) and directly addresses your spec compliance gap.

Other Things Worth Fixing

1. Add a TOC to the reference file — conversion-examples.md is 347 lines without a table of contents. After the heading, add:

   ## Contents
   - [Basic Document Conversions](#basic)
   - [Windows/WSL Path Conversion](#wsl)
   

   This scores you another +2 points on Progressive Disclosure.

2. Spell out the cleanup step — Your "Step 4: Format Cleanup" says "markitdown output often needs manual fixes" but doesn't show patterns. Add specific examples:

   Look for ALL CAPS LINES → convert to # Heading
   Multiple blank lines → replace with single blank line
   

3. Add verification commands — After Quick Start examples, add: head -20 output.md # Verify converted content

4. Move scripts inline — Rather than listing extract_pdf_images.py at the bottom, reference it where it's actually used in workflows.

Quick Wins

• Highest impact: Add trigger phrases to description (+2 points)
• Next: Add TOC to reference file (+2 points)
• Easy wins: Clarify cleanup patterns (+2 points), add verification steps (+1 point)

These four changes would push you to 87/100 (A-territory) with minimal effort. The skill is fundamentally solid—it just needs better discoverability and clearer workflows.

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.