tomevault-io 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: 最終レビュー
品質チェックリスト:
- タイトルが明確でプロジェクトと一致
- 説明が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を作成してください。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.