Update Skill Content

---
name: update-skill-content
description: >
  更新现有 SKILL.md 的内容以提高准确性、完整性和清晰度。涵盖版本号递增、步骤
  精炼、常见问题扩展和相关技能同步。适用于技能步骤引用了过时工具或 API、常见
  问题章节内容单薄、相关技能中有失效的交叉引用，或在收到技能步骤不清晰或不完
  整的反馈后。
locale: zh-CN
source_locale: en
source_commit: ecece0b7
fence_basis_commit: ecece0b7
translator: claude-opus-4-6
translation_date: 2026-03-16
license: MIT
allowed-tools: Read Write Edit Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.1"
  domain: review
  complexity: intermediate
  language: multi
  tags: review, skills, content, update, maintenance, quality
---

# 更新技能内容

通过精炼步骤、扩展常见问题的真实失败模式、同步相关技能章节并递增版本号，改进现有 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 标志或命令语法
- 已重命名或废弃的包名
- 已演变的配置文件格式

```bash
# 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 步：更新步骤以确保准确性

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

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. 对每个被引用的技能，验证其是否存在：
   ```bash
   # Check if referenced skill exists
   test -d skills/referenced-skill-name && echo "EXISTS" || echo "NOT FOUND"
   ```
2. 搜索引用此技能的技能（它们应该被交叉链接）：
   ```bash
   # Find skills that reference this skill
   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` — 用于在整个技能库中批量修复交叉引用