README ジェネレーター

概要

このスキルは、GitHubプロジェクト用のプロフェッショナルで包括的なREADME.mdファイルの作成を支援します。テンプレート提供、バッジ生成、README品質検証、ドキュメント作成のベストプラクティス適用を行います。

このスキルを使用するタイミング:

• ユーザーがREADME作成のヘルプを求めた時
• ユーザーが既存のREADMEを改善したい時
• ユーザーがプロジェクトドキュメントを必要とする時
• ユーザーがGitHubプロジェクトのセットアップを求めた時
• ユーザーが「ドキュメント」「README」「プロジェクト説明」に言及した時

ワークフロー

優れたREADMEを作成するために、この構造化されたプロセスに従ってください：

ステップ1: プロジェクトを理解する

プロジェクトタイプを判定:

• ライブラリ/パッケージ - 他の開発者向けの再利用可能なコード
• Webアプリケーション - ユーザー向けのWebアプリ
• CLIツール - コマンドラインユーティリティ
• その他 - 特殊なプロジェクト

情報を収集: ユーザーに尋ねるか、analyze_project.pyを使用して推測:

• プロジェクト名
• プログラミング言語
• 主な目的/機能
• 対象ユーザー
• インストール方法
• 基本的な使用例

プロジェクトディレクトリにアクセス可能な場合、実行:

python scripts/analyze_project.py /path/to/project

これにより言語、フレームワーク、CI、テストなどが自動検出されます。

ステップ2: テンプレートを選択

プロジェクトタイプに基づいて適切なテンプレートを選択:

• assets/templates/basic.md - 一般的なプロジェクト
• assets/templates/library.md - ライブラリ/パッケージ
• assets/templates/webapp.md - Webアプリケーション
• assets/templates/cli-tool.md - コマンドラインツール

テンプレート選択ガイド:

npm/PyPI/crates.ioのパッケージなら → library.md
Web UI/フロントエンドがあるなら → webapp.md
主にコマンドラインインターフェースなら → cli-tool.md
それ以外 → basic.md

ステップ3: バッジを生成

プロジェクト情報ファイルを作成:

{
  "project_name": "my-project",
  "username": "github-user",
  "language": "python",
  "package_manager": "pypi",
  "license": "MIT",
  "ci_service": "github-actions",
  "branch": "main"
}

バッジを生成:

python scripts/generate_badges.py project_info.json

これにより以下のマークダウンバッジが出力されます:

• ビルドステータス
• パッケージバージョン
• ダウンロード数
• ライセンス
• 言語

詳細は references/badge-types.md を参照してください。

ステップ4: コンテンツをカスタマイズ

テンプレートのセクションを埋める:

1. タイトルと説明

   • 明確で説明的なタイトル
   • 1-2文の価値提案
   • 生成されたバッジを追加

2. 機能

   • 主要な機能をリスト
   • 絵文字で視覚的な魅力を追加
   • ユーザーのメリットに焦点を当てる

3. インストール

   • assets/snippets/installation.mdのスニペットを使用
   • 前提条件を含める
   • 複数のインストール方法を提供
   • 検証手順を追加

4. クイックスタート

   • 最小限の動作する例
   • コピペ可能
   • 期待される出力を表示

5. 使用方法

   • assets/snippets/usage.mdのスニペットを使用
   • シンプルから高度へと進める
   • コード例を含める
   • コードが何をするか説明

6. APIリファレンス (ライブラリの場合)

   • すべてのパブリックAPIを文書化
   • パラメータ、戻り値、例外を含める
   • 例を提供
   • フォーマットは references/sections-guide.md を参照

7. コントリビューション

   • assets/snippets/contributing.mdのスニペットを使用
   • 貢献者を歓迎
   • 明確な手順を提供
   • 詳細なCONTRIBUTING.mdにリンク

8. ライセンス

   • assets/snippets/license-sections.mdのスニペットを使用
   • ライセンスバッジを含める
   • LICENSEファイルにリンク

セクション固有のガイダンスについては、references/sections-guide.mdを読んでください。

ステップ5: ベストプラクティスを適用

参照: references/best-practices.md に以下が記載:

• 文体ガイドライン
• 構造の推奨事項
• 視覚要素
• アクセシビリティ
• よくある落とし穴

主要な原則:

