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:

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

Phase 2: Analysis

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

4. 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)

5. 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:

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

Edge Cases

Analysis Details

Frontmatter Checks (20 points)

• --- delimiters present
• name field exists and is kebab-case
• description field exists
• No XML tags (< >)
• No "claude" or "anthropic" prefix in name
• Valid YAML syntax

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)

• Error handling included
• Examples provided
• Instructions are specific and actionable
• References clearly linked
• No ambiguous language

Additional Checks (15 points)

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