DEV Community

Zrking pan9
Zrking pan9

Posted on

Make your skill more accurate

#ai #llm #tooling #productivity

Stop writing skills that Claude ignores. This optimizer catches the issues that waste your context window and break progressive disclosure.

The Problem

You write a skill. Claude doesn't use it. Or worse—it loads 800 lines into context when it only needs 50.

Most skill problems come down to three things:

  1. Vague descriptions that don't trigger
  2. Everything crammed into SKILL.md
  3. No decision points for multi-step workflows

This optimizer finds those issues and tells you how to fix them.

What It Does

We discovered a very useful skill：https://github.com/pan94u/skill-optimizer
Runs your skill through an 8-category checklist based on Anthropic's actual documentation:

  • Structure (15%) - Valid frontmatter, proper file organization
  • Progressive Disclosure (20%) - Three-tier loading, reference linking
  • Content Quality (20%) - Clear instructions, useful examples
  • Degrees of Freedom (10%) - Right level of specificity
  • Single Responsibility (15%) - Focused scope, no overlap
  • User Decision Points (10%) - Control flow for workflows
  • Security (5%) - Safe scripts, proper permissions
  • Testability (5%) - Validated and working

You get a score, a report, and specific fixes.

Installation 

# Clone into your Claude skills directory
cd ~/.claude/skills/
git clone https://github.com/yourusername/skill-optimizer.git

# Or for project-specific
cd your-project/.claude/skills/
git clone https://github.com/yourusername/skill-optimizer.git
Enter fullscreen mode Exit fullscreen mode

Usage

Just ask Claude:

Review my-skill
Enter fullscreen mode Exit fullscreen mode 
Check all skills for progressive disclosure
Enter fullscreen mode Exit fullscreen mode 
Optimize api-documenter
Enter fullscreen mode Exit fullscreen mode

Claude will:

  1. Load your skill
  2. Run the checklist
  3. Generate a scored report
  4. Offer to auto-fix critical issues

Example Output 

# Skill Optimization Report

## Basic Info
| Item | Content |
|------|---------|
| Skill Name | api-documenter |
| Overall Score | 72/100 |
| Rating | Acceptable |

## Main Issues

### Critical Issues
1. **Description too vague**
   - Problem: "Generates API docs" doesn't include triggers
   - Fix: Add "Use when documenting REST APIs, OpenAPI specs..."

### High Priority Issues
1. **No progressive disclosure**
   - Problem: 600 lines in SKILL.md, no reference files
   - Fix: Move examples to references/examples.md

Next steps:
1. Auto-fix critical issues
2. View detailed suggestions
3. Generate optimized SKILL.md
Enter fullscreen mode Exit fullscreen mode

What Gets Checked

Progressive Disclosure

The big one. Most skills fail here.

Bad:

# My Skill
[800 lines of everything]
Enter fullscreen mode Exit fullscreen mode

Good:

# My Skill

## Quick Start
[50 lines of essentials]

## Advanced
- **Feature X**: See [X.md](references/x.md)
- **Examples**: See [EXAMPLES.md](references/examples.md)
Enter fullscreen mode Exit fullscreen mode

User Decision Points

For workflow skills that do multiple steps.

Bad:

1. Fetch data
2. Process data
3. Generate report
4. Send email
Enter fullscreen mode Exit fullscreen mode

No control. Can't stop it.

Good:

### Step 2: Process Data
[instructions]

**After processing:**
Next steps:
1. Generate report
2. Modify parameters
3. Export data

Choose: (1/2/3)
Enter fullscreen mode Exit fullscreen mode

Description Triggers

Your description is how Claude finds your skill.

Bad:

description: A useful skill for APIs
Enter fullscreen mode Exit fullscreen mode

Good:

description: Generate API documentation from source code. Use when documenting REST APIs, creating OpenAPI specs, or maintaining API reference guides. Triggers on requests involving API docs, endpoint documentation, Swagger.
Enter fullscreen mode Exit fullscreen mode

Reference Docs

The references/ folder has the full standards:

  • principles.md - Anthropic's 7 core principles
  • progressive_disclosure.md - Three-tier architecture explained
  • checklist.md - Complete evaluation criteria
  • anti_patterns.md - 18 common mistakes
  • report_format.md - Report structure

These load on-demand. The optimizer itself uses progressive disclosure.

Why This Matters

Context window is expensive. A skill that loads 800 lines when it needs 50 is burning tokens on every request.

Progressive disclosure means:

  • Metadata always loaded (~50 tokens)
  • Body loaded when triggered (~500-2000 tokens)
  • References loaded as needed (variable)

100 well-designed skills = minimal overhead
100 poorly-designed skills = context window death

Common Fixes

Issue: Skill never triggers
→ Add specific keywords to description

Issue: Too much context loaded
→ Move details to references/, link from SKILL.md

Issue: Workflow runs without user control
→ Add decision points between major steps

Issue: Overlaps with other skills
→ Narrow scope, define clear boundaries

Contributing

Found an issue the optimizer misses? Have a better way to check something?

PRs welcome. The checklist is in references/checklist.md.

License

MIT

Credits

Based on Anthropic's official skill documentation and best practices. All principles sourced from their public engineering posts and developer docs.

If this saved you from context window hell, give it a star ⭐

Top comments (0)