# Improve Skill

> 当用户要求改进已有 skill，或某个 skill 本次使用不顺、漏了指引、需要把有效经验补给下一个 agent 时使用。查 `~/.agents/.skill-lock.json`：未追踪的本地自制 skill 可就地改；已追踪的 skill 只在原 repo 改。分析后先提案，获用户批准才编辑。

- Skill: `cuipengfei/improve-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cuipengfei/improve-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cuipengfei/improve-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cuipengfei (https://skillmd.com/u/cuipengfei)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/cuipengfei/improve-skill

---


# 改进已有 skill

从本次实际使用中提炼改进。使用出了问题，找出指引缺口；使用顺利，提炼能让下一个 agent 少走弯路的经验。只依据可观察到的会话证据，不补造场景。

## 开始前

先加载当前环境中所有可用的 skill 设计、编写、评审、验证 meta skills，再分析目标 skill。


## 确认目标 skill 与改动位置

先确定用户要改的是哪个已有 skill。然后查固定文件：

```text
~/.agents/.skill-lock.json
```


| 目标 skill 是否在 lock 中 | 含义                      | 改动位置                                                                               |
| ------------------------- | ------------------------- | -------------------------------------------------------------------------------------- |
| 不在                      | 本地自制 skill            | 直接在该 skill 当前所在目录编辑。                                                      |
| 在                        | repo 安装、被追踪的 skill | 从 lock 记录识别原始 repo，只在原始 repo 修改；不直接改 `~/.agents/skills/` 安装副本。 |


## 从本次会话收集改进信号

### 使用出现问题

回看具体偏差，不笼统写“效果不好”。记录：

- agent 实际做了什么、说了什么；引用相关会话片段。
- 用户原本期待什么。
- 目标 skill 缺了哪一层指引：触发条件、判断步骤、边界、输出形状，还是验证方式。
- 为什么现有文字没能拦住这次偏差。

常见对应关系：

| 看到的偏差             | 优先补什么                       |
| ---------------------- | -------------------------------- |
| 没有加载或加载错 skill | description 的触发语与适用条件   |
| 漏掉关键步骤           | 明确的判断步骤或顺序             |
| 擅自扩范围             | 可观察的边界与非目标             |
| 输出形状不对           | 正面说明结果应包含什么、顺序如何 |
| 明知规则仍绕开         | 明确禁止项、触发信号和后果       |

### 使用顺利

不要因为顺利就停止复盘。检查是否出现了 skill 尚未写下、但下一个 agent 会受益的经验：

- 新的判断分支或取舍理由；
- 容易遗漏的边缘情况；
- 有实际理由的反模式；
- 更可靠的验证方法或路径约定。

没有具体证据就不添加“可能有用”的泛泛建议。

## 先提案，再编辑

分析完不能直接改文件。先向用户提出改进提案，至少写明：

1. 目标 skill 与 lock 判定结果。
2. 本次会话的具体证据。
3. 拟改哪个文件、哪个 section。
4. 拟新增、删除或改写什么。
5. 为什么这会帮助下一个 agent。
6. 不会改变什么范围。
7. 如何验证改动有效。

等用户明确批准后，才进入编辑。用户要求只分析、只提案或暂不动作时，停在提案阶段。

## 编辑已批准的改动

编辑前完整阅读目标 SKILL.md，理解其 frontmatter、结构和边界。每条修改都应对应已批准提案中的会话证据。

按偏差类型选择写法：

| 问题                       | 合适写法                                       |
| -------------------------- | ---------------------------------------------- |
| 在压力下故意绕过已知规则   | 明确禁止项，写出识别信号与不可接受的替代做法。 |
| 内容都做了，但结果结构不对 | 给出正面结果结构；说明各部分的顺序和职责。     |
| 经常漏掉固定信息           | 在模板中加入必填位置。                         |
| 做法取决于条件             | 写成可观察条件下的分支，而不是宽泛例外。       |

保持原 skill 的核心目标不变。补的是本次证据支持的指引，不是顺手加入新的任务、技术栈或偏好。

## 验证并报告

改完后核对：

- 每处改动都能对应已批准的提案与具体会话证据。
- 未改变目标 skill 的核心用途。
- frontmatter 仍完整，引用的资源仍可用。
- 不在 lock 的本地自制 skill 已在原位置改动；在 lock 中的 skill 已在原 repo 改动。
- 若目标 skill 属于 plugin，按该 repo 的约定同步版本和注册信息。

向用户报告：目标 skill、lock 判定、会话证据、批准过的提案、实际改动位置、以及验证结果。

## 不要这样做

- 把不在 `~/.agents/.skill-lock.json` 中的本地自制 skill 误判为不能改。
- 直接修改 `~/.agents/skills/` 中已追踪 skill 的安装副本。
- 未提案、未获批准就编辑目标 skill。
- 把一次性的会话过程、搜索记录或创建过程塞进 SKILL.md。
- 用没有证据的“可能有用”场景撑长 skill。
- 为了看起来完整而改掉原 skill 的目标或范围。