readme-generator について
readme-generatorは、GitHubリポジトリのREADME.mdを作成・更新するスキルです。リポジトリの調査から指標やセットアップ手順の記載、最終確認までを扱い、特にMkDocsベースの教科書に対応しています。
主な機能
- 01リポジトリのファイルと設定の調査
- 02技術・ライセンスバッジの生成
- 03プロジェクト指標と構成の記載
- 04セットアップとデプロイ手順の作成
- 05READMEの検証と整形
活用シーン
- 01新しいリポジトリのREADME作成
- 02プロジェクト変更後のドキュメント更新
- 03公開に向けたリポジトリの準備
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/readme-generatorを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
README.mdreferences/badges.mdscripts/collect-site-metrics.pyvalidate-readme.py詳細
README ジェネレーター
ベストプラクティスに沿って、GitHub リポジトリ用の包括的な README.md ファイルを生成または更新します。
目的
このスキルは、GitHub リポジトリ向けに、プロフェッショナルで構成の整った README.md ファイルを自動作成します。使用技術のバッジ、プロジェクトの概要、サイトの指標、利用開始手順、プロジェクト構成、連絡先情報など、必要なセクションをすべて生成します。特に MkDocs ベースのインタラクティブな教科書プロジェクト向けに最適化されていますが、あらゆる種類のリポジトリに応用できます。
このスキルを使うタイミング
次のような場合に、このスキルを使います。
- README.md が必要な新しい GitHub リポジトリを開始するとき
- 既存の README.md をベストプラクティスに沿って更新するとき
- ドキュメントに反映すべき大きなプロジェクト変更の後
- リポジトリを公開または共有する前
- 別のドキュメントシステムから移行するとき
- 新しい技術や依存関係を追加した後
ワークフロー
ステップ 1：リポジトリのコンテキストを分析する
README を生成する前に、リポジトリに関する情報を収集します。
- ルートディレクトリに README.md がすでに存在するか確認します
.git/configまたは作業ディレクトリからリポジトリ名を特定しますmkdocs.ymlが存在する場合は読み込み、以下を抽出します。- サイト名
- サイトの説明
- サイト URL（GitHub Pages リンク用）
- リポジトリ URL
/docsディレクトリにドキュメントがあるか確認します- 使用されている技術を特定します（package.json、requirements.txt、mkdocs.yml などを確認します）
ユーザーへの確認が必要な場合：
- README.md が存在する場合：「README.md はすでに存在します。更新しますか、それとも先にバックアップを作成しますか？」
- リポジトリ URL が見つからない場合：「GitHub リポジトリの URL を教えてください（例：https://github.com/username/repo-name）」
- サイト URL が設定されていない場合：「このサイトは GitHub Pages にデプロイされていますか？デプロイされている場合は、URL を教えてください」
ステップ 2：バッジを生成する
関連する技術やプラットフォームのバッジを作成します。一貫性を保つため、shields.io 形式を使用します。
バッジの順序：
- MkDocs（mkdocs.yml が存在する場合）
- MkDocs Material（テーマが Material の場合）
- GitHub Pages の稼働中バッジ（サイトがデプロイされている場合）
- Claude Code バッジ
- Claude Skills バッジ（.claude/skills または skills/ ディレクトリが存在する場合）
- ライセンスバッジ
- その他の技術バッジ（Python、JavaScript、p5.js など）
README から同じリポジトリへリンクする「GitHub repo」バッジは含めないでください。 README を読む人はすでに GitHub 上にいるか、リポジトリをクローン済みであるため、自身へのリンクを追加しても意味がありません。GitHub Pages バッジは公開サイトという別の場所を指すため、使用してかまいません。
バッジのテンプレート：
[](https://www.mkdocs.org/)
[](https://squidfunk.github.io/mkdocs-material/)
[](SITE_URL)
[](https://claude.ai/code)
[](https://github.com/dmccreary/ibook-skills)
次の追加バッジも確認してください：
- p5.js:
[](https://p5js.org/) - Python:
[](https://www.python.org/) - JavaScript:
[](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
ステップ 3：ライセンスバッジを追加する
次の場所でライセンス情報を確認します。
- ルートにある
LICENSEファイル docs/license.mdmkdocs.yml（copyright フィールド）
指定がない場合は、Creative Commons BY-NC-SA 4.0 をデフォルトとして使用します：
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
その他の一般的なライセンス：
- MIT:
[](https://opensource.org/licenses/MIT) - Apache 2.0:
[](https://opensource.org/licenses/Apache-2.0) - GPL-3.0:
[](https://www.gnu.org/licenses/gpl-3.0)
ステップ 4：ウェブサイトへのリンクセクションを作成する
バッジの後に、公開中のウェブサイトへの目立つリンクを追加します（デプロイされている場合）：
## View the Live Site
Visit the interactive textbook at: [https://username.github.io/repo-name](https://username.github.io/repo-name)
Step 5: 概要／短い説明を書く
次の点に答える、魅力的な1～3段落の概要を作成します。
- このプロジェクトは何ですか？
- 誰を対象としていますか？
- どのような価値がありますか？
- 何が独自で、特別なのですか？
ガイドライン：
- 簡潔ながらも読者を引きつける内容にします
- 能動態を使います
- 主な機能やメリットを強調します
- 該当する場合は、教育フレームワークについて触れます
- 教科書の場合：対象読者（学年、前提知識）を記載します
インテリジェント教科書の例：
## Overview
This is an interactive, AI-generated intelligent textbook on [TOPIC] designed for [AUDIENCE]. Built using MkDocs with the Material theme, it incorporates learning graphs, concept dependencies, interactive MicroSims (p5.js simulations), and AI-assisted content generation.
The textbook follows Bloom's Taxonomy (2001 revision) for learning outcomes and uses concept dependency graphs to ensure proper prerequisite sequencing. All content is generated and curated using Claude AI skills, making it a Level 2+ intelligent textbook with interactive elements.
Whether you're a student learning [TOPIC] for the first time or an educator looking for structured course materials, this textbook provides comprehensive coverage with hands-on interactive elements that make complex concepts accessible and engaging.
Step 6: サイトのステータスと指標を追加する
プロジェクトの完成度と規模を示すため、プロジェクトの指標を収集して表示します。
正規の指標ファイルを読み取ってください。件数を再計算しないでください。
書籍全体の集計値を確認する唯一の情報源は
docs/learning-graph/book-metrics.json です（book-metrics ツールによって生成され、
src/book-metrics/book-metrics.schema.json に照らして検証されます）。README の指標は
必ずこのファイルを参照し、README、LinkedIn の告知、事例紹介カードで同じ数値を表示してください。
# 1. Make sure the file is fresh (regenerate if missing or stale):
bk-generate-book-metrics 2>/dev/null \
|| python3 "$BK_HOME/src/book-metrics/book-metrics.py" docs
# 2. Read the totals:
python3 - <<'PY'
import json, pathlib
m = json.loads(pathlib.Path("docs/learning-graph/book-metrics.json").read_text())["metrics"]
for k in ("concepts","chapters","microsims","glossaryTerms","faqs",
"quizQuestions","words","diagrams","references","equivalentPages",
"developmentStage"):
print(f"{k}: {m.get(k)}")
PY
metrics オブジェクトには、concepts、chapters、microsims、stories、
glossaryTerms、faqs、quizQuestions、chapterQuizzes、chapterReferences、
references、diagrams、equations、words、links、appendices、
mascotImages、developmentStage、equivalentPages が含まれます。識別情報
（タイトル、著者、リポジトリの URL、ライセンス）については、book-metadata.json／
mkdocs.yml を参照してください。
指標ファイルにない件数を取得する場合に限り、scripts/collect-site-metrics.py
（Markdown／画像のスキャン）を使用してください。たとえば、画像アセット数や
コードブロック数です。概念／章／単語数を手作業で数え直さないでください。
表形式で記載します：
## Site Status and Metrics
| Metric | Count |
|--------|-------|
| Concepts in Learning Graph | 200 |
| Chapters | 13 |
| Markdown Files | 87 |
| Total Words | 45,230 |
| MicroSims | 12 |
| Glossary Terms | 187 |
| FAQ Questions | 42 |
| Quiz Questions | 156 |
| Images | 34 |
| References | 28 |
**Completion Status:** Approximately 85% complete (content generation phase)
教科書固有の指標：
専門的な教科書では、分野固有の指標を追加します。
- 回路の教科書：回路図とシミュレーションの数
- 歴史の教科書：年表、地図、一次資料の数
- プログラミングの教科書：コード例、演習、プロジェクトの数
- 数学の教科書：方程式、証明、計算例の数
Step 7: はじめにセクションを追加する
プロジェクトの使用方法とカスタマイズ方法を、わかりやすく説明します。
標準的なセクション：
- 前提条件（ある場合）
- リポジトリをクローンする
- インストール（依存関係が必要な場合）
- サイトをビルドする
- ローカルで開発する
- デプロイする
例：
## Getting Started
### Clone the Repository
```bash
git clone https://github.com/username/repo-name.git
cd repo-name
依存関係をインストールする
このプロジェクトでは、Material テーマを使った MkDocs を使用します。
pip install mkdocs
pip install mkdocs-material
ローカルでビルドして起動する
サイトをビルドします。
mkdocs build
開発用にローカルで起動します（ライブリロード対応）。
mkdocs serve
ブラウザーで http://localhost:8000 を開きます
GitHub Pages にデプロイする
mkdocs gh-deploy
これにより、サイトがビルドされ、gh-pages ブランチにプッシュされます。
書籍の利用方法
ナビゲーション：
- 左側のサイドバーを使って各章を閲覧します
- 検索アイコンをクリックすると、すべてのコンテンツを検索できます
- 各章にはクイズと練習問題が含まれています
インタラクティブな MicroSims：
- 「MicroSims」セクションにあります
- 各シミュレーションはブラウザー上で単独で実行されます
- スライダーやコントロールでパラメーターを調整します
カスタマイズ：
docs/内のマークダウンファイルを編集してコンテンツを変更しますmkdocs.ymlを変更してサイト構成を変更しますdocs/sims/に独自の MicroSims を追加しますdocs/css/extra.cssでテーマをカスタマイズします
### Step 8: Document Repository Structure
Create an ASCII tree diagram showing the repository structure with explanatory comments.
**Use this approach:**
- Don't list every single file
- Show representative examples
- Add comments explaining each major directory
- Keep it concise (10-20 lines)
**Example:**
```markdown
## Repository Structure
repo-name/ ├── docs/ # MkDocs ドキュメントのソース │ ├── chapters/ # 章のコンテンツ │ │ ├── 01-intro/ │ │ │ ├── index.md # 章のマークダウン │ │ │ └── quiz.md # 章のクイズ │ │ └── 02-concepts/ │ ├── sims/ # インタラクティブな p5.js MicroSims │ │ ├── graph-viewer/ │ │ │ ├── main.html # 単独で動作するシミュレーション │ │ │ └── index.md # ドキュメント │ ├── learning-graph/ # 学習グラフのデータと分析 │ │ ├── learning-graph.csv # 概念の依存関係 │ │ ├── learning-graph.json # vis-network 形式 │ │ └── quality-metrics.md # 品質分析 │ ├── glossary.md # ISO 11179 準拠の定義 │ ├── faq.md # よくある質問 │ └── references.md # 厳選した参考資料 ├── skills/ # Claude AI スキル（存在する場合） │ └── [skill-name]/ │ ├── SKILL.md # スキルの定義 │ └── *.py # 補助スクリプト ├── mkdocs.yml # MkDocs の設定 └── README.md # このファイル
ステップ 9：課題報告セクションを追加する
GitHub Issues ページをユーザーに案内します：
## Reporting Issues
Found a bug, typo, or have a suggestion for improvement? Please report it:
[GitHub Issues](https://github.com/username/repo-name/issues)
When reporting issues, please include:
- Description of the problem or suggestion
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- Screenshots (if applicable)
- Browser/environment details (for MicroSims)
ステップ 10：ライセンス情報を追加する
ライセンス条件と帰属表示の要件を明確にします：
## License
This work is licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
**You are free to:**
- Share — copy and redistribute the material
- Adapt — remix, transform, and build upon the material
**Under the following terms:**
- **Attribution** — Give appropriate credit with a link to the original
- **NonCommercial** — No commercial use without permission
- **ShareAlike** — Distribute contributions under the same license
See [LICENSE.md](docs/license.md) for full details.
ステップ 11：謝辞を追加する
オープンソースコミュニティと主要なプロジェクトに感謝を伝えます：
## Acknowledgements
This project is built on the shoulders of giants in the open source community:
- **[MkDocs](https://www.mkdocs.org/)** - Static site generator optimized for project documentation
- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)** - Beautiful, responsive theme
- **[p5.js](https://p5js.org/)** - Creative coding library from NYU ITP
- **[vis-network](https://visjs.org/)** - Network visualization library for learning graphs
- **[Python](https://www.python.org/)** community - Data processing and analysis tools
- **[Claude AI](https://claude.ai)** by Anthropic - AI-assisted content generation
- **[GitHub Pages](https://pages.github.com/)** - Free hosting for open source projects
Special thanks to the educators and developers who contribute to making educational resources accessible and interactive.
実際の依存関係に応じてカスタマイズします：
- バブルチャートを使用している場合は、Chart.js を追加します
- 図を使用している場合は、Mermaid を追加します
- 使用している場合は、具体的な Python ライブラリ（pandas、numpy など）を追加します
- その他の主要な依存関係も追加します
ステップ 12：連絡先セクションを追加する
ユーザーが連絡できる方法を用意します：
## Contact
**Dan McCreary**
- LinkedIn: [linkedin.com/in/danmccreary](https://www.linkedin.com/in/danmccreary/)
- GitHub: [@dmccreary](https://github.com/dmccreary)
Questions, suggestions, or collaboration opportunities? Feel free to connect on LinkedIn or open an issue on GitHub.
実際のメンテナー情報に合わせてカスタマイズします：
- リポジトリ所有者の名前に置き換えます
- LinkedIn の URL を更新します
- GitHub のユーザー名を更新します
- 必要に応じてメールアドレスを追加します（任意）
- 関連する場合はウェブサイトやブログを追加します
ステップ 13：任意のセクションを追加する
プロジェクトに関連する場合は、次のセクションを含めます：
コントリビューションガイドライン：
## Contributing
Contributions are welcome! To contribute:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
引用情報：
## How to Cite
If you use this textbook in your research or teaching, please cite it as:
[Author Name]. (2024). [Textbook Title]. GitHub. https://github.com/username/repo-name
BibTeX:
```bibtex
@misc{repo-name-2024,
author = {[Author Name]},
title = {[Textbook Title]},
year = {2024},
publisher = {GitHub},
url = {https://github.com/username/repo-name}
}
**Changelog:**
```markdown
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
**Recent Updates:**
- v1.0.0 (2024-11-11): Initial release with 13 chapters
- v0.9.0 (2024-11-01): Added 12 MicroSims and interactive elements
- v0.5.0 (2024-10-15): Completed learning graph and chapter structure
ステップ 14：検証と書式設定を行う
README を完成させる前に、次の点を確認します：
- すべてのリンクを確認する - GitHub の URL、サイトの URL、バッジの URL を確認します
- マークダウンを検証する - 書式が適切であることを確認します
- ローカルでテストする - GitHub 上で README をレンダリングし、表示を確認します
- スペルチェックを行う - 誤字脱字や文法を確認します
- 一貫性を確認する - 用語がプロジェクトのドキュメントと一致していることを確認します
品質チェックリスト：
- すべてのバッジが正しく表示される
- リポジトリの URL が正しい
- 公開サイトの URL が機能する（該当する場合）
- 指標が正確かつ最新である
- コードブロックに適切なシンタックスハイライトが適用されている
- リンクが切れていない
- 目次が各セクションと一致している（自動生成の場合）
- ライセンス情報が明確である
- 連絡先情報が最新である
ステップ 15：README.md を作成する
以下のすべてのセクションを順番に含む最終版の README.md ファイルを、リポジトリのルートに生成します。
- リポジトリ名を含むタイトル（H1）
- バッジ
- ライブサイトへのリンク（該当する場合）
- 概要
- サイトのステータスとメトリクス
- はじめに
- リポジトリの構成
- 問題の報告
- ライセンス
- 謝辞
- お問い合わせ
- 任意のセクション（貢献、引用、変更履歴）
書式設定のベストプラクティス：
- ATX スタイルの見出しを使用します（下線ではなく
#）。 - リストの前に空行を入れます。
- 言語を指定したコードフェンスを使用します。
- 実用上可能な範囲で、行の長さを120文字未満にします。
- 内部ドキュメントには相対リンクを使用します。
- README が長い場合（500行超）は目次を追加します。
補助スクリプト
このスキルには、メトリクスを自動収集するための Python スクリプトが含まれています。
scripts/collect-site-metrics.py
リポジトリをスキャンし、以下を含むメトリクスレポートを生成します。
- Markdown ファイル数と単語数
- チャプター数とセクション数
- MicroSim の数
- 用語集、FAQ、クイズの統計
- 画像と図表の数
- 学習グラフの統計
使用方法：
cd skills/readme-generator/scripts
python collect-site-metrics.py /path/to/repo
出力：すべてのメトリクスを含む JSON オブジェクト
scripts/validate-readme.py
以下について README.md を検証します。
- 必須セクションの有無
- リンクの有効性
- バッジ URL の有効性
- Markdown の書式が適切であること
使用方法：
python validate-readme.py README.md
出力ファイル
必須：
README.md- リポジトリのルートに置く完全版の README
任意：
README-backup.md- 以前の README のバックアップ（更新時）docs/readme-metrics.json- JSON 形式のメトリクスデータ
セッション例
ユーザー：「このリポジトリの README を生成してください」
Claude（このスキルを使用）：
- README.md が存在するか確認します（存在するため、バックアップを作成します）
mkdocs.ymlを読み込み、サイト情報を抽出します- 使用技術を特定します：MkDocs、Material、p5.js、Python
/docsをスキャンしてメトリクスを収集します（チャプター、MicroSim、用語集）collect-site-metrics.pyを実行して統計情報を収集します- 特定したすべての技術についてバッジを生成します
- 12のセクションを含む包括的な README.md を作成します
- リンクと書式を検証します
- 次のように報告します：「15のセクション、8個のバッジ、最新のサイトメトリクス（200の概念、13のチャプター、87個のファイル、12個の MicroSim）を含む README.md を作成しました。以前の README は README-backup.md にバックアップしました。」
品質基準
高品質な README には、以下が含まれている必要があります。
- 関連するすべてのバッジが正しく表示されている
- 正確で最新のメトリクス
- 明確で魅力的な概要（200～400語）
- 完全なセットアップ手順
- 適切なクレジット表記とライセンス
- 有効なリンク（すべて機能すること）
- プロフェッショナルな書式
- 連絡先情報