markdown-quality

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

Links:

• GitHub
• Your skill in the SkillzWave marketplace

The TL;DR

You're at 82/100, solid B grade territory. This is based on Anthropic's skill best practices framework. Your strongest area is Utility (17/20) - the skill actually solves real markdown quality problems with opinionated, practical guidance. Weakest spot is Spec Compliance (12/15), mainly because your description could use more trigger phrases for better discoverability.

What's Working Well

• Rock-solid utility design. You've nailed the problem-solving angle with clear guidance on when to bend rules vs. enforce strictness. The feedback loops are clean - lint → fix → validate pattern is intuitive.
• Good Progressive Disclosure structure. You've got 4 reference files that properly defer details from SKILL.md. The separation between main content and references is thoughtful.
• Excellent examples throughout. Your anti-pattern/better example pairs really show developers why the rules matter, not just what the rules are.
• Solid troubleshooting guide. The Common Pitfalls and FAQ sections cover real problems developers hit.

The Big One

Your SKILL.md lacks a table of contents - it's ~390 lines jumping straight into content. For a file this size, developers can't quickly navigate to what they need. This hurts your Progressive Disclosure score because readers have to scroll through everything.

The fix: Add a TOC after the frontmatter with links to major sections (Getting Started, Configuration, Common Pitfalls, Troubleshooting, etc.). This is a quick win that gives you +1-2 points toward better navigation signals.

Other Things Worth Fixing

1. Duplicate pitfalls content - You're detailing pitfalls #1-4 fully in SKILL.md (lines 235-312) and in pitfalls-reference.md. Keep summaries in the main file, defer full examples to the reference. Saves tokens and improves PDA scoring (+2 points).

2. Second-person voice in troubleshooting - You're using "your file", "your workflow" in troubleshooting.md. Reframe to "the file", "this workflow", "project settings" instead. Minor style issue but keeps tone consistent (+1 point).

3. Add trigger phrases to description - You've got a solid description but only 1-2 trigger phrases. Add: "debugging", "linting", "enforcing markdown standards" to help discoverability (+1 point).

4. Nested code block rendering - Your example showing how to display code blocks (lines 140-150) mixes backticks confusingly. Use 4 backticks for the outer fence when showing 3-backtick examples for clarity (+1 point).

Quick Wins (in order of impact)

• Add table of contents to SKILL.md (~5 min)
• Consolidate duplicate pitfalls to references (~10 min)
• Add 2-3 trigger phrases to frontmatter description (~2 min)
• Fix second-person voice in troubleshooting (~5 min)
• Clean up nested code block example (~3 min)

These changes should get you to 88-90/100 range.

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