Feedback on your scientific-pkg-markitdown skill

[RichardHightower]

I took a look at your scientific-pkg-markitdown skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 58/100, which lands in F territory. This is based on Anthropic's best practices for skill design. Your strongest area is Ease of Use (19/25) – the metadata and trigger terms are solid – but Progressive Disclosure Architecture (14/30) and Utility (11/20) are dragging things down. The good news? There are some concrete, high-impact fixes that'll move the needle significantly.

What's Working Well

• Trigger terms are strong: Your "When to Use" section nails real use cases (document conversion, OCR extraction, transcription) that'll help people find this skill at the right moment
• Format coverage is comprehensive: The list of supported formats (PDF, DOCX, PPTX, audio, video) shows you've thought about what MarkItDown actually does
• Clear naming and description: "Convert documents to Markdown" is straightforward, and your frontmatter YAML is valid with all required fields

The Big One: Ghost Reference Files

Here's the problem: your skill references 6 files in a references/ directory that don't actually exist (document_conversion.md, media_processing.md, etc.). Same issue with scripts/batch_convert.py. This breaks the entire layered architecture and tanks your PDA score.

The fix: Either create these files with actual content (which would push you +8 points easily), or remove the references entirely. If you go the creation route, these would be solid additions:

• references/document_conversion.md – API usage patterns, format matrix
• references/batch_processing.md – Example script for bulk conversions
• references/troubleshooting.md – Common errors and solutions

This alone could bump you from 14/30 to 22/30 on PDA.

Other Things Worth Fixing

1. No table of contents – At 242 lines, readers need a TOC after the frontmatter. Just a simple markdown list linking to each section (## Contents → - [Overview](#overview) etc.) adds navigability.

2. Missing error handling guidance – You only show happy-path examples. Add a Troubleshooting section with try/except patterns, unsupported format handling, and common failure scenarios. This pushes Utility from 11/20 to 14/20.

3. Voice inconsistency – One line says "Use this skill when users request" which mixes second-person with third. Keep it imperative: "Activation triggers: document conversion requests, OCR extraction..."

4. Name mismatch – Your skill is named markitdown in frontmatter but lives in scientific-pkg-markitdown/. Pick one and standardize it across the directory and SKILL.md.

Quick Wins (Do These First)

• Remove or create the 6 missing reference files (+8 points)
• Add a TOC section (+2 points)
• Create a basic Troubleshooting section (+3 points)
• Fix the name/directory mismatch (+2 points)

That's +15 points for maybe 30 minutes of work, pushing you from 58 to 73.

---

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.