markdownlint-custom-rules

I took a look at your markdownlint-custom-rules skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 65/100, which puts you in D territory—solid foundation, but needs meaningful work to really shine. The evaluation uses Anthropic's best practices rubric. Your strongest spot is Spec Compliance (12/15), but Progressive Disclosure Architecture is dragging you down hard at just 12/30. That's the biggest opportunity.

What's Working Well

• Comprehensive coverage — You've got 15+ complete code examples showing different parser types (markdown-it, markdownlint-cli, etc.), which is genuinely helpful for someone building custom rules
• Solid spec compliance — Your YAML frontmatter is clean, naming follows conventions (hyphen-case), and you're using allowed-tools properly
• Consistent terminology — Throughout the 756 lines, you're consistent with markdownlint, parser, onError, fixInfo—no confusion about terminology
• Real problem solving — This addresses an actual gap; custom markdownlint rules aren't trivial, and you show multiple approaches (sync/async, different parsers, etc.)

The Big One: Progressive Disclosure Architecture

Here's what's holding you back: everything is in one 756-line SKILL.md file with no references. Every time this skill activates, it loads all 756 lines. That's brutal for token economy.

Why it matters: Skills should reveal complexity progressively. A user asking "how do I write a basic markdownlint rule?" doesn't need your async rule examples or parser deep-dives in the initial context window.

The fix: Create a references/ directory with these files:

• parser-examples.md — Your three parser implementations (markdown-it, markdownlint-cli, async)
• fixing-patterns.md — All the fixInfo examples and error reporting patterns
• advanced-rules.md — Async rules, complex validation logic

Then trim SKILL.md to 150-200 lines covering: overview, basic rule structure, when to use it, and links to the references. Impact: +12 points alone.

Other Things Worth Fixing

1. Add trigger phrases to your description — Right now it's just "Create custom linting rules for markdownlint..." but doesn't say when to use it. Add: "Use when asked to create markdownlint rules, write custom markdown validators, or enforce doc standards." (+2 points)

2. Redundant examples — Lines 59-135 show three parsers doing nearly identical blockquote detection. Show one complete example, then diff-style variations. You're repeating the same pattern unnecessarily. (+2 points)

3. Missing table of contents — A 700+ line file needs navigation. Add a TOC after your overview section linking to Rule Structure, Parser Selection, Error Reporting, fixInfo sections. (+2 points)

4. No numbered workflow — Your Best Practices section is tips, not a workflow. Add a Quick Start: "1. Create rule file → 2. Define names/description → 3. Choose parser → 4. Implement → 5. Register in config → 6. Test" (+2 points)

Quick Wins

• Create references/ folder and split out parser examples (+12 points)
• Add trigger phrases to frontmatter description (+2 points)
• Consolidate redundant code patterns (+2 points)
• Add TOC and numbered workflow (+4 points)

These four changes could push you from 65 to 85+.

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.