claude-md-enhancer

I've been digging through the CLAUDE.md files and skill system, and I see you're working on enhancing markdown processing for Claude Code—solid conceptual foundation, but the execution is pulling the grade down to 69. What's the thinking behind your current architecture choices, and where do you see the biggest friction points in the token efficiency?

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 69/100, solidly in D territory. This evaluation is based on Anthropic's Progressive Disclosure Architecture (PDA) standards—the methodology that keeps skills lean and navigable. Your strongest area is Utility (15/20)—the skill genuinely solves a real problem with CLAUDE.md generation. But Writing Style (5/10) is where you're bleeding points, and your token economy needs serious attention (18/30 on PDA).

What's Working Well

• Real utility here. The skill addresses an actual pain point—CLAUDE.md generation isn't trivial, and your approach of analyzing existing files then generating structured content is solid.
• Good modular structure. You've got examples/, scripts/, and references/ directories—that's the right instinct for layering. The bonus points for "verifiable intermediate outputs" and "exemplary examples" reflect that.
• Reasonable trigger coverage. "Setting up CLAUDE.md", "improve my CLAUDE.md", "analyze existing files"—these hit the right use cases, though they're buried in verbose description.

The Big One: 447 Lines Is Too Much

Your SKILL.md is 447 lines when it should be <150. This is your biggest token drain. You've got Example 1, Example 2 (appears twice—duplicate numbering), an Interactive Example section, and Workflow Steps all crammed into the main file. This violates the core PDA principle: reference material belongs in the references/ folder, not inline.

Here's the fix: Keep SKILL.md to ~120 lines covering:

• Metadata + description
• One "Quick Start" section (3-4 triggers max, concise)
• A single line: "See references/examples.md for detailed workflows and edge cases"

Move everything else to:

• references/workflow.md - your narrative workflow steps
• references/examples.md - all three examples consolidated, not duplicated
• references/best-practices.md - validation patterns and error handling

Impact: +8 points immediately. You'd jump from 18/30 to 26/30 on PDA.

Other Things Worth Fixing

1. Kill the second-person voice. Lines 27, 141, 148, 231, 250 use "you", "your", "Would you like"—switch to imperative: "To analyze existing CLAUDE.md" instead of "Provide existing CLAUDE.md" and "your repository". Costs you 2 points. +2 points.

2. Strip the marketing language. Emoji bullets ('🆕 Interactive Initialization'), superlatives ('100% Native', 'comprehensive'), and cheerleading ('Ready for immediate use!') come across as non-objective. Tone it down to straightforward descriptions. +1 point.

3. Add terminology consistency. You flip between enhance/improve, analyze/scan/evaluate, generate/create. Pick one verb per concept and stick with it throughout. Helps with discoverability. +2 points.

4. Missing validation workflow. You mention "Always validate your output against official native examples" (line 310-320) but don't provide an executable run→check→fix pattern. Add a simple validation step: "After generation, compare output against compare_format(output, /update-claude-md) to catch deviations." +2 points.

Quick Wins

• Move examples to references/ (+8 points)
• Add TOC and trim SKILL.md to <150 lines (+3 points)
• Switch to imperative voice, drop "you/your" (+2 points)
• Standardize terminology (enhance, analyze, generate) (+2 points)
• Remove marketing language (+1 point)

Hit these five and you're looking at 85/100 territory. The utility is already there—you're just carrying too much weight in the main file.

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.