document-release

document-release スキルの概要

document-release は何のためのものか

document-release は、リリース後のドキュメント更新を行うスキルで、実際に出荷された内容とプロジェクトドキュメントを一致させるために使います。ドキュメントを読み、最新の diff と照らし合わせながら、リリースで内容が変わったときに README.md、ARCHITECTURE.md、CONTRIBUTING.md、CLAUDE.md、CHANGELOG.md、VERSION などのファイル更新を支援します。

どんな人に向いているか

この document-release スキルは、技術ライター、リポジトリのメンテナー、そしてマージ済みコードを手作業の突き合わせを減らしながら正確なドキュメントに落とし込みたいエージェントに最適です。コードは完成しているのに、ドキュメントだけが旧仕様のまま残っている場面で特に力を発揮します。

実務で重要な理由

ここでの主な仕事は、一般的な文章作成ではなくリリース同期です。新しい物語をゼロから作るのではなく、確実にドキュメントをリリース内容に合わせ、古い TODO を整理し、出荷済みの変更と整合したリリースノートに保つための document-release ガイドとして有用です。

document-release スキルの使い方

正しくインストールして起動する

まずはエージェント環境で document-release のインストール手順に従い、PR がマージされたとき、コードが出荷されたとき、または誰かが「ドキュメントを更新して」「文書を同期して」と依頼したときに呼び出します。このスキルは、試行錯誤の下書き段階ではなく、実装後に使う前提で設計されています。

適切な入力から始める

良いプロンプトには、出荷された diff、影響を受けるファイル、想定読者、そしてリリース上の制約を含めます。「docs を更新して」だけでは推測に頼ることになりますが、「このマージ済み PR の API リネームに合わせて docs を同期し、changelog の文体は簡潔に保って」といった依頼なら、正確に編集するための文脈が十分に伝わります。

先に確認すべきファイル

document-release を使うときは、まず SKILL.md を起点に読み、そのうえでリポジトリ内で参照されているファイル、特に README.md、ARCHITECTURE.md、CONTRIBUTING.md、CLAUDE.md、およびリリースやバージョン関連のファイルを確認します。生成される構成や、更新をまたいで安定して残すべき部分を理解したい場合は SKILL.md.tmpl も確認してください。

出力をよくするワークフローのコツ

このスキルは、次の 3 点を順番に整理すると使いやすくなります。何が変わったか、その動作についてどのドキュメントが触れているか、そして何を書き換えるべきか／削除すべきかです。リポジトリにアクティブな TODO、古い例、バージョン依存の記述があるなら、プロンプトで明示してください。そうすることで document-release スキルがそれらを残さず、きちんと整理できます。

document-release スキル FAQ

document-release は最終リリース専用ですか？

いいえ。document-release スキルは、マージ済み PR や、公開後にドキュメントが現実とずれるような変更にも向いています。プレマージのブレストよりも、正しいソース・オブ・トゥルースがすでに変わった後でこそ使いやすいスキルです。

通常のプロンプトと何が違いますか？

通常のプロンプトでもある程度の編集はできますが、document-release にはリリース重視のワークフローがあります。つまり、ドキュメントを読み、diff と突き合わせ、影響を受けるファイルを更新し、文体と用語を揃える流れです。その結果、古い手順を出荷してしまったり、関連ドキュメントの更新漏れが起きたりするリスクを下げられます。

初心者でも使えますか？

はい。ただし、何が出荷され、どのドキュメントをそれに合わせる必要があるのかをユーザーが示せることが前提です。初心者が最良の結果を得やすいのは、変更内容の要約、対象リポジトリのパス、更新したいファイルを明確に渡したときです。

使わないほうがいいのはどんなときですか？

ラフな下書き、製品発表文、未完成コードの推測ベースのドキュメントだけが必要な場合は、document-release を使わないでください。また、リポジトリ履歴や変更済みファイルにアクセスできない場合も不向きです。このスキルは、実際に何が変わったかを根拠に編集することが前提だからです。

document-release スキルを改善する方法

スキルにより具体的なリリースブリーフを与える

品質を最も大きく上げるのは、出荷された挙動の正確な内容、影響を受けるドキュメント、そして残したい文体を明示することです。たとえば、「新しい auth flow の docs を更新し、古いセットアップ手順を削除し、changelog は事実ベースに保ち、影響範囲外の architecture notes は変更しないでください」といった指示が有効です。

よくある失敗パターンを先に伝える

document-release は、古い例、リネームされたコマンド、壊れた相互参照、一緒に更新すべきバージョン文字列があるときに、それを事前に知らせてもらうと最もよく機能します。あるドキュメントが正本で、他が派生物だと分かっているなら、それも明示してください。不要な書き換えを防ぎ、document-release スキルの焦点を絞れます。

1 回目の出力後に反復する

最初の出力では、リンクの抜け、古いスクリーンショットやコードサンプル、ファイル間での用語ぶれ、の 3 点を確認してください。そのうえで、見つかった不足分だけをフィードバックすれば、次のパスで document-release のインストールと使用結果をより精密にできます。安定している部分まで毎回編集し直す必要はありません。

リリースチェックリストとして使う

Technical Writing 向けの document-release では、このスキルをリリース後の QA として扱ってください。ドキュメントが出荷済みの挙動と一致しているか、不要な TODO が残っていないか、バージョン依存の手順が正しいかを確認します。最良の document-release ガイド入力は、モデルが diff とリポジトリを突き合わせて判断できるだけの具体性を持っており、内容を一般論に丸めないことです。