• 明確で簡潔に
• 能動態を使用
• 動作する例を含める
• スキャン可能にする
• 最新の状態を保つ

ステップ6: 品質を検証

検証を実行:

python scripts/validate_readme.py README.md

検証チェック:

• 必須セクションが存在
• 適切な見出し構造
• コードブロックが正しくフォーマット
• リンクが壊れていない
• 適切な長さ
• 品質スコア (0-100)

バリデーターが報告した問題に対処してください。

ステップ7: 最終レビュー

品質チェックリスト:

• タイトルが明確でプロジェクトと一致
• 説明が1-2文で価値を説明
• インストール手順がテスト済み
• クイックスタート例が動作
• すべてのコード例が有効
• リンクが機能
• 画像が正しく表示
• バッジが正確
• ライセンスが指定
• 機密情報がない

利用可能なリソース

スクリプト (scripts/)

generate_badges.py - shields.ioバッジを生成

python scripts/generate_badges.py project_info.json

ビルドステータス、バージョン、ダウンロード、ライセンス、言語のバッジを作成。

validate_readme.py - README品質を検証

python scripts/validate_readme.py README.md

構造、完全性、フォーマットをチェック。品質スコアを提供。

analyze_project.py - プロジェクト構造を分析

python scripts/analyze_project.py /path/to/project

言語、フレームワーク、CI、パッケージマネージャー、テストなどを自動検出。

リファレンス (references/)

sections-guide.md - 各READMEセクションの包括的ガイド

• 各セクションの書き方
• 良い例と悪い例
• セクション固有のベストプラクティス
• 各セクションのテンプレート

badge-types.md - 完全なバッジカタログ

• 利用可能なすべてのバッジタイプ
• 各バッジの使用方法
• カスタマイズオプション
• バッジのベストプラクティス

best-practices.md - README作成のベストプラクティス

• 一般原則
• 文体
• 構造ガイドライン
• 視覚要素
• アクセシビリティ
• メンテナンスのヒント

examples.md - 優れたREADMEの分析

• 人気プロジェクトからの実例
• 何が優れているか
• 学んだ教訓
• 共通パターン

アセット (assets/)

テンプレート (assets/templates/):

• basic.md - 汎用テンプレート
• library.md - APIドキュメント付きライブラリ/パッケージ用
• webapp.md - スクリーンショット付きWebアプリケーション用
• cli-tool.md - コマンドラインツール用

スニペット (assets/snippets/):

• installation.md - 各種パッケージマネージャーのインストール手順
• usage.md - コード例と使用パターン
• contributing.md - コントリビューションガイドラインテンプレート
• license-sections.md - ライセンスセクションテンプレート

使用パターン

パターン1: ゼロから新しいREADMEを作成

ユーザー: "PythonのWebアプリ用のREADMEが必要です"

1. プロジェクトタイプを特定: Webアプリケーション
2. テンプレートを選択: assets/templates/webapp.md
3. プロジェクト詳細を尋ねる:
   - 名前、説明、機能
   - インストール方法
   - 使用例
4. プロジェクトディレクトリが利用可能なら、analyze_project.pyを実行
5. generate_badges.pyでバッジを生成
6. ユーザーの情報でテンプレートをカスタマイズ
7. validate_readme.pyで検証
8. 完成したREADMEを提示

パターン2: 既存のREADMEを改善

ユーザー: "READMEを改善できますか？" [README.mdを添付]

1. 既存ファイルでvalidate_readme.pyを実行
2. 問題と提案を特定
3. 改善のためにreferences/best-practices.mdを読む
4. 具体的な改善を提案:
   - 不足セクションを追加
   - 例を改善
   - バッジを生成
   - フォーマットを改善
5. 改善を適用
6. 再検証
7. 改善版を提示

パターン3: 簡易README生成

ユーザー: "[project-name]の基本的なREADMEを作って"

1. assets/templates/basic.mdを使用
2. 最小限の情報を記入:
   - タイトル
   - 説明
   - インストール
   - クイックスタート
   - ライセンス
3. READMEを提示
4. 詳細を追加することを提案

パターン4: バッジ生成のみ

ユーザー: "プロジェクトのバッジを生成して"

1. プロジェクト情報を尋ねるか、analyze_project.pyを実行
2. project_info.jsonを作成
3. generate_badges.pyを実行
4. マークダウンバッジを提示
5. READMEへの追加方法を説明

