self-improving-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Self-Improving Agent

自我改进型Agent

When to use this skill:

After completing a significant task (post-task reflection)

When you notice yourself repeating a multi-step workflow

When a human corrects your behavior and you need to persist the correction

When the codebase map in AGENTS.md is stale

At the end of a working session

何时使用该技能：

完成重要任务后（任务后复盘）

发现自己重复执行多步骤工作流时

人类纠正了你的行为，需要将该修正固化时

AGENTS.md中的代码库地图过时

工作会话结束时

Step 1: Diagnose What Needs Improving

步骤1：诊断需要改进的内容

Ask yourself these questions after completing work:

Did I wander? Did I spend time searching for files that should have been in the codebase map?
- → Update the Codebase Map in
```
AGENTS.md
```
Did I get corrected? Did the human tell me to do something differently?
- → Add the correction to Local Norms, Guardrails, or Patterns & Gotchas in
```
AGENTS.md
```
Did I repeat a workflow? Did I follow a multi-step procedure that I've done before (or will likely do again)?
- → Create a new skill (see Step 3 below)
Did something surprise me? Did I discover a gotcha, a deprecated API, or a non-obvious coupling?
- → Add it to Patterns & Gotchas in
```
AGENTS.md
```
Is the AGENTS.md stale? Do the norms, entry points, or conventions no longer match the actual codebase?
- → Update the outdated sections now

If none of these apply, no action is needed. Don't create artifacts for the sake of it.

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

我是否走了弯路？ 是否花费时间寻找本应在代码库地图中记录的文件？
- → 更新
```
AGENTS.md
```
  中的代码库地图
我是否被纠正过？ 人类是否要求我换一种方式做事？
- → 将该修正添加到
```
AGENTS.md
```
  中的本地规范、防护规则或模式与注意事项部分
我是否重复执行了某个工作流？ 是否遵循了之前做过（或可能再次执行）的多步骤流程？
- → 创建一个新的skill（见下方步骤3）
我是否遇到了意外情况？ 是否发现了注意事项、已弃用的API或不明显的耦合关系？
- → 将其添加到
```
AGENTS.md
```
  中的模式与注意事项部分
AGENTS.md是否过时？ 其中的规范、入口点或约定是否与实际代码库不符？
- → 立即更新过时的部分

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

Step 2: Update AGENTS.md

步骤2：更新AGENTS.md

When updating

AGENTS.md

, follow these rules:

更新

AGENTS.md

时，请遵循以下规则：

Codebase Map Updates

代码库地图更新

Read the current map in
```
AGENTS.md
```
.
Use
```
find
```
or
```
ls
```
(not recursive full-tree) to see the actual top-level structure.
Update only the parts that have changed. Don't rewrite the whole map.
Focus on: entry points, directory roles, config files, test locations.

阅读
```
AGENTS.md
```
中的当前地图。
使用
```
find
```
或
```
ls
```
（非递归全树扫描）查看实际的顶层结构。
仅更新已更改的部分，不要重写整个地图。
重点关注：入口点、目录作用、配置文件、测试位置。

Adding Norms or Guardrails

添加规范或防护规则

Write the rule as a short, imperative statement — one line if possible.
Place it in the correct section:
- Local Norms → How to build, test, run, or style code in this repo
- Guardrails → What the agent must NEVER do
- Patterns & Gotchas → Non-obvious discoveries about the codebase
If a correction contradicts an existing entry, update the existing entry rather than adding a duplicate.

将规则写成简短的祈使句——尽可能用一行表述。
将其放在正确的部分：
- 本地规范 → 此代码库中构建、测试、运行或编写代码的方式
- 防护规则 → Agent绝对不能做的事
- 模式与注意事项 → 关于代码库的非明显发现
如果某个修正与现有条目冲突，请更新现有条目，而非添加重复内容。

Quality Checks

质量检查

