# Skill Optimizer

> Analyzes and optimizes existing skills based on official best practices. Evaluates quality score, proposes structural improvements (Progressive Disclosure), description enhancement, and error handling additions. Use when: "improve skill", "optimize skill", "follow best practices", "review skill", "check SKILL.md", "analyze SKILL.md quality".

- Skill: `ttokit/skill-optimizer` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add ttokit/skill-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ttokit/skill-optimizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ttokit (https://skillmd.com/u/ttokit)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ttokit/skill-optimizer

---


# 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:

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

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

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

- [ ] `---` 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)