improve-skill

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

改进已有 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 会受益的经验：

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

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

先提案，再编辑

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

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 的目标或范围。