readme について
Readmeは、ツールの事実に基づくドキュメント作成や改訂を支援するスキルです。リポジトリの確認、不足情報の質問、READMEの作成、よくある問題の最終チェックを手順化しています。
主な機能
- 01起草前のリポジトリ情報確認
- 02不足情報だけを質問
- 03使い方を中心としたREADME作成
- 04ドキュメント上の問題を点検
- 05既存の正確な記述を維持
活用シーン
- 01ソフトウェアツールのREADME作成
- 02既存READMEの改訂
- 03根拠のない主張や記載漏れの確認
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/readmeを入力して読み込まれたか確認します。
詳細
README
README はツールを説明する文書です。ツールの機能を述べ、実行中の様子を示し、インストール方法、使い方、削除方法を説明します。説得はしません。事実が優れていれば、それだけで README は成り立ちます。事実を飾り立てる必要があるなら、それは文章の問題ではなく、ツールの問題を示しています。
ルール
- 1 行目でそれが何かを述べます。 平易な断定文にします。「cron でスケジュールされた、sqlite データベースのバックアップ。」のように記述します。問題と解決策を提示する構成や、苦労話、「X にうんざりしていませんか？」といった表現は避けます。読者が 5 秒以内に何を見ているのか分かるようにします。
- 早い段階で実際の実行例を示します。 説明より、コマンドと実際の出力のほうが伝わります。理想化した例ではなく、実際のセッションからコピーします。
- 形容詞より事実を優先します。 「高機能」「シンプル」「洗練された」「超高速」「シームレス」といった表現は削除します。代わりに仕組みを述べます。「電光石火の検索」ではなく、「ripgrep を使って 10 万個のファイルを約 50 ミリ秒で検索します」と記述します。
- 何に作用するかを明記します。 コードの実行、フックの登録、ファイルの書き込み、ネットワーク呼び出しを行うものは、無効化またはアンインストールする方法とともに、インストールコマンドの近くに記載します。これは動作に関するドキュメントであり、信頼を得るための工夫ではありません。
- 事実への言及は 1 回にします。 インストール方法を「インストール」セクションに記載したら、ほかの場所では繰り返しません。繰り返しは売り込みのように読めます。
- 内容を削らず、
<details>で折りたたみます。 アーキテクチャの説明、設計の根拠、リファレンステーブルは、内部に Markdown を含む<details>ブロックに入れます（<summary>の後に空行を入れ、</details>の前にも空行を入れます）。 - 物語調にしません。 「これを作った理由は……」「学んだこと」「開発の経緯」「冒頭の理念」などは含めません。設計の根拠が重要なら、折りたたんだセクションに短く記載します。
- 使う順序に沿って並べます。 ツールの概要 → インストール → 使い方／例 → 仕組み → リファレンス／FAQ → ライセンス。ツールを試したい読者が、コマンドを見つけるために理論を読み進めることがないようにします。
ワークフロー
1. まず黙ってコンテキストを集めます
質問する前に、既存のファイルを確認します。README.md、マニフェスト（package.json、pyproject.toml、go.mod、Cargo.toml）、LICENSE、トップレベルのソースディレクトリを読みます。名前、言語、インストールコマンド、ライセンスを推測します。
2. 推測できないことだけを尋ねます
残りの不足情報をまとめて、一度に質問します。質問は次のうち最大 3 つです。
- ツールの機能をコードから明確に判断できない場合は、ツールの機能を 1 文で説明してもらいます
- 実際の実行例となるコマンドと出力（または、ツールを実行して例を取得してよいか）
- シェルコマンド／フックの実行、プロジェクト外へのファイル書き込み、ネットワーク呼び出しの有無
リポジトリ内に答えがある質問は省きます。
3. 作成します
上記のルールに従って README を作成します。構成は固定のテンプレートではなく、内容に合わせます。小さな CLI に必要な情報は、フレームワークに必要な情報の一部で十分です。既存の内容に絵文字が使われていない限り、絵文字は使いません。バッジは、リポジトリにすでにある場合、またはユーザーから求められた場合にのみ追加します。
書き直す場合は、正確な内容を維持し、以下の違反を修正し、現在の README の優れた点は残します。
4. 完了前に自己レビューします
| 違反 | 修正 |
|---|---|
| 冒頭が質問、悩みの提示、「X にうんざりしていませんか？」になっている | ツールが何かを示す平易な文に置き換えます |
| 問題と解決策を売り込む構成になっている | ツールの機能を述べ、売り込みは省きます |
| 数字を伴わない形容詞（「高速」「シンプル」「高機能」）がある | 仕組みや測定値に置き換えるか、削除します |
| セクション間で価値を繰り返し述べている | 最初に記載した事実を残し、ほかは削除します |
| ファイルへの作用／フック／ネットワークの動作が記載されていない | アンインストール方法も含め、インストールの近くに記載します |
| 同じコマンドが 3 か所以上に記載されている | 使い方のセクション 1 か所にまとめます |
| 例より前に開発の経緯や理念がある | 折りたたんだ詳細セクションに移すか、削除します |
| 理想化した出力例を使っている | 実際に取得した出力を使います |
見つけて修正した違反を報告し、意図的な選択についてユーザーが異議を唱えられるようにします。