markdownlint-integration

I took a look at your markdownlint-integration 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 is F territory. This skill covers a lot of ground on markdownlint integration—your Ease of Use is solid at 17/25, and Spec Compliance hits 12/15—but the biggest drag is Progressive Disclosure Architecture at just 12/30. The core issue? You've crammed 910 lines into a single SKILL.md file when it should be broken into modular reference files. That's killing your token efficiency and navigation.

What's Working Well

• Comprehensive coverage: You're touching CLI, API, CI/CD (GitHub Actions, GitLab, CircleCI, Jenkins, Azure), hooks, and editors. That's thorough.
• Valid frontmatter: Your YAML checks out with all required fields present.
• Consistent terminology: Good use of consistent language around "markdownlint," "linting," and "configuration" throughout.
• Real code examples: You're not skipping over the implementation details—there are actual command examples and configurations people can use.

The Big One: Break Up That Monolithic File

Your skill is essentially a 910-line encyclopedia squeezed into one file. This violates progressive disclosure architecture hard. The fix is straightforward:

Create a references/ directory with external files:

• references/cli.md - Command-line usage
• references/api.md - Node.js API integration
• references/ci-github.md, ci-gitlab.md, ci-circleci.md, etc. - Each CI platform gets its own file
• references/editors.md - VS Code, Vim, Neovim configurations
• references/hooks.md - Pre-commit and Husky setups

Your main SKILL.md becomes a quick-reference overview with links to these files. This cuts token bloat, improves navigation, and hits that PDA requirement. Estimated gain: +8 points.

Other Things Worth Fixing

1. Add trigger phrases to your description - Right now it's functional but doesn't say "use me when you want to lint markdown" or "set up CI/CD markdown checks." Something like: "Lint markdown files, set up CI/CD markdown checks, configure pre-commit hooks, integrate markdownlint with VS Code/Vim." Gets you +2 points and better discoverability.

2. Add a table of contents - At 910 lines, users are scrolling blind. A TOC after the overview showing jump links to CLI, API, CI/CD, hooks, and editors takes 5 minutes to add and improves navigation signals. +2 points.

3. Trim the best practices/pitfalls lists - You have 15 best practices and 15 pitfalls (35 lines of lists). Pick the top 5 for each, keep them in SKILL.md, and move the detailed ones to a reference file. Addresses the verbosity issue. +2 points.

4. Show expected output in examples - Your code blocks show commands but not what success looks like. Add expected linting output so people know what to expect. +2 points.

Quick Wins

• Biggest impact: Restructure into modular reference files (+8 points) — this fixes your PDA score dramatically
• Fast wins: Add trigger phrases (+2), TOC (+2), trim lists (+2), show expected outputs (+2) = +8 more points
• Together: 58 → 74+ with focused effort

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.