Make your skill more accurate

Zrking pan9 — Fri, 16 Jan 2026 10:08:20 +0000

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:

Vague descriptions that don't trigger
Everything crammed into SKILL.md
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

Usage

Just ask Claude:

Review my-skill

Check all skills for progressive disclosure

Optimize api-documenter

Claude will:

Load your skill
Run the checklist
Generate a scored report
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

What Gets Checked

Progressive Disclosure

The big one. Most skills fail here.

Bad:

# My Skill
[800 lines of everything]

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)

User Decision Points

For workflow skills that do multiple steps.

Bad:

1. Fetch data
2. Process data
3. Generate report
4. Send email

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)

Description Triggers

Your description is how Claude finds your skill.

Bad:

description: A useful skill for APIs

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.

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 ⭐

Forem: Zrking pan9

Make your skill more accurate

The Problem

What It Does

Installation

Usage

Example Output

What Gets Checked

Progressive Disclosure

User Decision Points

Description Triggers

Reference Docs

Why This Matters

Common Fixes

Contributing

License

Credits