meta-skill: the methodology is derived from Anthropic official specs + SkillLens 9-dimension empirical study (arXiv 2605.23899) + SkillOpt validation-gated optimization (arXiv 2605.23904) + community anti-patterns, fully self-contained with no need to link to other skills. For complete research materials see
references/research/01-06.mdandreferences/(for scope/process details see description and the routing table below, not repeated here).
🔴 Hard rules (violation means failure)
- Explicit trigger: this skill
disable-model-invocation: true, only/skill-devmanually invoked. It is a creation/optimization tool, not background knowledge; do not change it to automatic triggering. - Artifact positioning: build function / domain / topic perspective skills or subagents (the creation methodology has Process A built in); do not distill persona role-play DNA (expression tone / character personality are outside this skill's scope).
- Honest labeling: fabricating citations is forbidden. Sources that cannot be verified are discarded outright; dry_run ratio > 30% → evaluation failure warning, scores are untrustworthy, and the user must be explicitly informed.
- Independent scoring(during optimization): scoring spawns a subagent; self-evaluation and self-modification in the same context is forbidden (optimism bias, SkillLens empirically found LLM-as-judge 46.4%). Only trust at least 2 judge consensus or 1 full_test actual measurement.
- After changing any SKILL.md / agent.md, pass the quality gate: for files with YAML frontmatter use the stdin command template (no
"$(cat ...)"interpolation,---will be parsed as a CLI option), for a single command see references/skill-quality-checklist.md §Quality Gate Verification Method; on endpoint flakiness (400/empty return) use a retry loop (see memory claude-p-endpoint-flaky), only pass if three runs are consistent; if it still fails after 3 times → manual verification + small-step rollback-capable commit, marked "pending endpoint recovery for re-run".
Routing (first decide create or optimize)
| Input signal | Go to |
|---|---|
| "Help me make an X skill / write a skill from scratch / add a subagent / configure a db agent" | Process A · Create |
| "This skill doesn't trigger / is too long / changes didn't take effect / triggers incorrectly / quality regression / do a regression" | Process B · Optimize |
| "Should this go in SKILL.md or be split into a reference / should context:fork be used / how to write the description" | Process A related Phase (structure/frontmatter decisions) |
| Deep autonomous scoring + visualized results card + multi-round hill-climbing | Process B · Optimize(9-dimension scoring / validation-gated hill climbing / results card all built in) |
| Domain/topic perspective distillation (requires dimension-by-dimension research + triple validation extraction) | Process A · Create(Phase 4 has built-in research swarm + validation funnel) |
| Persona role-play DNA (expression tone / personality simulation) | 🛑 Outside this skill's scope (distill methodology, not personas) |
When the boundary between create and optimize is blurry (e.g., "this skill doesn't trigger, and while you're at it help me add a feature"):First run optimize diagnostics, then based on the diagnostic conclusion decide whether to go through create to fill in structure。
Flow A · Create skill / agent (6 Phase)
Phase 1: Positioning (answer the 4 questions first, then start writing)
- skill or subagent?
- Reusable prompt/workflow, runs in the main conversation → skill
- Produces redundant output that needs isolation, requires enforced tool restrictions, self-contained returns a summary → subagent
- Background knowledge (should not be command-triggered) → skill +
user-invocable: false - Hybrid(main conversation interaction + subtask isolation, e.g., deployment requires confirmation + verification + execution) → skill +
context: fork+agent: <type>
- Trigger method?(judge "which kind of load is more worthwhile to pay") model-invoked pays context load(description is resident every turn, only worthwhile when the agent must autonomously reach it or be reached by another skill—reuse ≠ a reason to extract, autonomous reachability is); user-invoked pays cognitive load(humans become the index, zero residency). Side-effect operations (deploy/commit/send) →
disable-model-invocation: true(manual only); background knowledge →user-invocable: false; general workflows → default. - Content type? Reference (conventions/patterns) → inline resident; Task (deployment/generation steps) → often paired with
disable-model-invocation。 - Degrees of freedom? Multiple solutions all acceptable → high (text instructions); has a preferred one → medium (parameter template); operation is fragile → low (specific script, no parameters).
✅ Completion criteria: All 4 questions have a clear landing point (skill/subagent choose one · trigger method tier · Reference/Task choose one · degrees of freedom tier), with no empty "decide later depending on the situation" answers.
Phase 2: Skeleton
my-skill/
├── SKILL.md # 主指令（≤500 行 / token 意识）
├── references/ # 按需加载细节（只深一层）
└── scripts/ # 可执行脚本（执行而非加载）
- Split multiple domains by
references/<domain>.md; for >100-line references, put a table of contents at the top. - References only one level deep: no a→b→c nesting (Claude pre-reads nested
head -100, causing incomplete information).
🔴 CHECKPOINT: After the skeleton is finalized, show the directory structure to the user for confirmation, then proceed to frontmatter. If the skeleton direction is wrong, everything afterward is rework.
✅ Completion criteria: The directory tree is finalized (including the reason for splitting references/ , or a determination that a single file is sufficient) · The user has confirmed at CHECKPOINT.
Phase 3: frontmatter
The complete 16-field table + invocation control matrix + string substitution variables are in references/frontmatter-spec.md。 The 5 most commonly used:
---
name: <lowercase-kebab> # 默认目录名；≤64 字符，禁 anthropic/claude 保留词，禁 XML 标签
description: <做什么 + 何时用> # 🔴 项目底线 < 512 字符；第三人称；key use case 前置
disable-model-invocation: true # 副作用操作必加（仅手动 /name）
allowed-tools: Bash(git *) # 预授权工具（可选，仅免批准不限制工具池）
paths: packages/api/** # monorepo 按包触发（可选）
---
description iron rules(P0 anti-pattern): third person (no "I can" "You can") · include key terms (words users would say) · write both "what it does" + "when to use it" · key use case upfront(🔴 bottom line < 512 characters, stricter than the official 1024/1536 truncation; for long lists, trim by "drop the least-invoked first") · overly long trigger phrases/examples are offloaded to when_to_use(bottom line < 128) · narrow the "when to use" boundary(too broad causes false triggers; discoverability ≠ trigger accuracy).
✅ Completion criteria：name/description is filled in and description passes the three self-checks of "third person + key use case upfront + < 512 characters" · side-effect/background knowledge/monorepo scenario corresponding fields (disable-model-invocation/user-invocable/paths) have been set according to the Phase 1 determination.
Phase 4: Research + Content (writing to disk is the source of truth → review gate → triple verification → assembly)
Research first, then write—The quality ceiling of a skill from a function / domain / topic perspective is determined by research quality (garbage in, garbage out; intercepting here is cheaper than rework in Phase 5). When the target domain is entirely common knowledge already known to Claude, you can skip 4.1-4.2 and write directly.
4.1 Parallel research by dimension(when domain knowledge is insufficient): split the target domain into non-overlapping dimensions (official specifications / existing implementation patterns / boundaries and failure modes / anti-patterns / toolchain), with one independent subagent per dimension researching in parallel.Interface agreement(swarm relies on agents orchestrating on the spot, with no physical script): each agent must write its results to references/research/0X.md——Not persisting to disk equals not doing it(persisting to disk is the truth); each item must be labeled with source + credibility (first-hand > second-hand > speculation); distinguish "what the docs say" vs "what the community says" vs "what I infer"; when contradictions are foundkeep them, do not paper over them。the skill must be self-contained: research files go inside the skill directory, so copying the entire directory makes it independently usable. If the environment does not support parallelism → see the degradation table in Process A.
4.2 🔴 Research review gate (CHECKPOINT): after all dimensions are persisted to disk, pause and show the user a research quality summary (number of sources per dimension / key findings / contradictions / dimensions with insufficient information). Only proceed to synthesis if quality is OK; if a dimension is insufficient → do more research before continuing. This gate intercepts garbage input, and the cost is far lower than rework in Phase 5.
4.3 Triple verification funnel(determines what goes into the skill body): each candidate rule/claim must pass three gates—① cross-domain reproduction(holds in ≥2 different scenarios/tasks) ② generative predictive power(can be used to infer the correct approach to new problems) ③ uniqueness excluding common knowledge(not something every competent Claude would do by default). Passing all three → core content; only 1-2 → downgrade to secondary hint/side note; 0 → discard (Claude already knows it, writing it only burns tokens). This is the executable version of "only add what Claude does not know."
4.4 Template + mapping table assembly: use the skeleton (Phase 2) as the template, and use the section→source mapping table to fill in the research + verification results section by section (frontmatter / workflow checklist / failure modes / counterexample blacklist / research sources).The target skill defaults to positive phrasing, with counterexamples paired with positive examples only in necessary scenarios—the main body of the target skill states "what to do," leaving counterexamples only at hard guardrails that cannot be positively phrased, and every counterexample must be paired with a positive example (matt paradigm Negation iron rule: state the target behavior, so that forbidden behavior is never mentioned).progressive disclosure: SKILL.md acts like a table of contents pointing to on-demand details; complex workflows get a copyable checklist (Claude checks off items one by one); quality-critical operations add feedback loop(validate → fix → repeat), and batch/destructive operations use plan-validate-execute(produce plan → script validation → execute → verify). For each section, ask "is this section worth its token cost?"
✅ Completion criteria(checkable + exhaustive, to prevent premature completion): □ everycandidate rule has passed the triple verification funnel (not "produced a list of rules") □ everyresearch dimension has been persisted to disk references/research/(not "did research").
🔴 CHECKPOINT: after the first draft of SKILL.md is complete, show it to the user for review, and only proceed to Phase 5 after confirming the content direction.
Phase 5: Verification
- eval first(Before writing content): run 3 representative taskswithout skill to record a failure baseline → write ≥3 eval scenarios (query + expected_behavior) → compare after writing.
- Structural self-check: check item by item against the "anti-pattern blacklist".
- AI-discoverability quality check：
claude -p "列出所有可用 skill 并说明何时触发" ...(same as hard rule 5 commands). - 🛑 Trigger accuracy test(critical, distinct from discoverability): use should-trigger + should-not-trigger prompt pairs to test false positive / false negative. Discoverability only tests "can be listed", and cannot catch false triggers/missed triggers—a zero-visibility failure.
- Reverse interrogation(optional):
/grillingred-team。 - Quantitative quality gate (convergence criterion): pass the quantitative standards item by item (≥3 eval scenarios all pass · triggers have no false positive + false negative · counterexample blacklist complete · no unverified citations). If not passed → go back to the corresponding Phase to fix,Phase 4→5 iteration limit 2 rounds: if items still fail after 2 rounds, mark the weak dimensions at the honest boundary and deliver the current best version; do not polish indefinitely (better to deliver an honest 60-point version with marked limitations than a seemingly perfect but fabricated 90-point version).
- 9-dimension scoring/A-B eval(optional): if deep scoring + validation-gated hill climbing is needed → switch to this skill's Process B(9-dimension scoring / hill-climbing gate / blind evaluation are all built in, see below).
Phase 6: Maintenance (modifying an existing skill)
- Session not updated after invoke: SKILL.md is rendered as a single message and persists for the whole session; after modifying the file, an already-invoked session still runs the old version → notify the user to open a new session or re-invoke.
- Change scope judgment: behavior/trigger changes (affecting muscle memory + downstream discovery logic) → evaluate whether to create a new skill instead of modifying in place; body-only optimization → modify in place.
- Regression: after changes, run the original eval scenarios to confirm nothing is broken.
- Version semantics: description trigger word changes = breaking; body-only optimization = compatible.
✅ Completion criteria: change scope has been determined (modify in place / create new) · regression eval has been run and nothing is broken · version semantics (breaking/compatible) have been marked and communicated to the user.
If 9-dimension diagnosis + validation-gated deep optimization is needed → switch toProcess B。
Process A degradation table (degradation paths when the environment is insufficient, if-then)
| Trigger condition | First-line fix | Fallback if still failing |
|---|---|---|
| Environment does not support parallel subagents (Phase 4.1 hangs and waits forever) | Research degradationSerial: after finishing one dimension, persist that dimension; do not hang waiting for background notifications | Run a single agent in rounds, persisting each dimension immediately after each round |
| Insufficient context window (accumulated overflow prevents completion) | Continue by Phase: persist at the end of each Phase references/research/, and restore in a new session by reading the files (the research file is the checkpoint) |
Run Phases 1-3 / 4 / 5-6 in segmented sessions, reading the already-persisted files at the start of each segment |
| Search/WebSearch tool unavailable | Switch to an environment with an equivalent available tool (fetch / an installed information-acquisition skill) | Guide the user to provide first-hand material and switch to local-material mode |
| Scarcity of information sources (<10 usable sources) | Phase 4.2 lowers expectations, core rules reduced | Expand the honesty-boundary section, mark speculative elements |
| Single-dimension agent times out with no valuable result | Do not wait, keep advancing; Phase 4.4 marks "insufficient information for this dimension" | The honesty boundary states this dimension is weak; do not force generation |
1. Positioning (Phase 1 four questions)
- skill / subagent: <type> · trigger method: <model / user-invoked> · content type: <Reference / Task> · degrees of freedom: <high/medium/low>
- One-sentence responsibility statement: <what the target skill does + defining constraints>
2. Skeleton (Phase 2)
<目录树：SKILL.md / references/ / scripts/ >
- Splitting rationale: <why split references this way>
3. frontmatter（Phase 3）
- name: · description: <what it does + when to use + trigger words, <512 characters> · disable-model-invocation: <true/default>
- Key trigger words: <list the words users would say>
4. Research (Phase 4)
- Dimension-by-dimension research persisted to disk: <each dimension corresponds to references/research/0X.md>
- Research review gate conclusion: <source count per dimension / key findings / contradictions / dimensions with insufficient information>
- Triple-verification funnel: <core rules (pass all three) / secondary (1-2) / discarded (0)>
- Positive-form check: □ main body stated positively □ any residual counterexamples paired with positive examples
5. Validation (Phase 5)
- eval scenarios: <≥3, query + expected_behavior>
- Quantitative quality gate: □ ≥3 evals all pass □ triggering has no FP+FN □ failure-mode three-part structure complete □ no unverified citations
- Trigger accuracy test: <conclusion of should-trigger / should-not-trigger pairs>
- claude -p discoverability check: <returns non-empty and identifies correctly>
- Phase 4→5 iteration rounds: <N/2> · weak dimensions (honestly marked): <list>
Process B · Optimize an existing skill / agent (5 Phase · validation-gated)
Based on SkillLens utility-grounded evaluation + SkillOpt validation-gated text-space optimization. Full dimension table / loop details see
references/dimensions.md·references/workflow.md。
🔴 Optimization hard rules(stacked on top hard rules):validation-gated two-layer gate(first layer gross: 9 dimensions Δ>0; second layer human review: scores fine-grained and untrustworthy, destructive/trigger-word changes must be confirmed by the user, no direct landing of "I think it's better") · single-variable rounds(each round changes only 1 dimension or 1 related cluster) · ratchet(only keep commits with improvements, regressions git revert HEAD auto-rollback, git branch isolation) · bloat guardrail(after changes SKILL.md > original ×1.5 → reject commit, streamline first then evaluate, prevent "adding filler to pad the score" bloat) · stop at ceiling(2 consecutive rounds Δ<2 → break). 🛑 known limitations(inherent to the method, not a missing tool): the validation gate of text-space optimization depends on a real skill harness trigger + independent judge swarm; when the environment is insufficient it degrades to dry_run; dry_run > 30% means an evaluation-invalidity warning, scores are untrustworthy and require human review——this isthe ceiling of text-space optimization itself, no external skill can bypass it, only the full_test ratio + human review can backstop it.
Phase 1: Diagnose
- Positioning: user-specified path, or scan
.claude/skills/*/SKILL.md+.claude/agents/*.md。 - 9-dimension scoring(for quick reference see references/dimensions.md): structure dim1-6 (frontmatter/workflow/failure modes/checkpoints/specificity/resources) · effectiveness dim7-8 (architecture/empirical testing) · meta dim9 (counterexample blacklist).
- runtime red-flag scan(gate item, before scoring):
Hit → P0 fix runtime drift first: replace single-platform-pinned wording ("in Claude Code", "Claude Code skill") with neutral phrasing, change badge/install path to the three-layer neutral structure "Agent Skills Standard + multi-runtime". Exceptions: frontmatter trigger words, references to skill names within the ecosystem, sections explicitly marked runtime-specific, and commit messages do not count as red flags.grep -nE "(在 Claude Code|Claude Code skill|Cursor only|Codex 中|~/\.claude/skills/[a-z]|/plugin install\b)" <target> - Find weak spots + correlated clusters(HL-3): dim2/3/4 are a correlated cluster; when fixing one, check whether the other two are weak spots in sync. Output a diagnostic table: dimension/score/weak-spot evidence (line-number references)/suggested edit type.
🔴 CHECKPOINT: show the diagnostic table to the user, and only design edits after confirming direction + priority. A wrong direction means all subsequent rework.
✅ Completion criteria: 9-dimension scoring + runtime red-flag scan both run · diagnostic table (dimension/score/weak-spot evidence line numbers/suggested edit type) produced · user has confirmed direction at CHECKPOINT.
Phase 2: Design edits (Design · SkillOpt edit vocabulary)
| Operation | Applicable | Example |
|---|---|---|
| add | dim3 missing failure branch / dim4 missing checkpoints / dim9 missing counterexamples | Add an 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 (or one correlated cluster) per round; changing multiple dimensions at once invalidates attribution.Positive-form editing: the target skill defaults to positive phrasing; only in necessary scenarios pair counterexamples with positive examples—rewrite "do not do Y" blacklists into target behaviors, and if a counterexample remains when necessary it must be paired with a positive example (matt paradigm Negation).Edit granularity: prefer the smallest verifiable change (HL-1: 4 lines of 🔴 CHECKPOINT leverage dim4 +3), avoid rewriting entire sections—unless Phase 2.5 is triggered.
✅ Completion criteria: each edit has a defined operation type (add/delete/replace) + hit dimension + specific change content · single-variable constraint verified (this round only 1 dimension or 1 correlated cluster).
Phase 2.5: Exploratory rewrite (as needed)
Only when dim8 empirical testing ≤ 4/10, or ≥3 dimensions are simultaneously ≤ 4, and single-point patching is insufficient, rewrite entire sections.Requires user confirmation, and the rewritten version still goes through the Phase 3 gate.
Phase 3: Validation (Validation Gate · SkillOpt core)
- held-out testing(prompts not used in training): 2-3 should-trigger + 1-2 should-not-trigger (to test false positives) + 1 edge case.
- before/after comparison: spawn independent sub-agents to each run it once (with skill vs baseline), blind evaluation.
- Acceptance criteria(Keep only if strictly improved): trigger accuracy (should-trigger hits + should-not-trigger misses) · output quality shows visible improvement over baseline with no negatives (redundancy/drift/odd formatting) · 9-dimension total score strictly higher than before · 🛑 Scores serve only as a gross signal, Δ>0 does not replace human review; destructive/trigger-word changes must be confirmed by the user.
- dry_run degradation: dry run when sub-agent is unavailable (simulate execution approach), annotate
dry_run; > 30% → ⚠️ evaluation invalid warning.
✅ Completion criteria（checkable + exhaustive）：□ Each held-out prompt has a before/after conclusion (not "ran the tests") □ dry_run ratio recorded.
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 rewrite (destructive, downstream discovery logic will change).
- Fail → rollback (
git revert HEADcreate reverse commit, forbidreset --harddiscarding the working tree), record failed attempt toreferences/optimization-log.md(note the reason: unclear attribution / Δ<0 / worse triggering). - Bloat guardrail: after edits SKILL.md > original ×1.5 → reject commit, go back to the improvement step to trim (delete redundancy/merge duplicates) and re-evaluate. Continuing to force edits after hitting the ceiling is often "adding filler to make the LLM feel it's more detailed"; bloat ×1.5 is the warning sign.
- Stop at ceiling(HL-4): 2 consecutive rounds of Δ < 2 points → break into Phase 5. +0.15 is a stop signal, not a continue signal.
✅ Completion criteria: this round has been committed (passed) or reverted (failed) · on failure references/optimization-log.md has been recorded (including failure reason).
Phase 5: Regression + Summary
- Regression: after edits, run the original eval scenarios.The vast majority of skills have no evals.json(normal) → write 2-3 test prompts on the spot and run before/after (reuse the Phase 3 held-out set).
- Change semantics annotation: description trigger-word change = destructive(downstream discovery logic changes) must be explicitly communicated; body-only optimization = compatible.
- Summary: before/after 9-dimension scores + Δ + accepted/rolled-back edit list + judge consensus + dry_run ratio.
- Visual results card(optional, showcase results): copy
templates/result-card.html, fill in skill name / before-after-Δ scores / 9-dimension radar / hill-climbing rounds / improvement summary / date, open in browser or screenshot. The template comes with 3 styles (swiss/terminal/newspaper, switched via URL hash), no external scripts needed.
✅ Completion criteria: regression eval has been run and did not break · change semantics (destructive/compatible) annotated · summary report has all four elements (9-dimension scores+Δ / edit list / judge consensus / dry_run ratio).
Overview
- Target skill: <path>
- Date: · Number of judges: · Hill-climbing rounds: <N rounds> · dry_run ratio: <%>
- Final verdict: ✅ Keep / ⏮️ Rollback (reason: <unclear attribution / Δ<0 / worse triggering>)
before / after 9-dimension scores
| dim | Dimension | Direction | Ideal value | before | after | Δ | Completion-criteria baseline met? |
|---|---|---|---|---|---|---|---|
| 1 | Frontmatter quality | ↑ | name+desc+trigger words<512 | □ | |||
| 2 | Workflow clarity | ↑ | steps+IO+Done when | □ | |||
| 3 | Failure mode encoding | ↑ | three-part if-then | □ | |||
| 4 | Checkpoint design | ↑ | 🔴/🛑 visual markers | □ | |||
| 5 | Executable specificity | ↑ | no soft wording | □ | |||
| 6 | Resource integration | ↑ | paths reachable+one level deeper | □ | |||
| 7 | Overall architecture | ↑ | no AI tone | □ | |||
| 8 | Measured performance | ↑ | ≥2 test prompt | □ | |||
| 9 | Counterexample guardrails | ↓ | positive-first+counterexamples paired with positive examples | □ | |||
| Total | <+n> |
Direction axis (which dimensions ↑ and which ↓, whether converging toward ideal values)
- ↑ dimensions (higher is better): <list dimensions where before<ideal, whether after moves toward ideal>
- ↓ dimensions (lower is better, dim9 counterexample residue): <list dimensions where before>ideal, whether after converges>
Edit list
- Keep (ratchet landed): <each edit + its dim + acceptance reason>
- Rollback: <each rollback edit + rollback reason (Δ<0 / attribution invalid / trigger worsened)>
Judge consensus and credibility
- judge consensus: <unanimous / 1-vote disagreement / add 3rd judge> · full_test count: · evaluation credibility: <credible / dry_run>30% human review>
Breaking change annotation
- Trigger word/description change: <yes/no> → if yes mark breaking, downstream discovery logic changes
subagent authoring points + agent.md optimization differences
subagent frontmatter / body design points (error handling conventions / tool inheritance exceptions / hook condition validation / fork vs named) + always-on vs on-demand / explicit vs implicit triggering / runtime-neutral tradeoffs, see references/subagent-authoring.md. When optimizing agent.md, diagnostic dimension adaptation:
| Dimension | skill adaptation | subagent adaptation |
|---|---|---|
| dim1 frontmatter | name/description/when_to_use/disable-model-invocation | name/description/tools/model (body=system prompt, CC prompt that relies on inheritance is forbidden) |
| dim3 failure modes | body if-then | body must require tool failures to be explicitly marked [工具失败:原因], otherwise the main conversation consumes the error summary as valid data |
| dim4 checkpoints | 🔴 visual markers | subagent has no user interaction, checkpoints move up to the delegation prompt |
| dim7 architecture | progressive disclosure | tools field minimized + nesting ≤ 5 levels |
| Measured | test prompt comparison | delegate a real task, verify whether the returned summary contains mixed-in errors |
subagent tool inheritance exceptions (not granted even if listed): AskUserQuestion / EnterPlanMode / ExitPlanMode / ScheduleWakeup / WaitForMcpServers. Explore/Plan skips CLAUDE.md—if rules must arrive, restate them in the delegation prompt.
Consensus iron rules (all sources agree)
| # | Iron rule | Reason |
|---|---|---|
| 1 | SKILL.md ≤500 lines (token proxy, not an exact value） | CJK/tables/code blocks have high token density, 500 lines of Chinese may be 8000+ tokens; resident for the whole session |
| 2 | description third person + key use case front-loaded + what to do + when to use + narrow the boundary to prevent false triggers | discovery entry point, 🔴 bottom line < 512 characters (official 1024/1536 truncation); over-length split when_to_use（< 128） |
| 3 | references only one level deep | nesting causes incomplete head pre-read information |
| 4 | eval before docs | solve real problems rather than imagined ones |
| 5 | main body in positive phrasing, only necessary hard guardrails keep counterexamples paired with positive examples | matt paradigm Negation: state the target behavior so the forbidden behavior is never mentioned; counterexamples become chapters to catch missed failure modes |
| 6 | consistent terminology + forward-slash paths + no voodoo constants | cross-platform + maintainable |
| 7 | token lifecycle awareness | auto-compaction retains the most recent 5000 tokens before invoke, 25000 tokens total shared across skills, in a multi-skill session old skills get dropped——no error message, the hardest-to-debug zero-visibility failure |
failure handling (trigger → first-line fix → fallback if still failing)
high-frequency failures inlined; full 22 items on the creation side see references/anti-patterns.md。
| trigger condition | first-line fix | fallback if still failing |
|---|---|---|
| skill written but not triggered | description too broad/missing key terms → add words users would say + narrow the boundary | run a discoverability check to see if it is listed; if not listed, check whether name/description contains reserved words or exceeds 512 truncation |
| changed SKILL.md but it did not take effect | an already-invoked session keeps the old version resident → open a new session or re-invoke | confirm you changed the loaded path (not a references copy);disable-model-invocation requires /name re-trigger |
| in a multi-skill session this skill's behavior is lost | 25000 tokens shared across skills, old invokes dropped by compaction → slim down SKILL.md, split details into references | still lost after shrinking to ≤500 lines → move key instructions up into the top 5000-token retention window |
| reference not fully read | nested references cause head -100 truncation → flatten to only one level deep |
add a table of contents at the top of references >100 lines |
| 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 |
| judge disagreement is large | add a 3rd judge or switch to full_test actual measurement | mark as "evaluation untrustworthy", human review |
| dry_run > 30% | add full_test (spawn a real sub-agent to run the test prompt) | evaluation invalid, only give suggestions without changing the board |
| trigger word change breaks downstream | roll back the trigger word, add keywords in the body | create a new skill instead of modifying in place (breaking change) |
| structure/trigger correct but output goes off track | missing failure mode encoding → add dim3 if-then three-part form + check residual blacklist and convert to positive | run /grilling red-team to find missed failure modes |
| runtime red light hit | P0 fix runtime drift first (pin down wording → neutral phrasing) | change badge/install path to "Agent Skills Standard + multi-runtime" three-layer neutral |
Anti-pattern guardrails (positive by default, keep only necessary hard guardrails)
Positive phrasing by default: This section writes "correct practices", not a "don't do Y" list. Only the followinghard guardrails that cannot be positivizedkeep counterexamples, each must be paired with a positive example (matt paradigm Negation). Creation side P0-P3, 22 total, see references/anti-patterns.md。
Optimize correct practices(positive by default, follow this and it's correct):
- spawn an independent sub-agent for scoring, separate the writer from the judge (avoid optimism bias, LLM-as-judge 46.4% accuracy).
- Before Phase 1 scoring, prepare 2-3 test prompts (dim8 weight 23%, no prompt means no scoring).
- Change only 1 dimension or 1 related cluster per round (keep attribution clear).
- At least 1 full_test actual measurement (dry_run does not count as full marks).
- Use 🔴 / 🛑 visual markers for checkpoints (LLMs scan markers with priority over "must" semantics).
- Use a three-part structure for failure branches (trigger / first-line fix / fallback).
- Stop when the ceiling is hit: break when Δ < 2 for 2 consecutive rounds (don't force the round count).
- When changing the subagent body, require tool failures to be explicitly marked
[工具失败:原因](to prevent the main conversation from consuming an erroneous summary). - A full rewrite still goes through the Phase 3 gate (preserve attribution + prevent break).
- runtime wording is neutral (badge + wording are cross-runtime universal, to prevent other agents from refusing to install).
Rejected framings (rejected patterns + reasons + positive examples)
The following framings are explicitly rejected; they are written out so the agent knowswhy it cannot be written this way—this is not a blacklist; each has been converted into the positive practice above, and only the reason is kept here:
| Rejected framing | Reason for rejection | Positive example |
|---|---|---|
| "Self-evaluate and self-revise in the same context" | Optimism bias; the writer cannot score objectively | spawn an independent sub-agent for scoring |
| "Give a high score just because the test ran well" | dim8 without a prompt is scoring out of thin air | Prepare 2-3 prompts before scoring |
| "Change multiple dimensions in one round" | Attribution fails; cannot tell which dimension had an effect | 1 dimension or 1 related cluster per round |
| "Use 'must' instead of visual markers" | LLMs scan markers with priority over semantics | 🔴 / 🛑 visual markers |
| "Two-column fallback (symptom/solution)" | Missing fallback path, no third layer | Three-part structure (trigger/first-line/fallback) |
| "Force MAX_ROUNDS" | over-engineering | Stop when Δ<2 for 2 consecutive rounds |
| "Bare 'don't do Y' blacklist" | Negation backfire effect: naming a forbidden behavior makes it more available | Main body positive; any remaining counterexample must be paired with a positive example |
Verification checklist
Check item by item before releasing the artifact; for the complete 5 groups on the creation side see references/validation-checklist.md. Optimization side: 9-dimension scoring complete (line-number references) · runtime red-light scan run · related-cluster weaknesses identified · 🔴 diagnostic table confirmed by user · held-out test (should/should-not/edge) · independent sub-agent blind evaluation (≥2 judges or 1 full_test) · dry_run < 30% · Δ>0 strict improvement · apply only after passing the gate + git branch isolation · trigger word changes marked as breaking · summary report.
Honesty Boundaries (no self-praise, real limitations)
- Targets the Claude ecosystem (Agent Skills standard); cross-platform migration requires adjusting the trigger mechanism.
- The 9-dimension rubric / HL-1~4 are validated only on darwin-skill's own test set(testing itself with questions it wrote itself), not peer-reviewed, no third-party benchmark. Fine-grained quality difference is not trustworthy—important decisions must be human-reviewed.
- Research sources include 3 self-media platforms(Medium/LinkedIn/Substack), no independent third-party reproduction; anti-pattern frequencies are a subjective summary.
- validation gate self-reference paradox: the core claim is validation-gated, but when the real skill harness + judge swarm are insufficient it almost inevitably degrades to dry_run, and the core mechanism is hard to validate by its own full_test. Honest positioning:a strong diagnostic checklist + validation-gated discipline, a weak validation engine—this is the ceiling of text-space optimization, relying on the full_test ratio + human review as a backstop, and no external tool can bypass it.
- Covers agent.md but has less experience than skill: the subagent dimension table is a design derivation, with fewer real-world samples than skill.
- The domain/topic-perspective distillation methodology is already built into Process A (dimension-based research + triple verification); deep autonomous scoring + visualized result cards are already built into Process B, and no longer link out to other skills. Only persona role-play DNA (expression tone / personality simulation) is out of scope.
Research Sources
| File | Dimension | Primary Source |
|---|---|---|
| frontmatter-spec.md | Full table of 16 frontmatter fields + project bottom line | code.claude.com/docs/zh-CN/skills (official first-party) |
| dimensions.md | Full table of 9-dimension rubric + HL-1~4 + related clusters | darwin-skill local + SkillLens |
| workflow.md | SkillOpt validation-gated loop + git ratchet + judge independence | SkillOpt (arXiv 2605.23904) + darwin |
| subagent-authoring.md / anti-patterns.md / validation-checklist.md | subagent design / 22 anti-patterns / pre-release checklist | Official + community + darwin dim9 |
| skill-quality-checklist.md | skill quality fundamentals (predictability / information layering / when to split / pruning / leading words / 6 failure modes) | ask-matt /writing-great-skills same source |
| research/01-06.md | Official specs / academic / community / cross-platform / anti-patterns / toolchain | platform.claude.com / anthropics/skills / etc. |
| optimizer-sources.md | 3 papers + darwin citations + empirical data | arXiv / GitHub (verified via curl on 2026-06-26) |
Information source blacklist (always excluded): Zhihu, WeChat Official Accounts, Baidu Baike.
Boundaries of the three checklist-type files(to prevent duplicate definitions, single source of truth):skill-quality-checklist.md = the meta-methodologymeta-methodologywhen writing a skill (predictability / information layering / pruning / converting negation to positive / quality-gate verification method, answering "how to think, how to verify");validation-checklist.md = pre-releaseitem-by-item checklist (answering "what to check before going live", the main entry point of Phase 5 Step 2);optimization-log.md = Process B historical optimization roundrecord table (answering "what was changed before, and why it succeeded/failed", Phase 4 rejected-edit buffer, neither a criterion nor a methodology). The three define their own exclusive content without repeating each other, and cross-file references use only pointers (e.g. validation-checklist.md §Trigger Accuracy → skill-quality-checklist.md §Quality-Gate Verification Method).