Claudeのdocumentationスキルで、README・runbook・導入資料を書く

engineeringプラグインのdocumentationスキルは、技術文書を5つの種別に分けて書くスキルです。README、APIドキュメント、runbook、アーキテクチャ文書、オンボーディングガイドの5種で、種別ごとに入れる項目があらかじめ決まっています。

SKILL.mdは約50行と短く、中身は種別ごとの項目表と5つの原則だけです。短いぶん、使い方の勘所は「どの種別を選ぶか」と「何を渡すか」に集まります。この記事では、入れ方、5種別の項目、種別の選び方、渡す材料、CLAUDE.mdへの載せ方を順に説明します。

documentationスキルが担う範囲

SKILL.mdの説明文は、このスキルを技術文書の作成と保守のためのものとしています。呼び出しのきっかけとして挙がっている語句は、次の5つです。

• 「write docs for」
• 「document this」
• 「create a README」
• 「write a runbook」
• 「onboarding guide」

APIドキュメント、アーキテクチャ文書、運用手順書(runbook)を含む技術文書全般が対象です。engineeringプラグインのREADMEでは、code-review や tech-debt と並ぶ6つのスキルのひとつで、「ドメイン知識としてClaudeが関連する場面で自動的に使う」側に分類されています。

architectureスキルのように /architecture と書けるコマンド版はありません。READMEのコマンド一覧にあるのは /standup、/review、/debug、/architecture、/incident、/deploy-checklist の6つで、documentationはそこに入っていません。

ただし、SKILL.mdのフロントマターは name と description の2項目だけです。呼び出しを自動に限る disable-model-invocation も、直接呼び出しを禁じる user-invocable: false も書かれていません。Claude Codeの公式ドキュメントでは、どちらも既定では無効です。つまり話題に応じた自動起動に加えて、プラグインのスキルを /プラグイン名:スキル名 で呼ぶ形、ここでは /engineering:documentation でも呼べる想定です。

engineeringプラグインを入れる

導入はマーケットプレイスの追加とプラグインの導入の2コマンドです。

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install engineering@knowledge-work-plugins

入れたあと、/engineering:documentation に続けて文書の種別と対象を書けば始められます。自動起動に任せる場合も、「READMEを書いて」「このサービスのrunbookを作って」のように種別を言葉にしておくと、スキルが選ばれやすくなります。

Claude Codeでの導入のスコープ(ユーザー・プロジェクト)や、チームへの配り方は、同じプラグインを扱うarchitectureスキルの記事に詳しく書いています。

5種別に入れる項目

SKILL.mdが種別ごとに挙げている項目は、次のとおりです。

READMEのクイックスタートにだけ「5分未満」という数値の基準が付いています。ほかの種別は、項目名が並ぶだけで分量の指定はありません。

種別の選び方 — 読み手と使う場面で決める

SKILL.mdの最初の原則は「読み手のために書く」で、「誰が読み、何を必要としているか」を問います。種別選びも同じ問いから決まります。迷いやすい組み合わせを、読み手の動作で分けてみます。

この表は、SKILL.mdの項目から導いた分け方の一例です。公式の判定基準ではありません。

アーキテクチャ文書とADRは別物

アーキテクチャ文書の項目には「主な決定とトレードオフ」が入ります。ただし、個々の技術選定を1件ずつ記録するのはADRの役割です。engineeringプラグインでは、決定1件を残すならarchitectureスキル、システム全体の説明ならdocumentationスキルのアーキテクチャ文書、と分かれます。

前者の記録を積んでおき、後者からリンクする形にすると、SKILL.mdの5つめの原則「リンクして、複製しない」と合います。

runbookは書く場面が2つある

runbookには、定常作業用と障害対応用があります。障害対応そのものの流れ、状況更新の型、ポストモーテムはincident-responseスキルが扱います。documentationスキルのrunbookは、そこで参照される「手順書」の側を書くための型です。

なお、operationsプラグインにもrunbookの作成があります。そちらは業務運用の手順書が主題です。比較はoperationsプラグインの記事を参照してください。

種別ごとに渡す材料

スキルは、渡された情報から文書を組み立てます。項目表の欄を埋められるだけの材料がなければ、一般論で埋まった文書になります。種別ごとに、次の材料を添えると項目が具体的になります。以下は項目表から逆算した一例です。

