technical-writer について
technical-writerは、特定の読者に向けたタスク中心の技術文書を作成するスキルです。文書の種類を選び、ソースファイルで事実を確認し、テンプレートを使って手順を検証することで、正確で実行可能な文書を目指します。
主な機能
- 01読者、タスク、前提知識の明確化
- 02目的に応じた文書タイプの選択
- 03コードベースに基づく事実確認
- 04テンプレートとスタイルガイドでの執筆
- 05手順の段階的なテスト
活用シーン
- 01新規コントリビューター向けセットアップガイドの作成
- 02管理者向け設定手順の文書化
- 03よくある問題のトラブルシューティング作成
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/technical-writerを入力して読み込まれたか確認します。
同梱ファイルreferences/style-guide.mdreferences/templates.md
詳細
テクニカルライター
特定の読者が、誰にも聞かずに特定のタスクを完了できるドキュメントを作成します。
ワークフロー
-
読者とタスクを明確にします。 次の形式で一文にまとめます。「[読者]は[何をする必要があり]、[何をすでに知っています]。」リポジトリをセットアップする新しいコントリビューター、SSO を設定する管理者、アーキテクチャを評価するエグゼクティブには、それぞれ異なるドキュメントが必要です。依頼に記載がない場合は、文脈から推測し、草稿の冒頭でその前提を明示します。
-
ドキュメントの種類を選びます。 各種類が答える問いは一つです。種類を混ぜることは、ドキュメントが分かりにくくなる最も一般的な原因です。
読者の目的 種類 構成 初めて、実践しながら学ぶ チュートリアル 確実に動作する一つの手順を最初から最後まで示す 既知のタスクを完了する ハウツーガイド 目標、前提条件、番号付きの手順、確認 情報を調べる リファレンス 表とリストを網羅的かつ一貫性のある形で示す 理由を理解する 解説／アーキテクチャ 背景、設計、トレードオフ 壊れたものを修正する トラブルシューティング 症状、原因、修正方法 README は入り口です。概要、クイックスタート、ほかのドキュメントへのリンクを記載します。各種類のテンプレートは references/templates.md にあります。
-
記憶ではなく、情報源から事実を集めます。 コードベースでは、エントリーポイント、
package.json／pyproject.toml／Makefileのスクリプト、設定ファイル、環境変数の使用箇所（grep -r "process.env\|os.environ"）、既存のドキュメントを確認します。ドキュメントに記載するすべてのコマンド、フラグ、ファイルパス、環境変数、デフォルト値は、読んだものか実行したものに基づいている必要があります。事実を検証できない場合は、推測せず[VERIFY: ...]と記載します。 -
テンプレートを使って草稿を作成し、 references/style-guide.md を適用します。最も一般的なタスクから説明します。前提条件は手順の途中ではなく、手順 1 の前に記載します。
-
ドキュメントをテストします。 コマンドを実行できる場合は、クリーンな状態から手順を順番に進め、失敗する箇所や、明記されていない手順が必要な箇所を修正します。実行できない場合は、読者の立場で読み直します。ドキュメントと前提条件だけで、すべての手順を実行できるでしょうか？
-
成果物を納品します。 解説文で包まず、実際のファイル（例：
README.mdやdocs/setup.md）として納品します。その後、すべての[VERIFY]マーカー、読者に関する前提、更新のきっかけとなる変更（設定形式の変更、必須環境変数の追加など）を列挙します。
作業例
依頼：「このリポジトリの新しい開発者向けにセットアップドキュメントを書いてください。」
- 読者とタスク：TypeScript は知っているが、このリポジトリについては知らない開発者が、ローカル環境を起動し、テストスイートに合格する必要があります。
- 種類：既知のタスクを扱うハウツーガイドと、そこへのリンクを記載した短い README セクション。
- 収集した事実：
package.jsonのスクリプトdev、test、db:migrate、.env.exampleに記載されたDATABASE_URLとSTRIPE_SECRET_KEY、Postgres 17 を起動するdocker-compose.yml、>=22のengines.node。 - 草稿：前提条件（Node 22 以降、Docker）→クローンとインストール→
.env.exampleを.env.localにコピーし、各変数の用途を説明→docker compose up -d→npm run db:migrate→期待される URL を示してnpm run devを実行→期待される出力を示してnpm testを実行→ポート 5432 がすでに使用中の場合と、DATABASE_URLがない場合のトラブルシューティング。 - テスト：手順を実行したところ、アプリに必要なシード手順（
npm run db:seed）が見つかったため、手順 6 として追加しました。
失敗につながる要因
- 詳細の捏造。 もっともらしく見えても、存在しないフラグや環境変数は、記載がない場合より読者に大きな負担をかけます。確認するか、未確認であることを明記してください。
- 手順を説明文に詰め込む。 読者が順番に作業するなら、番号を付けてください。各ステップでは操作を1つだけ行います。
- 期待される結果の欠如。 出力があるコマンドの後には、成功時の表示例を示し、順調に進んでいることを読者が確認できるようにしてください。
- 種類の混在。 設計上の判断を逐一説明してチュートリアルを中断すると、学習者の理解を妨げます。説明へのリンクを用意してください。
- 古いスクリーンショットやバージョン。 変更されるUIについては、スクリーンショットよりテキストを優先してください。バージョンが重要な場合に限って固定し、そのバージョンの参照元を記載してください。
- 成功する手順だけの説明。 初めて読む人が遭遇しやすい失敗を2つか3つ追加してください。