| name | readme-generator |
| description | GitHubプロジェクト用の高品質なREADME.mdファイルを生成します。プロジェクトドキュメント、READMEファイル、オープンソースプロジェクトのドキュメント作成時、またはユーザーがドキュメント作成、README作成、プロジェクトセットアップガイドのヘルプを求めた時に使用します。複数のプロジェクトタイプ（ライブラリ、Webアプリ、CLIツール）に対応し、テンプレート、バッジ、ベストプラクティスを提供します。 Use when this capability is needed. |
| metadata | {"author":"dio0550"} |
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-2文の価値提案
- 生成されたバッジを追加
-
機能
- 主要な機能をリスト
- 絵文字で視覚的な魅力を追加
- ユーザーのメリットに焦点を当てる
-
インストール
assets/snippets/installation.mdのスニペットを使用- 前提条件を含める
- 複数のインストール方法を提供
- 検証手順を追加
-
クイックスタート
- 最小限の動作する例
- コピペ可能
- 期待される出力を表示
-
使用方法
assets/snippets/usage.mdのスニペットを使用- シンプルから高度へと進める
- コード例を含める
- コードが何をするか説明
-
APIリファレンス (ライブラリの場合)
- すべてのパブリックAPIを文書化
- パラメータ、戻り値、例外を含める
- 例を提供
- フォーマットは
references/sections-guide.md を参照
-
コントリビューション
assets/snippets/contributing.mdのスニペットを使用- 貢献者を歓迎
- 明確な手順を提供
- 詳細なCONTRIBUTING.mdにリンク
-
ライセンス
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: 最終レビュー
品質チェックリスト:
利用可能なリソース
スクリプト (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を作成してください。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
