pjt222 更新技能内容
通过精炼步骤、扩展常见问题的真实失败模式、同步相关技能章节并递增版本号，改进现有 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 标志或命令语法
- 已重命名或废弃的包名
- 已演变的配置文件格式
# Check for version-specific references
grep -nE '[vV][0-9]+\.[0-9]+' skills/<skill-name>/SKILL.md
# Check for URLs
grep -nE 'https?://' skills/<skill-name>/SKILL.md
预期结果： 带行号的潜在过时引用列表。每个引用已验证为最新或已标记需要更新。
失败处理： 若需手动检查的引用太多，优先处理：步骤代码块（最可能导致运行时失败）、常见问题（可能引用旧的变通方法）、信息性文字。
第 3 步：更新步骤以确保准确性
对于每个已识别需要改进的步骤：
- 验证代码块是否仍能正确执行或反映当前最佳实践
- 添加缺失的上下文句子，解释为什么需要此步骤
- 确保具体命令使用真实路径、真实标志和真实输出
- 更新预期结果块以匹配当前工具行为
- 更新失败处理块，附当前错误信息和修复方法
更新代码块时，保留原始结构：
- 保持步骤编号一致
- 维护
### Step N: Title格式 - 除非原始顺序有误，否则不重新排列步骤
预期结果： 所有步骤包含当前、可执行的代码。预期结果/失败处理块反映实际当前行为。
失败处理： 若不确定代码块是否仍然正确，添加注释：<!-- TODO: Verify this command against current version -->。不要删除有效的代码块而用未经测试的替代方案替换。
第 4 步：扩展常见问题
审查常见问题章节，若存在缺口则进行扩展。
问题质量标准：
- 每个问题有加粗名称，后跟具体描述
- 描述包括症状（出了什么问题）和修复方法（如何避免或恢复）
- 问题来自真实失败模式，而非假设性问题
- 目标范围为 3-6 个问题
新问题的来源：
- 含复杂失败处理块的步骤（这些可能是常见问题）
- 警告相同工具或模式的相关技能
- 该步骤用户报告的常见问题
预期结果： 3-6 个问题，每个有具体症状和修复方法。无"注意"或"彻底测试"等笼统问题。
失败处理： 若只能识别 1-2 个问题，对于基础复杂度的技能这是可以接受的。对于中级和高级技能，少于 3 个问题表明作者没有充分探索失败模式——标记以供将来扩展。
第 5 步：同步相关技能章节
验证相关技能章节中的所有交叉引用都有效，并添加任何缺失的链接。
- 对每个被引用的技能，验证其是否存在：
# Check if referenced skill exists test -d skills/referenced-skill-name && echo "EXISTS" || echo "NOT FOUND" - 搜索引用此技能的技能（它们应该被交叉链接）：
# Find skills that reference this skill grep -rl "skill-name" skills/*/SKILL.md - 检查基于领域和标签的明显相关技能
- 使用格式：
- \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— 用于在整个技能库中批量修复交叉引用