• README: 実際に動かすコマンド、必要なランタイムの版、設定の環境変数名、ライセンスと貢献の窓口
• APIドキュメント: OpenAPI定義やルーターのコード、認証方式、エラー応答の実例、レート制限の値
• Runbook: 対象システムの構成、手順で使うコマンド、必要な権限の名前、直前の状態に戻す方法、連絡先と当番表
• アーキテクチャ文書: 構成図の元データ、既存のADR、非機能要件、連携先システムの一覧
• オンボーディングガイド: セットアップ手順の実績、主要リポジトリの一覧、担当者とチャンネルの対応表

Claude Codeなら、材料を貼る必要はありません。リポジトリを読ませる形で渡せます。

/engineering:documentation このリポジトリのREADMEを書いて。
package.jsonのscriptsとdocker-compose.ymlを読んで、
クイックスタートはコマンドを順に実行して確認してから書く

最後の一文が効きます。READMEの「5分未満で最初の成功」は、書き手が実際に通したかどうかで品質が分かれます。Claude Codeはシェルを実行できるので、書いたクイックスタートを自分で走らせる指示を足せます。公式のワークフロー集にも、生成後に「プロジェクトの基準に沿っているか確認して」と頼む手順があります。

渡さないと空欄になりやすい項目

Runbookの「前提条件と必要な権限」「エスカレーション経路」、オンボーディングの「誰に何を聞くか」は、コードからは読み取れません。組織の情報だからです。渡さないまま書かせると、もっともらしい名前が入る恐れがあります。

これらは「未定の項目は TBD と書き、推測で埋めない」と指示しておくと、人が埋めるべき箇所が文書に残ります。

5つの原則をレビューの観点に使う

SKILL.mdの原則は、書かせるときだけでなく、出てきた文書を読むチェックリストにもなります。

1. 読み手のために書く
2. 最も役に立つ情報から始める
3. 見せる(コード例、コマンド、スクリーンショット)
4. 最新に保つ(古い文書は無いより悪い)
5. リンクして、複製しない

レビューでは、各原則を問いに変えると使いやすくなります。冒頭の3行で、読み手が目的を判断できるか。手順にコマンドがあるか。別の文書に書いてある内容を、写していないか。

4つめの「最新に保つ」は、書いた後の話です。スキルは文書を一度作るのは得意でも、コードが変わったときに更新を促す仕組みは持ちません。次の節のとおり、保守のルールはリポジトリ側に置きます。

CLAUDE.mdに文書の規約を書く

SKILL.mdには、文書の保存先、ファイル名、文体の指定がありません。ここはチーム側で決める部分です。プロジェクトのCLAUDE.mdに、次のような節を足すと、毎回の指示が減ります。保存先は一例なので、チームの慣行に合わせて変えてください。

## ドキュメントの書き方
- 技術文書の作成は /engineering:documentation を使う
- READMEのクイックスタートは、書いた後に実際のコマンドで通して確認する
- runbookは docs/runbooks/ に置き、手順の末尾にロールバックと連絡先を必ず書く
- 設計判断は docs/adr/ のADRに残し、アーキテクチャ文書からはリンクで参照する
- コードの挙動を変えるPRでは、関連する文書の更新も同じPRに含める

最後の1行が、原則4に当たる運用です。更新漏れを防ぐには、人の注意に頼らず、PRの作法に入れるほうが残ります。

JSDocやdocstringの一括生成、変更ログの更新、CIからの生成は、スキルではなくClaude Code本体の使い方としてドキュメント生成の記事にまとめています。documentationスキルは、そのコード内コメントより上の層、つまり人に向けた文書の型を担当します。

コネクタで既存の文書基盤とつなぐ

READMEの連携表では、Notion、Confluenceが「ナレッジベース」として挙がり、ADR、runbook、オンボーディング資料を扱う基盤と位置づけられています。ソース管理(GitHub、GitLab)や監視(Datadog、New Relic)もつなげられます。

READMEは、すべてのコマンドとスキルが単体でも動く、と書いています。コネクタなしでも、システムの説明を貼れば文書は書けます。つなぐ価値が出るのは、文書の元になる情報、たとえば既存のrunbookや過去の障害対応記録が基盤側にあるときです。

どのコネクタがどの文書に効くのかは、documentationのSKILL.mdには書かれていません。READMEの表は、engineeringプラグイン全体についての一覧です。

まとめ

documentationスキルの中身は、5種別の項目表と5つの原則に尽きます。項目表は埋めるべき欄の見取り図で、原則はレビューの観点です。実際の中身は、渡す材料と、保存先・更新ルールを決めるCLAUDE.mdで決まります。

特に、組織の情報(権限、連絡先、担当者)はコードから読み取れません。ここを人が埋める前提で運用すると、もっともらしい架空の名前が文書に混ざる事故を避けられます。