self-learning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Self-learning: harvest golden paths into skills

自我学习：将黄金路径转化为技能

This skill turns something you just figured out the hard way into a reusable Agent Skill, so the next session — yours or a teammate's — starts already knowing the proven route instead of rediscovering it from scratch.

It is a meta-skill: it doesn't do the work, it captures how work got done. It's tool-neutral — it works with any agent that reads the Agent Skills format (e.g. Claude Code and Codex, which both load

SKILL.md

skills natively). Where a step differs by tool, the generic version comes first and any tool-specific detail is only an example.

本技能可将你刚刚费力摸索出来的方法转化为可复用的Agent Skill，让下一次会话——无论是你自己还是队友的——直接从已验证的路径开始，无需从零重新探索。

它是一种元技能：它不直接执行工作，而是记录工作完成的方法。它具备工具无关性——可与任何支持Agent Skills格式的代理配合使用（例如Claude Code和Codex，它们原生支持加载

SKILL.md

技能）。当步骤因工具不同而存在差异时，会优先给出通用版本，工具特定细节仅作为示例。

Recognize the moment

识别合适时机

Watch for these signals during normal work. Any one of them is a cue to harvest:

A task only worked after several attempts, wrong turns, or a correction from the user. The successful path is worth more than the failures around it.
You discovered project-specific facts the agent didn't know up front: where creds/env vars live, which selector or backend talks to a service, a non-obvious command, a required sequence, a gotcha that defies the obvious assumption.
It's an operational workflow likely to recur: reach the dev/prod DB, deploy, run migrations, seed data, verify a change live, run one specific test path, rotate a key, tail the right logs.
The user signals it explicitly: "remember this", "save this as a skill", "don't make me re-explain this next time".

Act on the cue immediately — don't ask for permission first, whether the user requested it or you noticed it yourself. Harvest the skill, then tell the user what you captured and where (step 5). They can always edit or delete it.

在日常工作中留意以下信号，只要出现其中任何一个，就可以开始捕获技能：

某项任务经过多次尝试、走了弯路或得到用户纠正后才成功。成功路径的价值远大于过程中的失败尝试。
你发现了代理原本不知道的项目特定信息：凭证/环境变量的存储位置、与服务交互的选择器或后端、不常见的命令、必须遵循的操作顺序、违背常规假设的陷阱。
这是一个可能重复执行的操作工作流：连接开发/生产数据库、部署、运行迁移、初始化数据、验证线上变更、运行特定测试路径、轮换密钥、追踪正确的日志。
用户明确发出指令：「记住这个」「把这个保存为技能」「为这个创建一个技能」「下次别让我再解释一遍」。

立即响应信号——无需先征得许可，无论用户是否明确请求，或是你主动识别到时机。捕获技能后，告知用户你捕获的内容及其存储位置（步骤5）。用户随时可以编辑或删除该技能。

Skill, memory, or skip?

技能、记忆还是跳过？

Not every lesson deserves a whole skill — triage first, so you don't bloat the skills list with one-liners:

A multi-step, reusable procedure or workflow (how to deploy, reach the DB, run the migration dance, verify live) → harvest it as a skill using the procedure below.
A single standalone fact or one-line correction (an env var name, a path, one gotcha) → if your harness has a lightweight memory/notes facility (e.g. a
```
MEMORY.md
```
index), record it there instead; a whole skill is overkill for a one-liner. With no such facility, make a small skill.
A genuinely one-off thing unlikely to recur → skip it.

When you do harvest, capture the failures too, not just the win: the approaches you ruled out and why often save more time next session than the golden path itself.

并非每个经验都值得单独成为一个技能——先进行分类，避免技能列表被大量单行内容臃肿：

多步骤、可复用的流程或工作流（如何部署、连接数据库、完成迁移流程、验证线上变更）→ 按照以下流程捕获为技能。
单个独立事实或单行修正（环境变量名称、路径、单个陷阱）→ 如果你的工具具备轻量级记忆/笔记功能（例如
```
MEMORY.md
```
索引），则记录在该位置即可；单行内容无需单独创建技能。如果没有此类功能，则创建一个小型技能。
真正的一次性操作，不太可能重复发生→ 跳过。

