Skill Optimizer

Analyze and optimize skills based on official Anthropic best practices.

Workflow

Phase 1: Skill Identification

With argument: Use specified skill path directly.

Without argument:

Scan skills/ directory for SKILL.md files
List found skills with names
Let user select via AskUserQuestion

Phase 2: Analysis

Read the target SKILL.md
Auto-detect language from content (Japanese/English)
Analyze from these perspectives:

Category	Points	Check Items
Frontmatter	20	YAML syntax, name/description required, security constraints
Description	25	Trigger phrases, specificity, includes both WHAT and WHEN
Structure	20	Progressive Disclosure, SKILL.md size (under 5000 words)
Content	20	Error handling, examples, clear instructions
Additional	15	references/ usage, MCP integration (if applicable)

Calculate quality score:
- A: 90-100 (Almost no issues)
- B: 75-89 (Minor improvements available)
- C: 60-74 (Improvement recommended)
- D: 40-59 (Needs improvement)
- F: 0-39 (Fundamental issues)
Organize improvement proposals by category

Reference files for analysis criteria:

./references/yaml-frontmatter.md - YAML spec & constraints
./references/description-writing.md - Description field best practices
./references/progressive-disclosure.md - Structure design guide
./references/patterns.md - Workflow patterns
./references/mcp-integration.md - MCP integration guidance
./references/troubleshooting.md - Common issues & solutions
./references/checklist.md - Quality checklist

Phase 3: User Confirmation

Display analysis results and confirm with AskUserQuestion.

Output language: Follow detected skill language.

## Analysis Result

**Skill**: {skill_name}
**Quality Score**: {score} ({grade})

### Issues Found

#### Frontmatter ({points}/20)
- {issue_1}
- {issue_2}

#### Description ({points}/25)
- {issue_1}

...

### Improvement Proposals

Select categories to apply:
- [ ] Structure improvements (split to references/)
- [ ] Trigger improvements (description field)
- [ ] Error handling additions
- [ ] MCP integration improvements

Phase 4: Execution

For selected categories:

Maintain original style (writing style, terminology, tone)
Output in detected language
Overwrite original directory (git recovery possible)
Display updated score after execution

Edge Cases

Case	Response
YAML error	Propose fix as "improvement"
Wrong filename	Propose rename as "improvement"
No improvement needed	Show score only, report "no issues"
Mixed Japanese/English	Detect main language, unify output
Multiple language templates	Optimize each in respective language

Analysis Details

Frontmatter Checks (20 points)

Description Checks (25 points)

Includes WHAT (what the skill does)
Includes WHEN (trigger conditions)
Under 1024 characters
Contains specific trigger phrases
Not too vague ("Helps with projects" is bad)
Mentions relevant file types if applicable

Structure Checks (20 points)

SKILL.md under 5000 words
Uses Progressive Disclosure (references/ for detailed docs)
Critical instructions at top
Uses clear headers (## Important, ## Critical)
Bullet points and numbered lists for clarity

Content Checks (20 points)

Additional Checks (15 points)

references/ used appropriately for large skills
MCP tool names correct (if applicable)
Validation steps included (if applicable)

skill-optimizer

Safety Notice

Copy this and send it to your AI assistant to learn