Keep entries concise. Agents read this every session — brevity compounds.
Remove placeholder/example entries (italicized) once real entries exist.
Don't add generic advice. Every entry should be specific to this repo.

保持条目简洁。Agent每次会话都会阅读此文档——简洁性会带来复利效应。
一旦有真实条目存在，删除占位符/示例条目（斜体格式）。
不要添加通用建议。每个条目都应针对此代码库。

Step 3: Create a New Skill

步骤3：创建新Skill

Use this procedure when you've identified a repeatable workflow worth capturing.

当你确定某个可重复的工作流值得固化时，请使用此流程。

Decision: Is This a Skill or an AGENTS.md Entry?

决策：这是Skill还是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.

这是一个有明确输出的多步骤流程吗？
  → 是 → 作为Skill
  → 否 → 作为AGENTS.md条目

这是否与本代码库的工作方式（规范、导航）相关？
  → 是 → 作为AGENTS.md条目
  → 否 → 作为Skill

不确定？
  → 先作为AGENTS.md条目。如果后续频繁使用，再升级为Skill

Creating the Skill

创建Skill

Choose a name. Use a verb-noun pattern reflecting the job:
```
debug-ci
```
,
```
draft-release-notes
```
,
```
run-migration
```
, etc.
Create the folder and file:
```
skills/<skill-name>/SKILL.md
```

Write the SKILL.md with this structure:

markdown

---
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.>

Key principles for good skills:
- Frame around a job to be done, not a tool ("debug CI failure", not "use grep")
- Make the trigger clear — when should an agent reach for this?
- Define the output contract — what does "done" look like?
- Include examples of good output as assets if helpful (put in
```
skills/<name>/examples/
```
  )
- Keep steps imperative and specific — avoid vague instructions

Add the new skill to the skills table in

AGENTS.md

markdown

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

选择名称。使用反映任务的动词-名词格式：
```
debug-ci
```
、
```
draft-release-notes
```
、
```
run-migration
```
等。
创建文件夹和文件：
```
skills/<skill-name>/SKILL.md
```

编写SKILL.md，遵循以下结构：

markdown

---
name: <skill-name>
description: <该Skill完成任务的单行描述>
---

# <Skill名称>

> **何时使用：** <明确的触发条件>

## 步骤

1. <步骤1 — 具体且使用祈使句>
2. <步骤2>
3. ...

## 输出约定

<“完成”的标准。明确说明格式、位置和质量要求。>

优质Skill的核心原则：
- 围绕要完成的任务构建，而非工具（比如“调试CI失败”，而非“使用grep”）
- 明确触发条件——Agent何时应该使用这个Skill？
- 定义输出约定——“完成”是什么样子？
- 如果有帮助，可在
```
skills/<name>/examples/
```
  中添加优质输出示例作为资源
- 步骤要具体且使用祈使句——避免模糊的指令

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

markdown

| [<skill-name>](skills/<skill-name>/SKILL.md) | <用途> | <触发条件> |

Adding Scripts or Assets to a Skill

为Skill添加脚本或资源

If a skill needs deterministic execution (not just LLM judgment), add scripts:

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

Reference these from SKILL.md: "Run

scripts/validate.sh

to verify the output."

如果某个Skill需要确定性执行（而非仅依赖LLM判断），可添加脚本：

skills/<skill-name>/
├── SKILL.md          # 操作手册（必填）
├── scripts/          # 用于确定性步骤的辅助脚本
│   └── validate.sh
└── examples/         # 展示“优质”标准的参考输出
    └── example-output.md

在SKILL.md中引用这些资源：“运行

scripts/validate.sh

以验证输出。”

Step 4: Decide Scope — Repo-Local vs Global vs Shared

步骤4：确定范围 — 代码库本地 vs 全局 vs 共享

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

该Skill仅对本代码库重要吗？
  → 保留在本代码库的skills/目录中（代码库本地）