捕获技能时，也要记录失败尝试，而不仅仅是成功路径：被排除的方法及其原因，往往比黄金路径本身更能为下次会话节省时间。

Promotion rule: don't enshrine guesses

晋升规则：不要固化猜测

A skill is authoritative — the next session trusts it without re-deriving it — so hold promotion to a high bar. Only write a skill when all three hold:

A passing check. The path was actually verified — a test passed, the command exited clean, the repro reproduced, the build went green. Record what the check was. "Seemed to work" is not a passing check.
A named failure pattern. You can name the failure this path avoids or diagnoses (e.g. "stale build cache → phantom type errors"), not a vague "sometimes it breaks".
At least one ruled-out dead-end. A concrete approach you tried and eliminated, with the reason.

If any is missing, it isn't a skill yet — leave a tentative note in memory (marked unverified) or skip it. This keeps confident guesses out of the skill set.

技能是权威性的——下一次会话会直接信任它，无需重新推导——因此要严格把控技能的创建标准。只有同时满足以下三个条件时，才能创建技能：

通过验证。路径已实际验证——测试通过、命令执行成功、复现问题成功、构建完成。记录验证方式。「似乎可行」不算通过验证。
明确的失败模式。你可以命名该路径避免或诊断的失败类型（例如「陈旧构建缓存 → 虚假类型错误」），而非模糊的「有时会出错」。
至少一个被排除的死胡同。你尝试过并排除的具体方法，以及排除原因。

如果缺少任何一个条件，则还不能创建技能——可以在记忆中留下暂定笔记（标记为未验证）或直接跳过。这能避免将不确定的猜测纳入技能集合。

Harvest procedure

捕获流程

1. Apply the promotion rule (above). Passing check + named failure pattern + one ruled-out dead-end — or it isn't a skill: note it in memory or skip. Don't proceed on a confident guess.
2. Choose scope and name yourself using the heuristics below — don't stop to ask. Default to project scope; pick a clear, specific
```
name
```
.
3. Dedupe. Look for an existing skill to UPDATE rather than duplicate. List your agent's skills directories — the project one and the user-level one (e.g. Claude Code
```
.claude/skills
```
+
```
~/.claude/skills
```
, Codex
```
.codex/skills
```
+
```
~/.codex/skills
```
, or your tool's equivalent). Also glance at any memory/notes index — a fact already there may just need a pointer.
4. Distill the golden path from THIS conversation before delegating — while it's fresh in your head: the exact working commands, file paths, env var names, the required order, and (just as important) the dead-ends to avoid. This is the raw material for the write.
5. Delegate the write to a subagent that inherits this conversation if your tool supports one, or do it inline otherwise — see below. The conversation is the only place the golden path lives, so whoever writes it must have that context.
6. When the write is done, relay the new skill's path to the user and, in one line, what it captured.

1. 应用晋升规则（如上所述）。必须同时满足通过验证、明确的失败模式、至少一个被排除的死胡同——否则不能创建技能：记录在记忆中或跳过。不要基于不确定的猜测继续操作。
2. 自行选择范围和名称，遵循以下启发式规则——无需停下来询问。默认使用项目范围；选择清晰、具体的
```
name
```
。
3. 去重。查找是否已有可更新的现有技能，而非创建重复技能。列出代理的技能目录——项目目录和用户级目录（例如Claude Code的
```
.claude/skills
```
+
```
~/.claude/skills
```
，Codex的
```
.codex/skills
```
+
```
~/.codex/skills
```
，或你的工具对应的目录）。同时查看任何记忆/笔记索引——已存在的事实可能只需要一个指向它的链接。
4. 在委托前提炼本次会话中的黄金路径——趁记忆清晰：准确的有效命令、文件路径、环境变量名称、必须遵循的顺序，以及（同样重要）需要避免的死胡同。这是编写技能的原始素材。
5. 委托编写任务：如果你的工具支持继承本次会话上下文的子代理，则委托给它；否则直接在当前流程中执行——详见下文。黄金路径仅存在于本次会话中，因此编写技能的主体必须具备该上下文。
6. 编写完成后，向用户告知新技能的路径，并用一句话概括捕获的内容。

