self-improving-agent

自我改进 Agent

何时使用此技能：

• 完成重要任务后（任务后反思）
• 发现自己在重复执行多步骤工作流时
• 人类纠正了你的行为，需要保留这一修正时
• AGENTS.md 中的代码库地图已过时时
• 工作会话结束时

---

第 1 步：诊断需要改进的方面

完成工作后，问自己以下问题：

1. 我是否偏离了方向？ 我是否花时间搜索了本应列在代码库地图中的文件？

   • → 更新 AGENTS.md 中的代码库地图

2. 我是否被纠正了？ 人类是否告诉我应该换一种方式做事？

   • → 将修正添加到 AGENTS.md 的本地规范、护栏或模式与注意事项中

3. 我是否重复了某个工作流？ 我是否遵循了以前执行过（或很可能会再次执行）的多步骤流程？

   • → 创建一项新技能（见下方第 3 步）

4. 是否有事情让我意外？ 我是否发现了注意事项、已弃用的 API 或不明显的耦合关系？

   • → 将其添加到 AGENTS.md 的模式与注意事项中

5. AGENTS.md 是否过时？ 规范、入口点或约定是否已与实际代码库不符？

   • → 立即更新过时的部分

如果以上情况都不适用，则无需采取行动。不要为了创建文档而创建文档。

---

第 2 步：更新 AGENTS.md

更新 AGENTS.md 时，请遵循以下规则：

更新代码库地图

1. 阅读 AGENTS.md 中现有的地图。
2. 使用 find 或 ls（不要递归遍历整个目录树）查看实际的顶层结构。
3. 只更新已发生变化的部分。不要重写整份地图。
4. 重点关注：入口点、目录用途、配置文件、测试位置。

添加规范或护栏

1. 将规则写成简短的祈使句——尽可能控制在一行。
2. 将其放在正确的部分：
   • 本地规范 → 如何在此仓库中构建、测试、运行或编写代码
   • 护栏 → Agent 绝对不能做的事
   • 模式与注意事项 → 关于代码库的不明显发现
3. 如果一项修正与现有条目矛盾，请更新现有条目，而不是添加重复条目。

质量检查

• 保持条目简洁。Agent 每次会话都会阅读这些内容——简洁的好处会不断累积。
• 有实际条目后，删除占位符／示例条目（斜体内容）。
• 不要添加通用建议。每条内容都应针对这个仓库。

---

第 3 步：创建新技能

发现值得记录的可重复工作流时，请使用此流程。

决策：这是技能还是 AGENTS.md 条目？

Is it a multi-step procedure with a clear output?
  → YES → Skill
  → NO  → AGENTS.md entry

Is it specific to HOW this repo works (norms, navigation)?
  → YES → AGENTS.md entry
  → NO  → Skill

Am I unsure?
  → Start as an AGENTS.md entry. Promote to skill if it grows.

创建技能

1. 选择名称。 使用体现任务的动词-名词格式：debug-ci、draft-release-notes、run-migration 等。

2. 创建文件夹和文件：

   skills/<skill-name>/SKILL.md
   

3. 按照以下结构编写 SKILL.md：

   ---
   name: <skill-name>
   description: <one-line description of what job this skill does>
   ---
   
   # <Skill Name>
   
   > **When to use:** <clear trigger condition>
   
   ## Steps
   
   1. <Step 1 — be specific and imperative>
   2. <Step 2>
   3. ...
   
   ## Output Contract
   
   <What "done" looks like. Be specific about format, location, and quality.>
   

4. 编写优质技能的关键原则：

   • 围绕要完成的任务来编写，而不是围绕工具（“调试 CI 故障”，而不是“使用 grep”）
   • 明确触发条件——Agent 何时应该使用此技能？
   • 定义输出约定——什么样的结果才算“完成”？
   • 如有帮助，可将优质输出示例作为素材加入（放在 skills/<name>/examples/ 中）
   • 步骤要具体明确，并使用祈使句——避免含糊的指示

5. 将新技能添加到 AGENTS.md 中的技能表：

   | [<skill-name>](skills/<skill-name>/SKILL.md) | <purpose> | <trigger> |
   

为技能添加脚本或素材

如果技能需要确定性执行（而不仅仅依靠 LLM 判断），请添加脚本：

skills/<skill-name>/
├── SKILL.md          # The playbook (always required)
├── scripts/          # Helper scripts for deterministic steps
│   └── validate.sh
└── examples/         # Reference outputs showing "good" quality
    └── example-output.md

在 SKILL.md 中引用这些脚本：“运行 scripts/validate.sh 以验证输出。”

---

第 4 步：确定范围——仓库本地、全局还是共享

Does this skill only matter for THIS repo?
  → Keep it in skills/ within this repo (repo-local)

Have I felt this pain in another repo too?
  → Promote to ~/.agent/skills/<name>/ (machine-global)
  → Copy the skill folder there

Does my team keep repeating this workflow?
  → Promote to a shared repo or registry (shared)
  → Move the skill folder into the team's shared skills repo

推广检查清单

将技能从仓库本地推广到全局时：

1. 从 SKILL.md 中移除特定于仓库的路径或引用。
2. 让指示足够通用，适用于任何项目。
3. 在不依赖原仓库上下文的情况下测试其是否有效。
4. 如果仓库本地版本包含特定于仓库的自定义内容，则保留该版本。

步骤 5：验证改进

完成任何更改（更新 AGENTS.md 或添加新技能）后：

1. 重新阅读更新后的文件。 内容是否清晰易懂？新启动的 Agent 会从中受益吗？
2. 检查是否存在矛盾。 新条目是否与现有内容冲突？
3. 检查内容是否臃肿。 文件是否太长？如果 AGENTS.md 超过约 200 行，请考虑：
   • 归档已不再适用的旧问题记录
   • 将详细流程移至技能中
   • 精简冗长条目
4. 提交更改，并使用清晰的提交说明：

   docs: update AGENTS.md with <what you learned>
   

   或

   feat: add <skill-name> skill for <job description>
   

---

应避免的反模式

❌ 不要	✅ 应该这样做
添加通用建议（“编写整洁的代码”）	添加仓库专属规则（“使用 pnpm，不要使用 npm”）
为一次性任务创建技能	为会重复执行的任务创建技能
任由 AGENTS.md 无限增长	清理过时条目，将流程移至技能中
编写含糊的技能步骤（“找出问题所在”）	编写具体步骤（“运行 npm test，查看第一个失败的断言”）
围绕某个工具创建技能	围绕要完成的工作创建技能
从共享/全局技能开始	从仓库本地技能开始，重复遇到问题后再推广

---

快速参考：复利循环

Work on task
    ↓
Complete task
    ↓
Reflect: Did I wander? Get corrected? Repeat a workflow? Discover a gotcha?
    ↓
    ├── Navigation miss     → Update Codebase Map
    ├── Behavior correction → Add to Local Norms / Guardrails
    ├── Repeated workflow   → Create a Skill
    ├── Surprise discovery  → Add to Patterns & Gotchas
    └── Nothing notable     → Move on
    ↓
Next task starts from a better baseline

“最有价值的技能，是观察自己如何工作的习惯。” 每次改进都会让未来的改进更容易。这就是 Agent 不断积累优势的方式。