关于 readme-generator
readme-generator 是用于为 GitHub 仓库创建或更新完整 README.md 的技能。工作流涵盖仓库分析、文档章节、项目指标、配置说明与最终校验，并特别关注基于 MkDocs 的教材项目。
主要功能
- 01分析仓库文件与配置
- 02生成技术和许可证徽章
- 03记录项目指标与结构
- 04编写设置和部署说明
- 05校验并整理 README 格式
适用场景
- 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 仓库”徽章。 阅读 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)
步骤 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.
步骤 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)
教科书专属指标：
对于专业教科书，请添加领域专属指标：
- 电路教科书：电路图和模拟的数量
- 历史教科书：时间线、地图和一手资料文档的数量
- 编程教科书：代码示例、练习和项目的数量
- 数学教科书：方程、证明和例题的数量
步骤 7：添加入门指南部分
提供清晰的项目使用和自定义说明。
标准部分：
- 先决条件（如有）
- 克隆仓库
- 安装（如需依赖项）
- 构建站点
- 本地开发
- 部署
示例：
## Getting Started
### Clone the Repository
```bash
git clone https://github.com/username/repo-name.git
cd repo-name
安装依赖项
本项目使用 MkDocs 和 Material 主题：
pip install mkdocs
pip install mkdocs-material
在本地构建和运行
构建站点：
mkdocs build
在本地运行以进行开发（支持实时重新加载）：
mkdocs serve
在浏览器中打开 http://localhost:8000
部署到 GitHub Pages
mkdocs gh-deploy
这将构建站点并将其推送到 gh-pages 分支。
使用本书
导航：
- 使用左侧边栏浏览各章节
- 点击搜索图标搜索全部内容
- 每章都包含测验和练习
交互式 MicroSims：
- 位于“MicroSims”部分
- 每个模拟都可以在浏览器中独立运行
- 使用滑块和控件调整参数
自定义：
- 编辑
docs/中的 markdown 文件以修改内容 - 修改
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 # 章节 markdown │ │ │ └── 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:
[作者姓名]。（2024） 。[教材标题]。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
- 验证 markdown——确保格式正确
- 本地测试——在 GitHub 上渲染 README，检查显示效果
- 拼写检查——检查拼写和语法错误
- 保持一致——确保术语与项目文档一致
质量检查清单：
- 所有徽章均正确显示
- 仓库 URL 正确
- 网站在线 URL 可访问（如适用）
- 指标准确且为最新
- 代码块使用了正确的语法高亮
- 链接均可正常访问
- 目录与各部分一致（如为自动生成）
- 许可证信息清晰
- 联系信息为最新
步骤 15：编写 README.md
在仓库根目录生成最终的 README.md 文件，并按以下顺序包含所有章节：
- 标题（H1），使用仓库名称
- 徽章
- 网站链接（如适用）
- 概览
- 网站状态与指标
- 入门指南
- 仓库结构
- 问题反馈
- 许可证
- 致谢
- 联系方式
- 可选章节（贡献、引用、更新日志）
格式最佳实践：
- 使用 ATX 风格标题（
#，而不是下划线） - 列表前留出空行
- 使用带语言标识符的代码围栏
- 在可行的情况下，将每行控制在 120 个字符以内
- 内部文档使用相对链接
- 较长的 README（超过 500 行）应添加目录
支持脚本
此技能包含用于自动收集指标的 Python 脚本：
scripts/collect-site-metrics.py
扫描仓库并生成指标报告，包括：
- Markdown 文件数和字数
- 章节和小节数
- MicroSim 数量
- 词汇表、常见问题、测验统计数据
- 图片和图表数量
- 学习图谱统计数据
用法：
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
- 验证链接和格式
- 报告：“已创建 README.md，包含 15 个章节、8 个徽章和最新的网站指标（200 个概念、13 个章节、87 个文件、12 个 MicroSim）。上一版 README 已备份到 README-backup.md。”
质量标准
高质量的 README 应包含：
- 所有相关徽章均正确显示
- 准确且最新的指标
- 清晰且引人入胜的概览（200–400 字）
- 完整的入门说明
- 适当的署名和许可信息
- 有效的链接（100% 可用）
- 专业的格式
- 联系方式