cuipengfei 改进已有 skill
从本次实际使用中提炼改进。使用出了问题，找出指引缺口；使用顺利，提炼能让下一个 agent 少走弯路的经验。只依据可观察到的会话证据，不补造场景。
开始前
先加载当前环境中所有可用的 skill 设计、编写、评审、验证 meta skills，再分析目标 skill。
确认目标 skill 与改动位置
先确定用户要改的是哪个已有 skill。然后查固定文件：
~/.agents/.skill-lock.json
| 目标 skill 是否在 lock 中 | 含义 | 改动位置 |
|---|---|---|
| 不在 | 本地自制 skill | 直接在该 skill 当前所在目录编辑。 |
| 在 | repo 安装、被追踪的 skill | 从 lock 记录识别原始 repo，只在原始 repo 修改；不直接改 ~/.agents/skills/ 安装副本。 |
从本次会话收集改进信号
使用出现问题
回看具体偏差，不笼统写“效果不好”。记录：
- agent 实际做了什么、说了什么；引用相关会话片段。
- 用户原本期待什么。
- 目标 skill 缺了哪一层指引：触发条件、判断步骤、边界、输出形状，还是验证方式。
- 为什么现有文字没能拦住这次偏差。
常见对应关系：
| 看到的偏差 | 优先补什么 |
|---|---|
| 没有加载或加载错 skill | description 的触发语与适用条件 |
| 漏掉关键步骤 | 明确的判断步骤或顺序 |
| 擅自扩范围 | 可观察的边界与非目标 |
| 输出形状不对 | 正面说明结果应包含什么、顺序如何 |
| 明知规则仍绕开 | 明确禁止项、触发信号和后果 |
使用顺利
不要因为顺利就停止复盘。检查是否出现了 skill 尚未写下、但下一个 agent 会受益的经验：
- 新的判断分支或取舍理由；
- 容易遗漏的边缘情况；
- 有实际理由的反模式；
- 更可靠的验证方法或路径约定。
没有具体证据就不添加“可能有用”的泛泛建议。
先提案，再编辑
分析完不能直接改文件。先向用户提出改进提案，至少写明：
- 目标 skill 与 lock 判定结果。
- 本次会话的具体证据。
- 拟改哪个文件、哪个 section。
- 拟新增、删除或改写什么。
- 为什么这会帮助下一个 agent。
- 不会改变什么范围。
- 如何验证改动有效。
等用户明确批准后，才进入编辑。用户要求只分析、只提案或暂不动作时，停在提案阶段。
编辑已批准的改动
编辑前完整阅读目标 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 的目标或范围。