更新技能内容

通过精炼步骤、扩展常见问题的真实失败模式、同步相关技能章节并递增版本号，改进现有 SKILL.md。在技能通过格式验证但存在内容缺口、过时引用或不完整步骤后使用此技能。

适用场景

• 技能的步骤引用了过时的工具、API 或版本号
• 常见问题章节内容单薄（少于 3 个问题）或缺少真实失败模式
• 相关技能章节中有失效的交叉引用或缺少相关链接
• 步骤缺乏具体代码示例或有模糊指令
• 已向库中添加新技能，应该从现有技能交叉引用
• 收到技能步骤不清晰或不完整的反馈后

输入

• 必填：要更新的 SKILL.md 文件路径
• 可选：要重点处理的特定章节（如"步骤"、"常见问题"、"相关技能"）
• 可选：更新来源（变更日志、问题报告、用户反馈）
• 可选：是否递增版本号（默认：是，小版本递增）

步骤

第 1 步：阅读当前技能并评估内容质量

阅读完整的 SKILL.md 并评估每个章节的完整性和准确性。

各章节评估标准：

• 适用场景：触发条件是否具体且可操作？（预期 3-5 条）
• 输入：类型、默认值和必填/可选是否清晰区分？
• 步骤：每个步骤是否有具体代码、预期结果和失败处理？
• 验证清单：清单项目是否可客观验证？（预期 5+ 条）
• 常见问题：问题是否具体，附症状和修复方法？（预期 3-6 条）
• 相关技能：引用的技能是否存在？是否遗漏了明显的相关技能？

预期结果： 清楚了解哪些章节需要改进，已识别具体的缺口。

失败处理： 若技能无法读取（路径错误），验证路径。若 SKILL.md 有损坏的 YAML 前置元数据，在尝试内容更新之前先使用 review-skill-format 修复前置元数据。

第 2 步：检查过时引用

扫描步骤中的特定版本引用、工具名称、URL 和可能已更改的 API 模式。

常见过时迹象：

• 特定版本号（如 v1.24、R 4.3.0、Node 18）
• 可能已移动或失效的 URL
• 已更改的 CLI 标志或命令语法
• 已重命名或废弃的包名
• 已演变的配置文件格式

# 检查特定版本引用
grep -nE '[vV][0-9]+\.[0-9]+' skills/<skill-name>/SKILL.md

# 检查 URL
grep -nE 'https?://' skills/<skill-name>/SKILL.md

预期结果： 带行号的潜在过时引用列表。每个引用已验证为最新或已标记需要更新。

失败处理： 若需手动检查的引用太多，优先处理：步骤代码块（最可能导致运行时失败）、常见问题（可能引用旧的变通方法）、信息性文字。

第 3 步：更新步骤以确保准确性

对于每个已识别需要改进的步骤：

1. 验证代码块是否仍能正确执行或反映当前最佳实践
2. 添加缺失的上下文句子，解释为什么需要此步骤
3. 确保具体命令使用真实路径、真实标志和真实输出
4. 更新预期结果块以匹配当前工具行为
5. 更新失败处理块，附当前错误信息和修复方法

更新代码块时，保留原始结构：

• 保持步骤编号一致
• 维护 ### Step N: Title 格式
• 除非原始顺序有误，否则不重新排列步骤

预期结果： 所有步骤包含当前、可执行的代码。预期结果/失败处理块反映实际当前行为。

失败处理： 若不确定代码块是否仍然正确，添加注释：<!-- TODO: Verify this command against current version -->。不要删除有效的代码块而用未经测试的替代方案替换。

第 4 步：扩展常见问题

审查常见问题章节，若存在缺口则进行扩展。

问题质量标准：

• 每个问题有加粗名称，后跟具体描述
• 描述包括症状（出了什么问题）和修复方法（如何避免或恢复）
• 问题来自真实失败模式，而非假设性问题
• 目标范围为 3-6 个问题

新问题的来源：

• 含复杂失败处理块的步骤（这些可能是常见问题）
• 警告相同工具或模式的相关技能
• 该步骤用户报告的常见问题

预期结果： 3-6 个问题，每个有具体症状和修复方法。无"注意"或"彻底测试"等笼统问题。

失败处理： 若只能识别 1-2 个问题，对于基础复杂度的技能这是可以接受的。对于中级和高级技能，少于 3 个问题表明作者没有充分探索失败模式——标记以供将来扩展。

第 5 步：同步相关技能章节

验证相关技能章节中的所有交叉引用都有效，并添加任何缺失的链接。

1. 对每个被引用的技能，验证其是否存在：

   # 检查引用的技能是否存在
   test -d skills/referenced-skill-name && echo "EXISTS" || echo "NOT FOUND"
   

2. 搜索引用此技能的技能（它们应该被交叉链接）：

   # 查找引用此技能的技能
   grep -rl "skill-name" skills/*/SKILL.md
   

3. 检查基于领域和标签的明显相关技能
4. 使用格式：- \skill-id` — 关系的一行描述`

预期结果： 所有引用的技能在磁盘上存在。双向交叉引用到位。无孤立链接。

失败处理： 若引用的技能不存在，删除引用或将其注释为计划中的未来技能。若许多技能引用了此技能但未在相关技能中列出，添加最相关的 2-3 个。

第 6 步：在前置元数据中递增版本号

按照语义化版本控制更新 metadata.version 字段：

• 补丁递增（1.0 到 1.1）：拼写修复、小幅澄清、URL 更新
• 小版本递增（1.0 到 2.0）：新步骤、重大内容添加、结构性变更
• 注意：技能使用简化的两部分版本控制（主版本.小版本）

若前置元数据中存在日期字段，也要更新。

预期结果： 版本已适当递增。变更幅度与更新范围匹配。

失败处理： 若当前版本无法解析，将其设置为 "1.1" 并添加注释说明版本历史中断。

验证清单

• 所有步骤包含当前、可执行的代码或具体指令
• 无过时的版本引用、URL 或已废弃的工具名称
• 每个步骤都有 Expected: 和 On failure: 块
• 常见问题章节有 3-6 个具体问题，附症状和修复方法
• 所有相关技能交叉引用指向现有技能
• 密切相关技能之间的双向交叉引用到位
• 前置元数据中的版本号已适当递增
• 更新后行数仍在 500 行以下
• SKILL.md 在修改后仍通过 review-skill-format 验证

常见问题

• 不测试就更新代码：在没有验证代码能运行的情况下更改步骤中的命令，比保留旧命令更糟糕。不确定时，添加验证注释而非未经测试的替换。
• 过度扩展问题：添加 10+ 个问题会稀释此章节。保留 3-6 个最有影响力的问题；若需要，将边缘情况移到 references/ 文件。
• 更新期间破坏交叉引用：重命名技能或更改其领域时，在整个技能库中搜索对旧名称的引用。使用 grep -rl "old-name" skills/ 查找所有出现。
• 忘记递增版本：每次内容更新，无论多小，都应递增版本。这让使用者能够检测技能何时发生了变化。
• 范围蔓延到重构：内容更新改进技能说的内容。若你发现自己在重构章节或提取到 references/，请改用 refactor-skill-structure 技能。

相关技能

• review-skill-format — 在内容更新之前运行格式验证，确保基础结构合理
• refactor-skill-structure — 当内容更新将技能推过 500 行时，重构结构以腾出空间
• evolve-skill — 对于超出内容更新范围的更深层变更（如创建高级变体）
• create-skill — 在添加新章节或步骤时参考规范格式规范
• repair-broken-references — 用于在整个技能库中批量修复交叉引用