reflect

Reflect

分析当前会话，并将所学内容转化为对技能作者源代码包的具体修改。技能是整个文件夹，而不仅仅是 SKILL.md。

工作流

1. 确定技能

自动检测使用过哪些技能，方法是扫描对话中的：

• <command-name>/skill-name</command-name> 标签
• 对技能目录中源文件（SKILL.md 或 <skill-name>.md）的读取记录

如果用户将技能名称作为参数提供，请直接使用该名称。

如果检测到多个技能，请询问用户要分析哪个。如果没有检测到技能，且用户未提供参数，请列出可用技能并询问用户。

已安装技能的源代码仓库记录在技能锁定文件中：全局安装使用 ~/.agents/.skill-lock.json，项目安装使用 <project-root>/skills-lock.json。在提出或应用修改之前，先通过锁定文件找到匹配的本地检出中的技能源代码包（不同技能可能位于不同的仓库）。

确定作者源代码后，在决定修改内容之前，先盘点整个软件包：SKILL.md、scripts/、脚本测试、references/、templates/、assets/、钩子、清单以及软件包专用的验证机制。先检查 git 状态。已有的未提交更改属于他人，除非能确认归属，否则不得覆盖或擅自纳入。

使用只读命令解析所选检出的 git 根目录、远程 URL 和当前分支。在拟议修改摘要中展示这三项，并在编辑前请用户确认确切的发布目标。源代码路径已过时、远程地址异常、处于分离 HEAD 状态，或未获得确认时，均须停止应用阶段；不得根据技能名称推断预期仓库。

2. 分析对话

扫描对话中的以下信号：

信号	置信度	查找内容
纠正	高	用户说“不对”“不是这样”“我的意思是……”；明确纠正输出；生成内容后立即要求修改
成功	中	用户说“完美”“很好”“正是如此”；未修改便接受输出；在输出的基础上继续推进
边缘情况	中	技能未预料到的问题；需要变通方案的情境；尚未涵盖的功能
偏好	低	用户选择中的重复模式；隐含的风格或工具偏好
触发误判	高	本应触发技能却未触发，或错误的技能被触发（这是 description/触发条件问题，而非正文问题）

不要将以下内容作为技能修改依据：一次性或仅适用于特定情境的指示（例如“这次就这样”“仅限这个仓库”）、问题、没有明确原因的笼统赞扬，以及无法推广到未来运行的内容。只记录持久且可普遍适用的信号。

将每项信号交由负责相关行为的资源处理：

• 运行时或转换缺陷：检查并修改随附脚本或钩子，并添加回归测试。不要用提示文本掩盖可执行行为问题。
• 使用方式、顺序、安全或触发缺陷：修改 SKILL.md 或其 description。
• 详细的事实性指南：修改对应的参考资料；仅当路由方式或公开契约发生变化时，才更新 SKILL.md。
• 模板/资源缺陷：修改源模板/资源，以及覆盖该内容的验证机制。
• CLI 或输出契约变更：同步更新实现、测试、SKILL.md 和受影响的参考资料。

只阅读相关的随附资源，但必须阅读理解和验证所选行为所需的全部文件。

3. 提议更改

更改可以针对任何自编写的软件包资源。选择证据所指向的最小完整集合。如果修复脚本却没有相应的回归测试，就不完整；如果更改了面向用户的命令，却没有更新相关技能说明或参考资料，也不完整。

如果没有发现可执行的改进信号，请说明该技能表现良好，并以以下内容结尾：

本次会话未发现 [skill-name] 的改进之处。该技能表现良好。

否则，列出发现：

+-- Skill Reflection: [skill-name] ----------------------------+
|                                                               |
|  Signals: X corrections, Y successes, Z edge cases           |
|                                                               |
|  Proposed changes:                                            |
|                                                               |
|  [HIGH] + Files: "specific change description"                |
|  [MED]  + Files: "specific change description"                |
|  [LOW]  ~ Note: "observation for review"                      |
|                                                               |
|  Target: "<git root> | <remote> | <branch>"                   |
|                                                               |
|  Validation: "tests/lint/commands to run"                     |
|                                                               |
|  Commit: "[skill]: [summary of changes]"                      |
|                                                               |
+---------------------------------------------------------------+

Apply these changes? [Y/n] or describe tweaks

4. 应用（如获批准）

1. 定位自编写的源软件包；显示其 Git 根目录、远程仓库和分支，并征求确认；然后重新检查其 Git 状态。如果目标未获确认或现有更改与之冲突，请停止并询问。
2. 阅读 SKILL.md，清点软件包内容，并完整阅读相关实现、资源和测试。
3. 将获批的更改应用到所有对应的源文件。保留无关的现有工作。
4. 运行软件包的重点测试，以及文档中要求的技能检查或验证。如果更改了脚本行为，必须添加回归测试，证明旧行为下测试失败、修复后测试通过。
5. 检查最终的软件包差异。提交或推送前，立即重新解析并显示 Git 根目录、远程仓库和分支，并请用户再次确认同一目标。如果任何值发生变化或未得到确认，请停止。只提交预期文件，并推送到已确认的源仓库。
6. 确认：“技能软件包已更新、测试并推送。”

如果用户拒绝，请确认并结束。

5. 精简（技能内容变得臃肿时）

反思不应只会添加内容。如果软件包变得冗长，或积累了重复的指导和资源（对于 SKILL.md，超过 100 行可视为一个粗略信号），请进行精简：

• 将重复或近似重复的条目合并为一条。
• 删除已过时或已被较新条目取代的指导。
• 将相关要点归入合适的章节。
• 仅当能够确认其使用方和移除路径时，才删除或合并过时的脚本、参考资料、模板、测试和素材。

通过相同的提议和批准流程（步骤 3–4）呈现更改。减少内容总量是理想结果。

示例

用户在一个前端设计会话中纠正了渐变用法和深色背景颜色后运行 /reflect：

+-- Skill Reflection: frontend-design -------------------------+
|                                                               |
|  Signals: 2 corrections, 3 successes                         |
|                                                               |
|  Proposed changes:                                            |
|                                                               |
|  [HIGH] + Constraints: "Never use gradients unless            |
|           explicitly requested"                               |
|  [HIGH] + Color & Theme: "Dark backgrounds: use #000,         |
|           not #1a1a1a"                                        |
|  [MED]  + Layout: "Prefer CSS Grid for card layouts"          |
|                                                               |
|  Commit: "frontend-design: no gradients, #000 dark bg"        |
|                                                               |
+---------------------------------------------------------------+

Apply these changes? [Y/n] or describe tweaks

限制

• 应用更改前，始终展示确切的拟议更改。
• 未经用户明确批准，绝不修改技能软件包。
• 只有成功提交后才能推送。
• 在其仓库中编辑自编写的源软件包，绝不要编辑 Agent 技能目录中的生成版或已安装副本（刷新时会覆盖它）。
• 对脚本、钩子、解析器、转换或输出契约的更改，添加或更新回归测试。
• 可执行行为或 CLI 用法发生变化时，更新说明或参考资料。
• 优先编辑或合并现有资源，而不是追加并行指导；保持软件包精简。