aikey-skillify: solidify a working approach into a skillThis skill was originally named
/zmm-…, renamed as of v1.0.0 to AI KEY（/aikey-…); the old name is no longer updated. For upgrading as an existing user, see README。
First read config.yaml(if unreadable → state clearly that the configuration is missing and stop; do not use example values to pretend they are the user's settings), then read aikey/references/交互规范.md（🔴 Don't just read it once and consider it done: at wrap-up follow the §4 trio — Recap · Before/After · next step as numbered options; if information is missing, per §4 usemultiple-choice questionsto ask,only one question at a time; for inapplicable cases see §5), then read aikey/references/家族公约.md, then read memory {config.paths.memory}/aikey-skillify/ + _通用/。
This skill's built-in criteria are in references/规则卡.md(criterion / why / how to check / strength); read them once before starting;{vault} when a corresponding rule file exists there, the vault takes precedence and the rule card is the baseline.
🔴 Gate: if it hasn't been run successfully, it must not be solidified
This skill only distills from "processes that have already produced the correct result". On entry, check three things first; if any is missing → explain what is missing and stop:
| What to check | If not satisfied |
|---|---|
| Was something actually completed in this session | Only discussion, no output → "there is nothing to solidify yet; finish the work first" |
| Has the result been verified(user approval / data / checkable output) | Not verified → "this approach has not been proven effective; solidifying it is equivalent to writing unverified experience into rules" |
| Will it happen again | One-off → "this is unlikely to recur; the benefit of solidifying it is negative" — you may keep just a record instead of making a skill |
⚠️ Do not skip the gate just because the user says "turn it into a skill". What the user wants is to save effort next time, not one more inaccurate skill.
Where to distill from: three sources, ordered by reliability
- The actual process of this session — most reliable. It was really done, with output and feedback.
{config.paths.memory}The skill memory in — corrections and effective methods accumulated before.- The user's spoken "how I usually do it" —— 🔴 Least reliable. People's descriptions of their own process often differ from what they actually do. It can only serve as a clue; you must go back to ① or ② to find evidence; if none is found, mark it "unverified" in the deliverable.
When the three conflict, ① takes precedence, and write the conflict itself into the skill ("he says X, actually does Y, Y takes precedence" is often the most valuable rule).
Five steps
Step 1 · Write the problem contract
反复出现的问题：
什么情境下会遇到：
这次是怎么解决的（按实际发生的顺序，不是理想顺序）：
产出物是什么：
凭什么算做完了（可检查的证据，不是「感觉good」）：
明确不处理的邻近问题：
🔴 "What counts as done" cannot be written as checkable evidence → stop. A skill without a completion criterion — next time nobody knows whether it ran correctly.
Step 2 · Translate "works well" into observable behaviors
Users will say "write it naturally" or "judge accurately".These cannot go into the skill; they must be translated into something checkable:
必须做到（可观察）：
禁止出现（可观察）：
允许它自己发挥的部分：
最容易出的那个错：
出错时应该怎样（停下问 / 降级 / 明说做不到）：
Contrast: "judge accurately" ❌ → "candidates must be selected from the actually listed options; anything not listed must not be invented" ✅
Step 3 · Set confidence levels for the criteria
The family convention requires every conclusion to be labeled with a source.Every rule in a new skill must carry a level：
| Level | When to use | How to write it |
|---|---|---|
| 🟢 Measured | Backed by a specific case in this session or in history | State the cost clearly: "measured cost: full rewrite" |
| 🟡 Inferred | Derived from measurements but not directly verified | Must add a sentence: "if this is wrong, where is it most likely wrong" |
| ⚪ Guess | Just sounds right | By default, do not write it into the skill. If you must write it, label it definitively, and it cannot be used as a criterion |
🔴 Do not write 🟡 and ⚪ in the tone of 🟢. This is the most common mistake in the family.
Step 4 · Generate the skill directory and self-check
aikey-<名字>/
SKILL.md 入口：门禁 + 主流程 + 停止条件 + 红线
references/ 条件性细节（只在某些情况下才读的）
scripts/ 重复且确定的活（能用脚本就别让模型算）
Keep the main entry light: SKILL.md should contain only what must be run every time; branch details go into references/。
Self-check list, go through item by item:
- frontmatter has
name(ASCII slug, consistent with the directory name),description(including Chinese trigger words),version - description clearly stateswhen it should be used, not just what it can do
- has gates: under what circumstances itshould notbe used, and when to stop
- every rule carries a 🟢🟡⚪ level
- has a stop condition: how far is considered done
- has read the family convention and interaction spec, and ends with numbered options
- with the existing 20 skillshas no responsibility overlap — if there is overlap, modify that one instead of creating a new one
🔴 The last item is the easiest to miss. First run bash aikey/scripts/list-skills.sh to look at the existing ones, and explicitly state "what the boundary between it and aikey-xxx is". If you cannot state it clearly → do not create a new one.
Step 5 · Run it once before delivery (passing self-check does not mean it works)
The checklist above is all static items: files exist, fields are complete, rules have levels.If a skill goes into the skill directory without ever having been run after being written, you only discover next time it is actually used that the gates cannot run — this is the same discipline as "people who write code cannot approve their own code". So before delivery, climb the ladder below, and at whichever level you reach, you may only speak the words for that level:
| Level | What was done | What you are allowed to say |
|---|---|---|
| 0 | Static self-check passed | "The files are complete."You may not say "it works" |
| 1 | Take a real input, in anewly opened context , run through it once according to SKILL.md, and the output meets the completion evidence of the problem contract | "The main scenario has been run through" |
| 2 | Ran a set of samples (see below), including at least onenear-neighbor counterexample, the executor has not seen the answer | "Can tell what should and shouldn't be done" |
| 3 | After revising a version, rerun the same sample set; hit rate no lower than the previous version | "This version didn't regress" |
How to build samples(put in the skill directory evals/, travels with the skill):
sample-NN-<描述>.md: input given to the executor.sample-NN-答案.md: given only to the grader; list two tables, "must catch" and "must not false-positive", 1 point per item- At least three categories per set:positive examples(should trigger and should catch) · boundary(right on the threshold) · near-neighbor counterexamples(look similar but belong to a neighboring skill, or look like a problem but aren't) — the trigger words of the 22 skills overlap with each other; near-neighbor counterexamples guard against false triggering
- If a rule grew out of one specific case, add one morechanged-topicsample: put the same flaw into another industry, another topic — can it still catch it? A rule that only holds on the original case was a fix for that one time, not yet a rule
- For samples, preferreal material where the user can tell right from wrong at a glance. On unfamiliar material, whether the result is right or wrong, nobody can say for sure
- Record results in
evals/results/sample-NN-v<版本>.md，evals/README.mdas a table: sample · version · hits / full score · false positives · conclusion.The version number points to SKILL.md'sversion; it must not be called "latest version" - Run by hand first, don't write a runner. Three samples run by hand for ten minutes is enough
When a run fails, classify first, then fix(without classifying, everything just gets more rules added to SKILL.md, longer and longer):
| Where it fails | What it looks like | Where to fix |
|---|---|---|
| Goal | The work is done quite carefully, but it's not what the user asked for (the user wants "is anyone watching", it's evaluating "is it rigorous") | Go back to Step 1 and rewrite the problem contract.Don't touch the rules — the goal is off; the more rules you add, the further off it gets |
| Expression | The judgment is right, but the user can't understand it or doesn't know what to do next (internal codenames, step names leaked into the output) | Only change the output format and wording; don't touch a single word of the judgment logic |
| Instruction | The rule is there, but the executor understood it as something else | Change the wording of that rule, add a counterexample |
| Trigger | What should enter didn't / what shouldn't enter did | Change the trigger words in description and "when not to use it" |
| Input | The sample itself is missing something; nobody could do it | Change the sample, or add "stop if X is missing" to the gate |
| Criterion | The answer itself is disputed | First align on the answer with the user, then touch the skill |
| Fluctuation | Same input gives different results twice | The rule gave room but no criterion; add a criterion |
When the user says "wrong", first break it into four lines before touching any files:
错的是哪一句：（把技能的原话抄出来，不转述）
实际会发生什么：（真实的观众 / 客户 / 数据会怎么反应）
它没看到的那个区别：
以后碰到同类，先看什么：
The fourth line is the criterion for the new rule; the first three lines go into the rule card's "example" and "why" respectively. 🔴 Can't write the fourth line → this is a one-off fix: just fix this output, don't add a rule to the skill. A "rule" that only fixes this one case will still fail next time with a different subject, and it makes the skill longer. After writing, verify once with a sample on a different subject (see "How to build samples" above).
🔴 The same failure has been revised three times and is still relying on "adding one more rule for this sample" — stop: that's not a missing rule, it's that this skill's boundary is drawn wrong. Go back to Step 1.
Ready-made examples:aikey-flow/evals/(one version run before and after the redesign; results for both v0.1.0 and v0.2.0 are available),aikey-resonate/evals/、aikey-review/evals/(created 2026-09-06).
Delivery boundary
By default, only make it usable locally: generate the directory, put it in the user's skills directory, and tell them how to invoke it.
🔴 Publishing is a separate matter and must only be done when the user explicitly asks. This includes: pushing to a public repository, publishing to ClawHub / SkillHub, and adding it to a packaged release. If the user hasn't said "publish it," don't touch any of this — once a freshly formed skill enters a public channel, the cost of changing it is much higher than keeping it local.
Stop conditions
Stop when any of the following is met; don't keep adding:
- The skill runsin a new contextthrough the scenario in the problem contract, and the output meets the completion evidence (Step 5, level 1 or above)
- The user says it's enough
- You find it overlaps with an existing skill → modify that one, don't create a new one
- You find the gate wasn't passed → explain why, don't force it
Wrap-up
Per 〈Interaction Spec · IV〉: Recap (what was solidified) · Before/After (what would have to be rethought next time without this skill) · Next steps as numbered options.
Also write a memory entry to {config.paths.memory}/aikey-skillify/: what was solidified this time, how the gate was passed, and whether any overlap was hit.Check for duplicates first。