document-release

document-release 技能總覽

document-release 是用來做什麼的

document-release 是一個發佈後文件更新技能，用來讓專案文件和實際已經上線的內容保持一致。它會讀取文件、比對最近的 diff，並在版本更新改變敘事時，協助更新像 README.md、ARCHITECTURE.md、CONTRIBUTING.md、CLAUDE.md、CHANGELOG.md 和 VERSION 這類檔案。

誰適合使用它

這個 document-release 技能最適合技術寫作者、repo 維護者，以及需要把已合併的程式碼轉成準確文件、又想減少人工交叉比對的代理。當程式已經完成，但文件還停留在舊行為時，它特別有用。

為什麼它在實務上重要

它的核心工作不是一般性的寫作，而是發佈同步。當你需要一個可靠的 document-release 指南，能更新說明文字、刪除過時的 TODO，並讓 release notes 與實際上線的變更一致，而不是從零編造一套新敘事時，這個技能就很有價值。

如何使用 document-release 技能

正確安裝並觸發它

先在你的 agent 環境中依照 document-release 的安裝流程完成設定，然後在 PR 合併、程式碼已上線，或有人要求「更新文件」、「同步文件」時呼叫它。這個技能是設計來在實作完成後使用，不是用在探索性草稿階段。

先提供正確的輸入

好的提示會包含已上線的 diff、受影響的檔案、目標讀者，以及任何發佈限制。像「更新文件」這種弱請求，會迫使技能自己猜；像「針對這個已合併 PR 的 API rename 同步文件，並保持 changelog 口吻精簡」這種更強的請求，則能提供它精準編修所需的脈絡。

先讀這些檔案

在使用 document-release 時，先從 SKILL.md 開始，再檢查它在 repo 內指向的檔案，尤其是 README.md、ARCHITECTURE.md、CONTRIBUTING.md、CLAUDE.md，以及任何 release 或 version 檔案。如果你想了解產生的結構，以及哪些內容在每次更新之間應保持穩定，也可以查看 SKILL.md.tmpl。

能提升輸出的工作流程技巧

使用這個技能時，最好按順序回答三個問題：變了什麼、文件裡哪些地方提到那個行為、哪些內容必須改寫或刪除。如果 repo 裡有活躍的 TODO、過時範例，或有版本綁定的說明，請在提示中明確指出，這樣 document-release 技能才能把它們清掉，而不是把它們保留下來。

document-release 技能常見問答

document-release 只適用於最終發佈嗎？

不是。document-release 技能同樣適合已合併的 PR，以及任何會讓已發布文件與現實脫節的發佈後變更。它對發佈前的腦力激盪幫助較小，但一旦單一事實來源已經改變，就會非常實用。

它和一般提示有什麼不同？

一般提示可能也能產出不錯的編修結果，但 document-release 多了以發佈為中心的工作流程：先讀文件、再對照 diff、更新受影響檔案，並維持語氣與術語一致。這能降低送出過時指引或漏掉相依文件的機率。

初學者適合用嗎？

可以，只要使用者能指出哪些內容已經上線、哪些文件需要跟著反映。初學者如果提供清楚的變更摘要、目標 repo 路徑，以及預期要更新的檔案，通常能得到最好結果。

什麼情況下不該用？

如果你只需要一份粗略草稿、產品公告，或是尚未完成程式碼的推測性文件，就不要用 document-release。若你無法存取 repo history 或變更過的檔案，它也不適合，因為這個技能必須以實際變更為基礎來編修。

如何改進 document-release 技能

給這個技能更精準的發佈簡報

最大的品質提升，來自明確指出實際上線的行為、受影響的文件，以及你希望保留的語氣。例如：「更新新 auth flow 的文件，移除過時的設定步驟，讓 changelog 保持客觀，且不要改動受影響區段以外的 architecture notes。」

把常見失誤點先講出來

當你提醒它注意過時範例、重新命名的 commands、壞掉的 cross-reference，或需要一起移動的 version 字串時，document-release 的效果最好。如果你知道某份文件是權威來源、其他文件只是衍生內容，也要直接說明；這樣可以避免不必要的重寫，並讓 document-release 技能專注在真正需要處理的地方。

第一次結果後再迭代

先檢查第一版輸出有沒有三件事：缺少連結、過時的截圖或 code sample、以及跨檔案術語是否漂移。接著只回饋你找到的缺口，這樣下一輪就能把 document-release 的安裝與使用結果收得更精準，而不必重編輯已穩定的段落。

把這個技能當成發佈清單

對 document-release for Technical Writing 來說，把這個技能視為一個發佈後 QA 檢查：確認文件與上線行為一致、清掉無效 TODO，並驗證版本化說明是否正確。最好的 document-release 指南輸入，應該具體到讓模型能把 diff 和 repo 內容對起來，而不是泛泛地整篇重寫。