Scope: project vs global

范围：项目级 vs 全局级

Project (the repo's skills directory — e.g.
```
.claude/skills/
```
,
```
.codex/skills/
```
): the path is specific to THIS codebase — its env vars, its build/release steps, its schema, its quirks. Most harvested operational skills are project-scoped, and they ship to the team via git.
Global (your user-level skills directory — e.g.
```
~/.claude/skills/
```
,
```
~/.codex/skills/
```
): the path generalizes across projects — a personal tool, a cross-repo habit, or a workflow tied to your machine rather than to one repo.

When unsure, prefer project — an over-shared global skill triggers in repos where its commands don't apply.

项目级（仓库的技能目录——例如
```
.claude/skills/
```
、
```
.codex/skills/
```
）：路径仅适用于当前代码库——其环境变量、构建/发布步骤、架构、特殊特性。大多数捕获的操作技能都是项目级的，会通过Git同步给团队成员。
全局级（用户级技能目录——例如
```
~/.claude/skills/
```
、
```
~/.codex/skills/
```
）：路径适用于多个项目——个人工具、跨仓库习惯，或与你的机器而非单个仓库绑定的工作流。

不确定时，优先选择项目级——过于宽泛的全局技能可能会在不适用的仓库中被触发。

Delegate the write (subagent, or inline)

委托编写任务（子代理或当前流程）

Whoever writes the skill needs THIS conversation's context — it's the only place the golden path lives. Two equally valid ways to run it:

Inline — do the steps yourself in the main loop. Always works.
Subagent — if your tool can delegate to a subagent that inherits this conversation, use it to keep the harvesting work out of your main context. (Claude Code: a skill with
```
context: fork
```
. Codex and others spawn subagents their own way.) Don't hand it to a fresh agent with no context — it would start blank with nothing to extract.

Either way it over-reaches by default, so box it in tightly. Follow this brief (fill in the bracketed parts) — hand it to the subagent, or work through it yourself inline:

You are harvesting a skill. Your ONLY job is to write a new Agent Skill capturing the golden path we just worked out in this conversation: [one-line description of the workflow].

Hard rules:
Write ONLY under
[skills dir]/[skill-name]/
. Do NOT modify project source, run builds, install anything, or resume the original task.
First read
[this-skill-dir]/references/skill-authoring.md
and
[this-skill-dir]/assets/SKILL.template.md
, then author
SKILL.md
to that spec, plus any
references/
or
assets/
files the procedure warrants.
Capture the PROCEDURE — commands, paths, the required order, gotchas — not a one-off answer. Generalize so it works next time.

Capture the FAILURES too: the approaches we ruled out and why, so the next session skips the dead-ends. Put them in a "What didn't work" section.

Enforce the promotion rule: the skill must record the passing check that verified this path, name the failure pattern it addresses, and list at least one ruled-out dead-end. If any is missing (e.g. nothing was actually verified), STOP and report it isn't promotable — leave a tentative memory note instead of writing the skill.

NEVER write secret VALUES (passwords, tokens, connection strings, API keys). Record only WHERE to find them: the env var name, the selector function, the MCP tool, the secret manager. Reproducing a secret into a skill file leaks it.

Self-validate before finishing (see the checklist in skill-authoring.md).

Report back: the absolute path you wrote and a one-line summary. Then STOP — do not pick the original task back up.

编写技能的主体需要本次会话的上下文——黄金路径仅存在于此。有两种可行的方式：

当前流程内执行——在主循环中自行完成步骤。始终有效。
子代理——如果你的工具可以委托给继承本次会话上下文的子代理，则使用它来将捕获工作从主上下文分离出来。（Claude Code：使用
```
context: fork
```
的技能。Codex和其他工具会以各自的方式生成子代理。）不要将任务交给没有上下文的全新代理——它会从零开始，无法提取任何内容。