我在其他代码库中也遇到过同样的问题吗？
  → 升级到~/.agent/skills/<name>/（机器全局）
  → 将Skill文件夹复制到该位置

我的团队是否在重复执行此工作流？
  → 升级到共享代码库或注册表（共享）
  → 将Skill文件夹移动到团队的共享技能代码库中

Promotion Checklist

升级检查清单

When promoting a skill from repo-local to global:

Remove any repo-specific paths or references from the SKILL.md.
Make the instructions generic enough for any project.
Test it works without the original repo's context.
Keep the repo-local version if it has repo-specific customizations.

将Skill从代码库本地升级到全局时：

从SKILL.md中删除所有代码库特定的路径或引用。
让指令足够通用，适用于任何项目。
测试其在脱离原代码库上下文的情况下是否能正常工作。
如果原代码库本地版本有特定定制，可保留该版本。

Step 5: Validate the Improvement

步骤5：验证改进效果

After making any changes (AGENTS.md update or new skill):

Re-read the updated file. Does it read clearly? Would a fresh agent session benefit from it?
Check for contradictions. Does the new entry conflict with anything existing?
Check for bloat. Is this file getting too long? If AGENTS.md exceeds ~200 lines, consider:
- Archiving old gotchas that are no longer relevant
- Moving detailed procedures into skills
- Summarizing verbose entries

Commit the changes with a clear message:

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

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

在完成任何更改（更新AGENTS.md或创建新Skill）后：

重新阅读更新后的文件。内容是否清晰？新的Agent会话是否能从中受益？
检查是否存在矛盾。新条目是否与现有内容冲突？
检查是否冗余。文件是否过长？如果AGENTS.md超过约200行，可考虑：
- 归档不再相关的旧注意事项
- 将详细流程迁移到Skill中
- 简化冗长的条目

提交更改，并附上清晰的提交信息：

docs: update AGENTS.md with <你学到的内容>

或

feat: add <skill-name> skill for <任务描述>

Anti-Patterns to Avoid

需避免的反模式

❌ Don't	✅ Do Instead
Add generic advice ("write clean code")	Add repo-specific rules ("use `pnpm` , not `npm` ")
Create skills for one-off tasks	Create skills for tasks you'll do again
Let AGENTS.md grow unbounded	Prune stale entries, move procedures to skills
Write vague skill steps ("figure out what's wrong")	Write specific steps ("run `npm test` , read the first failing assertion")
Create a skill around a tool	Create a skill around a job to be done
Start with shared/global skills	Start repo-local, promote when pain repeats

❌ 不要做	✅ 正确做法
添加通用建议（比如“编写整洁的代码”）	添加代码库特定规则（比如“使用 `pnpm` ，而非 `npm` ”）
为一次性任务创建Skill	为会重复执行的任务创建Skill
让AGENTS.md无限制增长	修剪过时条目，将流程迁移到Skill中
编写模糊的Skill步骤（比如“找出问题所在”）	编写具体步骤（比如“运行 `npm test` ，查看第一个失败的断言”）
围绕工具创建Skill	围绕要完成的任务创建Skill
从共享/全局Skill开始	先从代码库本地开始，当问题重复出现时再升级

Quick Reference: The Compounding Loop

快速参考：复利循环

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

"The most valuable skill is the habit of watching yourself work." Each improvement makes future improvements easier. That's how agents compound.

执行任务
    ↓
完成任务
    ↓
复盘：我是否走了弯路？被纠正过？重复执行了工作流？发现了注意事项？
    ↓
    ├── 导航失误     → 更新代码库地图
    ├── 行为被纠正 → 添加到本地规范/防护规则
    ├── 重复工作流   → 创建Skill
    ├── 意外发现  → 添加到模式与注意事项
    └── 无显著问题     → 继续执行下一个任务
    ↓
下一个任务从更优的基线开始

“最有价值的技能是观察自己工作的习惯。” 每一次改进都会让未来的改进更容易。这就是Agent实现复利增长的方式。