document-release

document-release 技能概览

document-release 的用途

document-release 是一个发布后的文档更新技能，用来让项目文档与实际已发布内容保持一致。它会读取文档、对照最近的 diff，并在发布内容改变叙事时，帮助更新 README.md、ARCHITECTURE.md、CONTRIBUTING.md、CLAUDE.md、CHANGELOG.md 和 VERSION 等文件。

适合谁使用

这个 document-release 技能最适合技术写作者、仓库维护者，以及需要把已合并代码转化为准确文档、同时减少人工交叉核对的 agent。尤其适合“代码已经完成，但文档还停留在旧行为”这类场景。

在实际工作中的价值

它解决的核心不是泛泛的写作，而是发布同步。这个技能适合你需要一个可靠的 document-release 指南，去更新正文、清理过时的 TODO，并让发布说明与已交付变更保持一致，而不是从头编造一套新叙事的时候。

如何使用 document-release 技能

正确安装并触发 document-release

先在你的 agent 环境中完成 document-release 的安装流程，然后在 PR 合并、代码发布，或者有人要求“更新文档”“同步文档”时调用它。这个技能设计上是用于实现之后，而不是探索性起草阶段。

从正确的输入开始

高质量提示应包含已发布的 diff、受影响的文件、目标受众，以及任何发布约束。像“更新文档”这种弱请求会迫使技能去猜；而像“针对这个已合并 PR 里的 API 重命名同步文档，并保持 changelog 的语气简洁”这样的明确请求，才能给它准确编辑所需的上下文。

先读这些文件

在使用 document-release 时，先从 SKILL.md 开始，再查看它在仓库里指向的文件，尤其是 README.md、ARCHITECTURE.md、CONTRIBUTING.md、CLAUDE.md 以及任何发布或版本文件。如果你想理解生成后的结构，以及哪些内容在多次更新中应该保持稳定，也要检查 SKILL.md.tmpl。

能显著提升输出的工作流建议

使用这个技能时，最好按顺序回答三个问题：变了什么、哪些文档提到了这种行为、哪些内容必须重写或删除。如果仓库里有活跃的 TODO、过时示例，或带版本号的说明，务必在提示里明确指出，这样 document-release 技能才能把它们清理掉，而不是保留下来。

document-release 技能常见问题

document-release 只适合最终发布吗？

不是。document-release 也适用于已合并的 PR，以及任何会让已发布文档与现实脱节的发布后变更。它对发布前的头脑风暴帮助较小，但在真实来源已经改变之后会更有用。

它和普通提示有什么不同？

普通提示也许能生成一版不错的修改，但 document-release 增加的是面向发布的工作流：先读文档，再交叉对照 diff，更新受影响文件，并保持语气和术语一致。这样能降低发布过时说明或遗漏依赖文档的风险。

适合新手吗？

适合，只要用户能说清楚已经发布了什么，以及哪些文档需要反映这些变化。新手在提供清晰的变更摘要、目标仓库路径和预期更新文件时，通常能得到最好结果。

什么时候不该用它？

如果你只是需要一个粗略草稿、产品公告，或者面向未完成代码的推测性文档，就不要用 document-release。如果你无法访问仓库历史或变更文件，它也不太适合，因为这个技能依赖于以实际变化为依据来编辑内容。

如何改进 document-release 技能

给 document-release 更精确的发布简报

最大的质量提升，来自明确写出已发布的具体行为、受影响的文档，以及你希望保留的语气。例如：“更新新认证流程的文档，删除过时的安装步骤，保持 changelog 只写事实，不要改动受影响章节之外的架构说明。”

把常见失败模式提前说出来

如果你知道有过时示例、改名的命令、损坏的交叉引用，或者需要一起移动的版本字符串，就提前告诉 document-release。如果你知道某一份文档是权威来源、其他文档都是衍生内容，也要说明；这样可以避免不必要的重写，并让 document-release 技能更聚焦。

首轮结果后继续迭代

先检查第一版输出里的三个点：缺失的链接、过时的截图或代码样例，以及跨文件的术语漂移。然后只把你发现的缺口反馈回去，这样下一轮就能在不重写稳定部分的前提下，进一步收紧 document-release 的安装与使用结果。

把这个技能当作发布检查清单

对于 Technical Writing 场景下的 document-release，把这个技能当成一次发布后的 QA：确认文档与已发布行为一致，移除失效的 TODO，并核对带版本的说明是否正确。最好的 document-release 指南输入，应该足够具体，让模型能把 diff 和仓库内容对齐，而不是泛泛地重写一切。