无论哪种方式，默认情况下都可能超出范围，因此要严格限制。遵循以下简短说明（填写括号中的内容）——将其交给子代理，或自行在当前流程中执行：

你正在捕获一个技能。你的唯一任务是编写一个新的Agent Skill，记录我们在本次会话中摸索出的黄金路径： [工作流的一句话描述]。

严格规则：
仅在
[技能目录]/[技能名称]/
下编写。不得修改项目源代码、运行构建、安装任何内容，或继续执行原始任务。
首先阅读
[当前技能目录]/references/skill-authoring.md
和
[当前技能目录]/assets/SKILL.template.md
，然后按照该规范编写
SKILL.md
，以及流程所需的任何
references/
或
assets/
文件。
记录流程——命令、路径、必须遵循的顺序、陷阱——而非一次性答案。进行通用化处理，确保下次仍能生效。

同时记录失败尝试：我们排除的方法及其原因，让下一次会话可以跳过这些死胡同。将这些内容放在「无效方法」部分。

执行晋升规则：技能必须记录验证该路径的通过标准、它解决的失败模式名称，以及至少一个被排除的死胡同。如果缺少任何一项（例如未实际验证），则停止操作并报告无法晋升为技能——改为在记忆中留下暂定笔记，而非编写技能。

绝对不要写入敏感值（密码、令牌、连接字符串、API密钥）。仅记录其位置：环境变量名称、选择器函数、MCP工具、密钥管理器。将敏感值写入技能文件会导致泄露。

完成前进行自我验证（参见skill-authoring.md中的检查清单）。

反馈结果：你编写的绝对路径和一句话总结。然后停止操作——不要继续执行原始任务。

Gotchas

注意事项

Secrets never go in a skill file. Skills get committed and open-sourced. Point to where the secret lives; never reproduce the value. This is the single most important rule in this skill.
name
must equal the directory name, and be lowercase
```
a-z
```
/
```
0-9
```
/hyphens only — no leading, trailing, or doubled hyphens. A mismatch means the skill won't load.
Whoever writes the skill over-reaches by default (a subagent especially). That's why the brief above forbids touching project source or resuming the task — keep it boxed to the skills directory.
Don't duplicate. If a near-identical skill (or memory) already exists, update it instead of spawning a second one that competes to trigger.
Capture procedures, not answers. "Join orders to customers for EMEA" is useless next time; "how to find the right tables and build the query" is the skill. See
```
references/skill-authoring.md
```
.
Keep
SKILL.md
tight (< 500 lines, < ~5000 tokens). Push detail into
```
references/
```
and tell the reader when to load each file.

For the full authoring spec, see references/skill-authoring.md. The fill-in template is assets/SKILL.template.md.

敏感值绝对不能写入技能文件。技能会被提交到版本控制系统甚至开源。只需指向敏感值的存储位置；绝对不要复制其内容。这是本技能中最重要的规则。
name
必须与目录名称一致，且只能使用小写
```
a-z
```
/
```
0-9
```
/连字符——不能有前导、尾随或连续的连字符。不匹配会导致技能无法加载。
编写技能的主体默认可能超出范围（子代理尤其如此）。因此上述说明禁止修改项目源代码或继续执行原始任务——严格限制在技能目录内操作。
不要重复创建。如果已有几乎相同的技能（或记忆），则更新它，而非创建第二个可能冲突的技能。
记录流程，而非答案。「将EMEA地区的订单与客户关联」下次毫无用处；「如何找到正确的表并构建查询」才是技能。参见
```
references/skill-authoring.md
```
。
保持
SKILL.md
简洁（少于500行，约5000个令牌）。将详细内容放入
```
references/
```
，并告知读者何时加载每个文件。

完整的编写规范请参见 references/skill-authoring.md。填充模板为assets/SKILL.template.md。