最良の結果を得るためのヒント

1. プロジェクトコンテキストを使用

ユーザーがプロジェクトディレクトリを提供した場合:

• 最初に analyze_project.py を実行
• 検出された情報でテンプレートを自動入力
• 必要な質問が減る

2. テンプレートから開始

常に適切なテンプレートから始める:

• 完全な構造を保証
• プロフェッショナルなレイアウトを提供
• すべての推奨セクションを含む

3. リファレンスを参照

関連するリファレンスファイルを読む:

• sections-guide.md セクション固有のヘルプ用
• best-practices.md 執筆ガイドライン用
• badge-types.md バッジ選択用
• examples.md インスピレーション用

4. 提供前に検証

常に validate_readme.py を実行:

• よくある問題を捕捉
• 品質を保証
• 客観的なスコアを提供

5. 簡潔に保つ

• 重要な情報に焦点
• 高度なトピックは詳細ドキュメントにリンク
• 説明より例を使用
• スキャン可能にする

6. ビジュアルにする

• トップにバッジを追加
• Webアプリにはスクリーンショットを含める
• 機能に絵文字を控えめに使用
• 役立つ場合は図を追加

7. 例をテスト

• すべてのコード例が動作することを確認
• インストール手順を検証
• すべてのリンクをテスト
• コマンドが正常に実行されることを確認

一般的なシナリオ

ライブラリ/パッケージ

重点:

• APIドキュメント
• パッケージマネージャーからのインストール
• コード例
• バージョン互換性

使用: assets/templates/library.md

主要セクション:

• インポート例付きクイックスタート
• APIリファレンス（包括的）
• 開発環境セットアップ
• テスト手順

Webアプリケーション

重点:

• スクリーンショット/デモ
• 機能（視覚的）
• デプロイメントガイド
• 環境セットアップ

使用: assets/templates/webapp.md

主要セクション:

• デモリンク
• スクリーンショット
• インストールとセットアップ
• デプロイメント手順

CLIツール

重点:

• コマンドリファレンス
• 使用例
• インストール方法
• 設定

使用: assets/templates/cli-tool.md

主要セクション:

• コマンド一覧
• オプション/フラグ
• 例
• 設定ファイル

トラブルシューティング

問題: ユーザーがプロジェクト詳細を知らない → analyze_project.py を実行して自動検出 → プレースホルダー付きの基本テンプレートを使用 → 具体的なフォローアップ質問をする

問題: READMEが長すぎる → 複数のドキュメントに分割 → 詳細ガイドにリンク → READMEを概要のみに保つ

問題: 対象ユーザーには技術的すぎる → 言語を簡素化 → より多くの例を追加 → 「How」の前に「What」を含める → 専門用語を避ける

問題: 検証が失敗 → まず重要な問題に対処 → 警告はオプション → バリデーターがフラグを立てた理由を説明 → 修正して再検証

例から学ぶ

references/examples.md ファイルは、人気プロジェクトの優れたREADMEを分析:

• React - 複数のエントリーポイント
• Vue.js - 視覚的魅力、多言語
• Next.js - 機能重視
• Rust - 包括的な学習パス
• TensorFlow - プラットフォームサポート
• FastAPI - パフォーマンス主張
• その他...

このファイルを読んで READMEを成功させる要因を理解してください。

段階的な拡張

シンプルから始めて、必要に応じて複雑さを追加:

レベル1: 最小限

• タイトル、説明、インストール、使用方法、ライセンス

レベル2: 標準

• 追加: 機能、例、コントリビューション、バッジ

レベル3: 包括的

• 追加: APIドキュメント、スクリーンショット、デプロイメント、トラブルシューティング

レベル4: 優秀

• 追加: 動画、図、複数言語、高度な例

プロジェクトサイズと対象ユーザーに合わせてレベルを調整。

最終ノート

覚えておいてください:

• READMEは最初の印象であることが多い
• 良いドキュメントは採用を増やす
• 明確な指示はサポート負担を軽減
• 定期的な更新は積極的なメンテナンスを示す

最高のREADME:

• ユーザーを5分以内に成功に導く
• よくある質問に事前に答える
• すべてのスキルレベルにアクセス可能にする
• プロジェクトが活発で維持されていることを示す

このスキルを使用して、これらの目標を達成するREADMEを作成してください。