ttokit 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)
-
---delimiters present -
namefield exists and is kebab-case -
descriptionfield 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)