| name | cheatsheet-update |
| description | 更新本仓库已有 cheatsheet 的专用技能。用于用户提到更新、升级、同步新版、补 changelog、release notes、跨版本变化、把某个 topic 更新到最新版本时；必须优先使用本技能，而不是直接用 cheatsheet-maker。该技能会先调用 cheatsheet-review-skill 做现状评估，再结合 cheatsheet-maker 的正文与文件规范直接提升内容：处理过时命令/API/配置，补充新特性、迁移影响与高频用法，并在符合条件时维护正文末尾的版本变更模块与 changelog-history.md。 |
cheatsheet-update
为已有 cheatsheets/<topic>/ 执行版本更新、跨版本差异整理、正文内容提升、过时内容修正、元数据同步与版本变更归档。
触发边界
- 用户提到更新、升级、同步新版、更新到最新版本、跨版本更新、release notes、changelog、版本变更时，使用本技能
- 用户只是创建全新 cheatsheet 时，转交 agentskill: cheatsheet-maker
- 用户只要求补标签时，转交 agentskill: tag-ci
- 用户只要求补图标时，转交 agentskill: icon-complete-skill
核心职责
- 评估当前 topic 是否过时、内容是否需要随版本调整，评估完直接执行
- 根据 review 建议提升正文质量，不只维护 changelog
- 基于官方来源更新
<topic>.md、meta.yml、refmap.md
- 删除或改写过时命令、参数、API、配置项、工作流与兼容性说明
- 补充新版本的重要特性、新增命令/API/配置、高频用法和迁移注意事项
- 在确认发生跨版本更新时，维护正文末尾
## 🧾 版本变更
- 若覆盖已有版本变更模块，先把旧内容归档到
changelog-history.md
- 更新后按 cheatsheet-maker 的文件规范自检，必要时重建 HTML
必须联动的技能
- 先使用 agentskill: cheatsheet-review-skill
- 读取当前
cheatsheets/<topic>/
- 评估内容完整度、事实正确性、版本时效性、来源可追溯性
- 输出会影响本次更新范围的问题与优先级
- 再参考 agentskill: cheatsheet-maker
- 沿用
<topic>.md、meta.yml、refmap.md 的格式规则
- 沿用普通 cheatsheet / cookbook / 混合风格判定
- 确保更新后的正文仍是可速查内容，而不是 release notes 文章
内容更新要求
本技能是执行型更新技能，不是只输出评估报告，也不是只追加版本变更模块。review 结论和官方新版本资料必须转化为实际内容改动。
必须处理的正文改动
- 过时内容：移除或改写旧版本命令、废弃 API、失效配置、旧行为默认值
- 新特性：补充新版本中对高频使用有价值的功能、命令、参数、API、配置入口
- 迁移影响：说明破坏性变化、重命名、默认值变化、兼容性要求和替代方案
- 内容匮乏：按 review 建议补齐缺失的最小工作流、高频 recipes、参数对照或常见坑
- 结构失配：必要时按 cheatsheet-maker 的风格规则重排章节，但不要为了更新而重写全部正文
- 来源补强：正文新增或修正的关键结论必须能在
refmap.md 找到来源
改动优先级
- 先修正会误导用户的过时内容和事实错误
- 再补新版本中影响使用路径的新特性和迁移点
- 再补 review 指出的内容匮乏项
- 最后维护
meta.yml、frontmatter、refmap.md 和 ## 🧾 版本变更
如果 review 建议与 release notes 信号冲突，以官方最新文档和最新稳定版本行为为准，并在结果中说明取舍。
版本判断
- 默认从
meta.yml.version 读取当前版本
- 如果
meta.yml.version 缺失，再读取 <topic>.md frontmatter 的 version
- 如果用户明确给出起止版本，优先使用用户指定版本
- 默认目标版本为官方最新稳定版本
- 若版本无法可靠判断，不要伪造跨度；先更新可核验内容，并在结果中说明版本跨度待核验
来源优先级
- GitHub Releases
- GitHub tags 与仓库内
CHANGELOG / CHANGELOG.md / RELEASE-NOTES.md
- 官方文档的 changelog / release notes 页面
- 官方博客或公告中的版本发布页
若 topic 有有效 GitHub 仓库，优先用 GitHub 来源。若没有有效 GitHub 仓库，允许尝试官网 changelog / release notes，但必须把来源写入 refmap.md。
版本变更模块规则
仅当确认本次是跨版本更新时，才新增或重建正文末尾的版本变更模块。
模块位置与标题
- 模块必须位于
<topic>.md 最后
- 标题固定为：
## 🧾 版本变更
---
link: <官方 changelog 或 release notes URL>
desc: 按官方发布说明整理本次跨版本更新中对速查用户最重要的变化。
---
内容粒度
- 每个版本保留 3-6 条重点
- 只写重要新特性、破坏性变化、迁移影响、CLI/API/配置的关键变化
- 不复制完整 release notes
- 不把普通 bugfix 全量搬进正文，除非它影响常用命令、兼容性或使用路径
- 多版本更新时按版本从新到旧排列
推荐格式
### v1.2.0
- 新增 xxx 能力，适合 xxx 场景
- 调整 xxx 默认行为，升级时需要检查 xxx
- 废弃 xxx，建议改用 xxx
已有 changelog 的归档规则
如果 <topic>.md 已存在 版本变更、Changelog、更新日志 等正文模块：
- 先提取将被覆盖的旧模块内容
- 创建或更新
cheatsheets/<topic>/changelog-history.md
- 将旧模块追加到文件顶部，使历史记录从新到旧排列
- 再用本次核验后的版本跨度内容重建正文末尾
## 🧾 版本变更
changelog-history.md 格式
# Changelog History
## 2026-05-08 覆盖归档
- 来源文件: `<topic>.md`
- 原模块标题: `## 🧾 版本变更`
- 覆盖原因: 更新到 `<target-version>`，重建跨版本摘要
<旧模块原文>
归档内容应保持原文，不做二次改写，方便追溯人工整理过的历史内容。
更新执行流程
- 识别目标 topic，读取
cheatsheets/<topic>/ 下的现有文件
- 使用 cheatsheet-review-skill 做现状评估，记录必须修复的问题
- 读取 cheatsheet-maker，确认正文格式、卡片结构、元数据与 refmap 规则
- 解析当前版本、仓库、发布日期、已有 changelog 状态
- 联网核验最新版本与跨版本 release notes
- 决定更新范围：
- 正文中过时的命令、API、配置、工作流
- review 指出的内容匮乏、结构失配、事实错误、来源缺失
- 新版本带来的新特性、新参数、新配置、新工作流
- 破坏性变化、迁移步骤、废弃项和替代方案
meta.yml.version、date、github<topic>.md frontmatterrefmap.md 的版本来源与 changelog 来源- 正文末尾
## 🧾 版本变更
- 若覆盖已有 changelog，先写入
changelog-history.md
- 修改源文件后，按 topic 执行 HTML 生成：
node cheatsheet-html-maker/index.js --input cheatsheets/<topic>/<topic>.md
- 若更新影响导览页元数据，再执行导航页重建
自检
- 已先评审，再更新，无需等用户确认
- 已把 review 建议落实为正文改动，而不是停留在评估报告
- 已处理过时内容、事实错误和版本行为变化
- 已补充新版本的重要特性、迁移影响或新增高频用法
- 已核验版本来源，不靠记忆判断最新版本
- 已区分 GitHub 来源与官网 changelog 来源
- 没有在无版本跨度时强行添加
## 🧾 版本变更
- 版本变更模块位于正文最后
- 每个版本只保留 3-6 条重点
- 已有 changelog 被覆盖前已归档到
changelog-history.md
meta.yml、frontmatter、refmap.md 与正文版本一致- 更新后的正文仍符合 cheatsheet-maker 的结构与风格规则
