Dual trigger (system automatic +
/skill-optimizermanual). Based on the darwin-skill 9-dimensional rubric + Microsoft SkillLens (arXiv 2605.23899) utility-grounded evaluation + SkillOpt (arXiv 2605.23904) validation-gated text-space optimization. For the full dimension table / loop details / paper evidence, seereferences/。
🔴 Hard rules (violation means failure)
- validation-gated (two-layer gate): edits must undergo before-and-after comparison on held-out tests.First layer: gross: 9-dimensional Δ>0 (gross improvement signal);Second layer: human review: fine-grained scores are untrustworthy (SkillLens empirically shows LLM-as-judge at 46.4%), Δ>0 is not automatically accepted, and destructive/trigger-word changes must be confirmed by the user. It is forbidden to ship directly based on "I think it's better after the change." 🛑 Known limitation: in non-darwin environments (without git ratchet + judge swarm + skill harness real triggering), the validation gate almost inevitably degrades to dry_run—deep validation route
/darwin-skill。 - Independent scoring: scoring spawns a subagent; self-scoring and self-editing in the same context is forbidden (optimism bias). Only trust at least 2 judge consensus or 1 full_test actual measurement.
- Single-variable rounds: only 1 dimension (or 1 related cluster) is changed per round; changing multiple variables at once makes attribution impossible.
- ratchet: only keep commits with improvements; automatically roll back regressions, with git branch isolation.
- Human in the loop: before destructive / large-scale rewrites / trigger-word changes (which affect downstream discovery logic) 🔴 CHECKPOINT for user confirmation.
- Honest labeling: dry_run ratio > 30% → evaluation failure warning, scores are untrustworthy, and the user must be explicitly informed.
When to use / boundaries
| Scenario | Use this skill | Do not use this skill |
|---|---|---|
| Optimize an existing SKILL.md / agent.md | ✅ | — |
| skill does not trigger (false negative) | ✅ Add description keywords | — |
| skill falsely triggers (false positive) | ✅ Narrow when_to_use | — |
| Missing failure modes / checkpoints | ✅ Add dim3/dim4 | — |
| Quality regression (broke something) | ✅ Run the original eval scenario for comparison | — |
| Create a new skill from scratch | ❌ | → /skill-author |
| Deep autonomous scoring + visualization card + multi-round hill-climbing | ❌ | → /darwin-skill(this skill can route) |
| Person / theme perspective distillation | ❌ | → /huashu-nuwa |
Division of labor with darwin: darwin is a heavyweight automatic engine (git ratchet + judge swarm + results.tsv + visual card + MAX_ROUNDS hill-climbing); this skill is alightweight methodology orchestrator—diagnosis + single-round bounded edits + validation gate; when darwin deep scoring is needed, Skill tool routing.
Dual trigger semantics: not set disable-model-invocation, so Claude automatically loads it when the user mentions skill quality issues; the user can also /skill-optimizer <skill-name> Explicit trigger. description + when_to_use comply with project baselines (< 512 / < 128).
Optimization workflow (5 Phase)
Phase 1: Diagnose
- Locate target: user specifies skill / agent path, or scan
.claude/skills/*/SKILL.md+.claude/agents/*.md。 - 9-dimension scoring(quick reference see references/dimensions.md）：
- Structural dimensions (dim1-6): frontmatter / workflow / failure modes / checkpoints / specificity / resources
- Effectiveness dimensions (dim7-8): architecture / measured performance
- meta dimension (dim9): counterexample blacklist
- runtime red-flag scan(gate item, before scoring):
Hit → P0 fix runtime drift first (see darwingrep -nE "(在 Claude Code|Claude Code skill|Cursor only|Codex 中|~/\.claude/skills/[a-z]|/plugin install\b)" <target>references/runtime-neutrality.md）。 - Find weak spots + related clusters(HL-3): don't just look at the lowest dimension; dim2/dim3/dim4 are related clusters—when fixing one, check whether the other two are weak spots in sync. Output diagnostic table: dimension / score / weak-spot evidence (line-number references) / suggested edit type.
🔴 CHECKPOINT: show the diagnostic table to the user, confirm optimization direction + priority before designing edits. Wrong direction means all subsequent work is redone.
Phase 2: Design Edits
SkillOpt edit vocabulary(bounded add/delete/replace, not free rewriting):
| Operation | Applicable | Example |
|---|---|---|
| add | dim3 missing failure branch / dim4 missing checkpoint / dim9 missing counterexample | Add if-then three-part fallback table |
| delete | dim7 redundancy / AI-speak filler / time-sensitive information | Delete "put simply / in other words / in summary" |
| replace | dim1 description too vague / dim5 softened wording / dim2 vague steps | "suggest / could consider" → specific parameters |
Single-variable constraint: change only one dimension per round (or one related cluster). Changing multiple dimensions at once → attribution fails.
Edit granularity: prefer the smallest verifiable change (HL-1: 4 lines of 🔴 CHECKPOINT leverage dim4 +3). Avoid rewriting whole sections—unless Phase 2.5 is triggered (see below).
Phase 2.5: Exploratory Rewrite (triggered as needed)
Only when dim8 measured performance ≤ 4 / 10, or ≥ 3 dimensions are simultaneously ≤ 4, and single-point patching is no longer enough, rewrite the whole section.Must have user confirmation, and the rewritten version still goes through the Phase 3 validation gate.
Phase 3: Validation Gate — SkillOpt core
-
Design held-out tests(prepared in Phase 1, do not use trained prompts):
- 2-3 should-trigger (real user expressions that should trigger)
- 1-2 should-not-trigger (similar expressions that should not trigger, testing false positive)
- 1 edge case (not covered by the skill but related)
test prompt sample set(for this skill's self-testing; other skills imitate this structure):
- should-trigger: "I have a skill that never triggers, help me see what's wrong" "this agent.md behaves differently after changes, do a regression" "the skill triggers falsely, it pops up every time I write code"
- should-not-trigger: "help me write a new skill from scratch" (→ skill-author), "distill someone's way of thinking" (→ huashu-nuwa), "run 10 rounds of automatic optimization to produce a visualization card" (→ darwin-skill)
- edge: "help me check whether this CLAUDE.md is well written" (CLAUDE.md is not a skill; this skill does not handle it directly, but can give structural suggestions)
-
before/after comparison: spawn independent sub-agents to each run it once (with skill vs without skill baseline), blind evaluation.
-
Acceptance criteria(keep only if strictly improved):
- Trigger accuracy: should-trigger hits + should-not-trigger misses
- Output quality: visible improvement over baseline, no negative effects introduced by the skill (redundancy / drift / weird formatting)
- 9-dimension total score strictly higher than before improvement
- 🛑 Scores serve only as a gross signal: the 9-dimension score fine-grained is not trustworthy (see honesty boundary), Δ>0 only proves "gross improvement",does not replace human review; destructive/trigger-word changes must be confirmed by the user, automatic accept based on scores is forbidden
-
dry_run degradation: when sub-agents are unavailable, degrade to dry run (simulate the execution approach), results annotated
dry_run; dry_run > 30% → ⚠️ evaluation invalid warning.
Phase 4: Apply / Rollback (Ratchet)
- Pass gate → apply edits, git commit (branch
optimize/<skill>-YYYYMMDD）。 - 🔴 CHECKPOINT: user confirmation before merging to main branch / changing trigger words / large-scale rewriting (destructive, downstream discovery logic will change).
- Fail → rollback, log the failed attempt to
references/optimization-log.md(write the failure reason in the note column: unclear attribution / Δ<0 / worse triggering). - Stop at the ceiling(HL-4): 2 consecutive rounds with Δ < 2 points → break, go to Phase 5. +0.15 is a stop signal, not a continue signal; forcibly padding the number of rounds introduces over-engineering.
Phase 5: Regression + Summary
- Regression testing: after editing, run the original skill's eval scenarios. If evals.json exists, reuse it;the vast majority of skills have no evals.json(a known norm); in that case, write 2-3 test prompts on the spot and run before/after (reusing the Phase 3 held-out set) to confirm existing capabilities are not broken.
- Change semantics annotation：
- description trigger-word change = destructive(downstream discovery logic will change), must be explicitly disclosed.
- Body-only optimization = compatible.
- Summary report: before/after 9-dimension scores + Δ + list of accepted/rolled-back edits + judge consensus + dry_run ratio.
agent.md optimization differences
subagent frontmatter ≠ skill frontmatter, adapt during diagnosis:
| Dimension | skill adaptation | subagent adaptation |
|---|---|---|
| dim1 frontmatter | name/description/when_to_use/disable-model-invocation | name/description/tools/model (body=system prompt, do not rely on inherited CC prompt) |
| dim3 failure modes | skill body if-then | body must require tool failures to be explicitly annotated with [工具失败:原因], otherwise the main conversation consumes the error summary as valid data |
| dim4 checkpoints | 🔴 visual markers | subagent has no user interaction, checkpoints move up into the delegation prompt |
| dim7 architecture | progressive disclosure | Minimize the tools field (do not list all inherited) + nesting ≤ 5 levels |
| Empirical testing | test prompt comparison | Delegate a real task, verify whether the returned summary contains error contamination |
subagent tool inheritance exceptions (not granted even if listed): AskUserQuestion / EnterPlanMode / ExitPlanMode / ScheduleWakeup / WaitForMcpServers. Explore/Plan skip CLAUDE.md—if a rule must reach them, restate it in the delegation prompt.
Failure handling (dim3 three-stage)
| Trigger condition | First-line fix | Fallback if still failing |
|---|---|---|
| After editing, skill behavior unchanged | New session or re- /skill-name invoke (session does not re-read files after invoke) |
See skill-author Phase 6 |
| validation gate Δ<0 | Roll back, check whether multiple variables were changed at once | Reduce to a single variable and retry; if still negative → mark as known limitation |
| High judge disagreement (low consensus) | Add a 3rd judge or switch to full_test empirical testing | Mark as "evaluation untrustworthy", human review |
| dry_run > 30% | Add full_test (spawn a real subagent to run the test prompt) | Evaluation invalid, only issue recommendations without changing the board |
| Trigger word change causes downstream break | Roll back the trigger word, add keywords in the body | Create a new skill instead of editing in place (breaking change) |
| 9-dimension scoring cannot be attributed | Split into smaller editing units | Route /darwin-skill to do MAX_ROUNDS hill-climbing |
| Runtime red light hit | Fix runtime drift as P0 first | See darwin runtime-neutrality.md |
Anti-pattern blacklist
| # | Anti-pattern | Consequence | Positive example |
|---|---|---|---|
| 1 | Self-evaluate and self-edit in the same context | Optimism bias (46.4% accuracy) | Spawn an independent subagent for scoring |
| 2 | Skip the test prompt and score directly | dim8 scored out of thin air (weight 23%) | Phase 1 mandates preparing 2-3 prompts |
| 3 | Change multiple dimensions within a round | Attribution invalid | 1 dimension per round (or 1 related cluster) |
| 4 | Treat a high dry_run ratio as a full score | Inflated score, 0 revert | Mandate ≥ 1 full_test |
| 5 | Rely on "must" wording instead of visual markers | LLM scans markers with priority over semantics | 🔴 / 🛑 markers |
| 6 | Two-column fallback (symptom/solution) | Missing fallback path | Three-stage (trigger/first-line/fallback) |
| 7 | Force-fitting MAX_ROUNDS | over-engineering | Stop when Δ<2 for 2 consecutive rounds |
| 8 | Silently skip git/tsv anomalies | Ratchet integrity broken | Notify the user of anomalies first |
| 9 | Optimize dim2 alone without looking at the related cluster | Already pushed to the top by the previous round's dim3 fix | HL-3 looks at the related cluster's weak spots |
| 10 | Edit the subagent body without adding error annotations | The main conversation consumes the erroneous summary | [工具失败:原因] Explicitly annotate |
| 11 | Rewrite the entire section without going through the gate | Cannot attribute + may break | Rewrite still goes through Phase 3 |
| 12 | Runtime pinned to a single platform | Other agents refuse to install | Neutral badge + wording |
Validation checklist
Diagnosis
- 9-dimension scoring complete (line-number referenced evidence)
- runtime red-flag scan run
- Related-cluster weaknesses identified (HL-3)
- 🔴 Diagnosis table user-confirmed
Edit
- SkillOp vocabulary classification (add/delete/replace)
- Single variable (1 dimension / 1 related cluster)
- Minimum verifiable granularity
Validation
- held-out test（should-trigger + should-not-trigger + edge）
- Independent sub-agent blind evaluation (≥ 2 judges or 1 full_test)
- dry_run ratio < 30% (otherwise ⚠️ invalidation warning)
- Δ > 0 (strict improvement)
Application
- Apply only after passing gate + git commit (branch isolation)
- Roll back on failure + failure log
- 2 consecutive rounds Δ<2 → break (HL-4)
Regression
- Original eval scenarios not broken
- Trigger-word changes flagged as destructive
- Summary report (before/after/Δ/judge consensus/dry_run ratio)
Honest boundaries (no self-praise, real limitations)
- The 9-dimension rubric comes from darwin-skill's own test set(using its own questions to test itself), not peer-reviewed, no third-party benchmark. darwin's local controlled study (huashu-research 4 types of degradation × 5 judges) proves it can identify gross degradation, but fine-grained quality difference is not trustworthy—important decisions must be human-reviewed.
- The SkillLens/SkillOpt papers were verified as real via curl on 2026-06-26, but this skill's 9-dimension adaptation isa paraphrase of darwin's paraphrase, not an original reproduction of the papers; the specific numbers (46.4%→73.8%) are darwin's self-citation, with independent reproduction lacking.
- dry_run degradation is a common path: when sub-agents are unavailable, validation runs dry, score confidence is low, and this skill does not claim "reliable scoring without full_test".
- Covers agent.md but has less experience than skill: the subagent optimization dimension table is a design derivation, not darwin battle-tested validation (darwin only tested skill).
- This skill does not replace darwin: when multi-round hill-climbing + visual card + results.tsv history are needed, route to darwin.
- Validation gate self-reference paradox (full_test empirical): this skill's core claim is validation-gated, but the first dogfooding on 2026-06-26 (2 judges blind evaluation + 1 full_test) was 100% dry_run in a non-darwin environment—the core mechanism has not been validated by its own full_test. A subagent fork does not guarantee re-reading the target SKILL.md for a real trigger comparison, and full_test is extremely hard to achieve in ordinary sessions. Honest positioning:this skill is a good diagnostic checklist, a weak validation engine; for deep validation route to darwin.
- dim8 repeatability is zero: the 9-dimension rubric does not require a skill to have a built-in test prompt set; judges improvise prompts on the spot, causing the same skill's dim8 to differ by 4 points across two scorings (the root of the dogfooding A=7/B=3 disagreement). It is recommended that skills being optimized have built-in test prompt examples (this skill L81-83 demonstrates this).
- Does not teach creating from scratch (→ skill-author), does not teach persona perspective distillation (→ huashu-nuwa).
Research sources
Full materials see references/：
| File | Dimension | Primary source |
|---|---|---|
| dimensions.md | Full 9-dimension rubric table + HL-1~4 + related clusters | darwin-skill local + SkillLens |
| workflow.md | SkillOpt validation-gated loop + git ratchet + judge independence | SkillOpt (arXiv 2605.23904) + darwin |
| sources.md | 3 papers + darwin citations + empirical data | arXiv / GitHub (verified via curl on 2026-06-26) |