| name | skill-optimizer |
| description | Evaluate and improve an existing Claude Code skill using explicit success criteria and small controlled changes. Use when the user asks to optimize a skill, reduce over-triggering or under-triggering, improve reliability, tighten instructions, or add evals for a skill. Also trigger on "スキルを改善して", "スキルを最適化して", "スキルの品質を確認して". |
| disable-model-invocation | true |
| allowed-tools | Read, Grep, Glob, Bash |
Pattern declaration
Primary pattern: Reviewer
Secondary patterns: Pipeline
Why: optimization starts with diagnosis against criteria, then applies small changes in a controlled sequence with eval checkpoints.
Purpose
Improve an existing skill without breaking what already works.
Your job is to:
- inspect the current skill package
- define or refine success criteria
- identify failure modes
- propose one small change at a time
- attach each change to an eval hypothesis
- reject changes that cannot be evaluated
Core optimization rule
Never apply a large rewrite first.
Optimize in small units:
- description
- gate logic
- workflow order
- examples
- prohibited behaviors
- output contract
- review checklist
- supporting file structure
Change only one major unit per proposal.
Phase 0: Baseline audit
Inspect:
- current
SKILL.md
- current supporting files
- invocation settings
- current examples
- current failure reports or user complaints
- existing eval cases if any
Then summarize:
- what the skill is supposed to do
- where it fails
- whether the issue is discovery, execution, or validation
Phase 1: Success criteria
Define 3 to 6 evaluation criteria.
Each criterion must be:
- specific
- observable
- pass/fail or narrowly scored
Separate:
- trigger quality
- task fidelity
- completeness
- safety / side effects
- output format compliance
Phase 2: Failure mapping
Classify failures into:
- over-triggering
- under-triggering
- missing context collection
- vague output
- hallucinated assumptions
- skipped verification
- unnecessary tool use
- high token or step cost
Phase 2.5: Pattern mismatch diagnosis
Before proposing wording or structure fixes, you must check whether the failure is caused by the wrong pattern or a missing secondary pattern. Do not skip this phase.
Check:
- acts too early on ambiguous input → missing Inversion
- output structure is inconsistent across runs → missing Generator
- returns unvalidated or unchecked output → missing Reviewer
- skips required steps or loses sequence control → missing Pipeline
- lacks domain-specific accuracy → missing Tool Wrapper
If pattern mismatch exists:
- recommend the smallest structural correction first
- do not jump to wording tweaks before resolving the pattern issue
Do not proceed to Phase 3 until pattern mismatch has been evaluated and documented.
Phase 3: Optimization proposal
For each proposed change, output:
- change id
- exact file to modify
- exact section to modify
- exact change summary
- reason
- expected benefit
- risk
- eval method
- rollback condition
Prefer the smallest useful change.
Phase 4: Eval plan
For the recommended next change, define:
- baseline measurement
- test prompts
- grading method
- number of trials
- adoption threshold
- rollback threshold
Use ${CLAUDE_SKILL_ROOT}/assets/eval-rubric-template.md as the rubric structure.
Default stance:
- do not adopt on a single successful run
- do not accept regressions on critical criteria
Phase 5: Review
Check against:
${CLAUDE_SKILL_ROOT}/references/review-default.md${CLAUDE_SKILL_ROOT}/references/optimization-playbook.md
Before finalizing, verify:
- no broad rewrites without evidence
- no hidden assumptions
- no unverifiable claims
- no changes that weaken safety or review steps
- no new ambiguity in the description
Output format
Return exactly these sections:
Baseline summary
Success criteria
Failure modes
Pattern mismatch diagnosis
Recommended next change
Eval plan
Rollback rule
Follow-up changes backlog
Anti-patterns
Do not:
- rewrite the whole skill first
- mix multiple major changes in one proposal
- optimize without a baseline
- optimize only for style
- remove verification to save tokens
- broaden description without evidence
Failure handling
If the current skill is structurally unsalvageable:
- say so directly
- recommend a replacement design
- explain why incremental optimization is not appropriate
