readme-generator by dmccreary/claude-skills
npx skills add https://github.com/dmccreary/claude-skills --skill readme-generator为 GitHub 仓库生成或更新遵循最佳实践的综合性 README.md 文件。
此技能自动化创建适用于 GitHub 仓库的专业、结构良好的 README.md 文件。它生成所有基本部分,包括所用技术的徽章、项目概述、站点指标、入门指南、项目结构和联系信息。该技能特别针对基于 MkDocs 的智能教科书项目进行了优化,但可适用于任何类型的仓库。
在以下情况下使用此技能:
在生成 README 之前,收集有关仓库的信息:
.git/config 或工作目录识别仓库名称mkdocs.yml 以提取:
/docs 目录中的文档用户对话触发器:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
为所有相关技术和平台创建徽章。使用 shields.io 格式以确保一致性。
徽章顺序:
徽章模板:
[](https://www.mkdocs.org/)
[](https://squidfunk.github.io/mkdocs-material/)
[](SITE_URL)
[](REPO_URL)
[](https://claude.ai/code)
[](https://github.com/dmccreary/claude-skills)
检查以下附加徽章:
[](https://p5js.org/)[](https://www.python.org/)[](https://developer.mozilla.org/en-US/docs/Web/JavaScript)在以下位置查找许可证信息:
LICENSE 文件docs/license.mdmkdocs.yml(版权字段)如果未指定,默认使用 Creative Commons BY-NC-SA 4.0:
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
其他常见许可证:
[](https://opensource.org/licenses/MIT)[](https://opensource.org/licenses/Apache-2.0)[](https://www.gnu.org/licenses/gpl-3.0)在徽章之后,添加一个指向实时网站的显著链接(如果已部署):
## 查看实时网站
访问交互式教科书:[https://username.github.io/repo-name](https://username.github.io/repo-name)
创建引人入胜的 1-3 段概述,回答以下问题:
指南:
智能教科书示例:
## 概述
这是一本关于 [主题] 的交互式、AI 生成的智能教科书,专为 [受众] 设计。使用 MkDocs 和 Material 主题构建,它融合了学习图谱、概念依赖关系、交互式 MicroSims(p5.js 模拟)和 AI 辅助内容生成。
该教科书遵循布鲁姆分类法(2001 年修订版)的学习成果,并使用概念依赖图来确保正确的先决条件排序。所有内容均使用 Claude AI 技能生成和策划,使其成为具有交互元素的 Level 2+ 智能教科书。
无论您是第一次学习 [主题] 的学生,还是寻找结构化课程材料的教师,这本教科书都提供了全面的覆盖范围,并配有动手实践的交互元素,使复杂概念易于理解和参与。
收集并显示项目指标,以展示完整性和范围。
运行 Python 脚本以收集指标:
调用 scripts/collect-site-metrics.py(或根据需要创建)以收集:
学习图谱指标(来自 docs/learning-graph/):
内容指标:
docs/chapters/ 中的目录)docs/ 中的 .md 文件)交互元素:
docs/sims/ 中的目录)quiz.md 的文件)教育资源:
docs/glossary.md 中)docs/faq.md 中)docs/references.md 中)媒体资源:
.png、.jpg、.svg 文件)格式化为表格:
## 站点状态和指标
| 指标 | 数量 |
|--------|-------|
| 学习图谱中的概念 | 200 |
| 章节 | 13 |
| Markdown 文件 | 87 |
| 总字数 | 45,230 |
| MicroSims | 12 |
| 术语表条目 | 187 |
| 常见问题解答问题 | 42 |
| 测验问题 | 156 |
| 图像 | 34 |
| 参考文献 | 28 |
**完成状态:** 约 85% 完成(内容生成阶段)
特定书籍指标:
对于专业教科书,添加特定领域的指标:
提供使用和自定义项目的清晰说明。
标准部分:
示例:
## 入门指南
### 克隆仓库
```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
mkdocs gh-deploy
这将构建站点并将其推送到 gh-pages 分支。
导航:
交互式 MicroSims:
自定义:
编辑 docs/ 中的 Markdown 文件以修改内容
修改 mkdocs.yml 以更改站点结构
在 docs/sims/ 中添加您自己的 MicroSims
在 docs/css/extra.css 中自定义主题
创建 ASCII 树状图,显示仓库结构并附有解释性注释。
使用此方法:
示例:
## 仓库结构
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 # 此文件
引导用户访问 GitHub Issues 页面:
## 报告问题
发现错误、拼写错误或有改进建议?请报告:
[GitHub Issues](https://github.com/username/repo-name/issues)
报告问题时,请包括:
- 问题或建议的描述
- 重现步骤(针对错误)
- 预期与实际行为
- 截图(如果适用)
- 浏览器/环境详细信息(针对 MicroSims)
重申许可条款和归属要求:
## 许可证
本作品采用 [知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议](https://creativecommons.org/licenses/by-nc-sa/4.0/) 进行许可。
**您可以自由地:**
- 共享 — 复制和重新分发材料
- 演绎 — 修改、转换和基于材料创作
**在以下条件下:**
- **署名** — 必须给出适当的署名,并提供指向原始作品的链接
- **非商业性使用** — 未经许可不得用于商业目的
- **相同方式共享** — 如果您修改、转换或基于本作品进行创作,您必须采用与本作品相同的许可协议分发您的贡献
有关完整详情,请参阅 [LICENSE.md](docs/license.md)。
向开源社区和关键项目表示感谢:
## 致谢
本项目建立在开源社区巨人的肩膀上:
- **[MkDocs](https://www.mkdocs.org/)** - 针对项目文档优化的静态站点生成器
- **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)** - 美观、响应式的主题
- **[p5.js](https://p5js.org/)** - 来自纽约大学 ITP 的创意编码库
- **[vis-network](https://visjs.org/)** - 用于学习图谱的网络可视化库
- **[Python](https://www.python.org/)** 社区 - 数据处理和分析工具
- **[Claude AI](https://claude.ai)** by Anthropic - AI 辅助内容生成
- **[GitHub Pages](https://pages.github.com/)** - 开源项目的免费托管服务
特别感谢为教育资源可访问性和交互性做出贡献的教育工作者和开发者。
根据实际依赖项进行自定义:
提供用户联系的方式:
## 联系
**Dan McCreary**
- LinkedIn: [linkedin.com/in/danmccreary](https://www.linkedin.com/in/danmccreary/)
- GitHub: [@dmccreary](https://github.com/dmccreary)
有问题、建议或合作机会?欢迎在 LinkedIn 上联系或在 GitHub 上提出问题。
使用实际维护者信息进行自定义:
如果与项目相关,包括以下部分:
贡献指南:
## 贡献
欢迎贡献!贡献方式:
1. Fork 仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开 Pull Request
请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细指南。
引用信息:
## 如何引用
如果您在研究中或教学中使用此教科书,请引用为:
[作者姓名]. (2024). [教科书标题]. GitHub. https://github.com/username/repo-name
BibTeX:
```bibtex
@misc{repo-name-2024,
author = {[作者姓名]},
title = {[教科书标题]},
year = {2024},
publisher = {GitHub},
url = {https://github.com/username/repo-name}
}
**更新日志:**
```markdown
## 更新日志
有关变更的详细历史,请参阅 [CHANGELOG.md](CHANGELOG.md)。
**近期更新:**
- v1.0.0 (2024-11-11): 初始发布,包含 13 个章节
- v0.9.0 (2024-11-01): 添加了 12 个 MicroSims 和交互元素
- v0.5.0 (2024-10-15): 完成学习图谱和章节结构
在最终确定 README 之前:
质量检查清单:
在仓库根目录生成最终的 README.md 文件,所有部分按顺序排列:
格式化最佳实践:
# 而不是下划线)该技能包括用于自动指标收集的 Python 脚本:
scripts/collect-site-metrics.py
扫描仓库并生成指标报告,包括:
用法:
cd skills/readme-generator/scripts
python collect-site-metrics.py /path/to/repo
输出:包含所有指标的 JSON 对象
scripts/validate-readme.py
验证 README.md 的:
用法:
python validate-readme.py README.md
必需:
README.md - 仓库根目录中的完整 README可选:
README-backup.md - 先前 README 的备份(如果更新)docs/readme-metrics.json - JSON 格式的指标数据用户: “为此仓库生成一个 README”
Claude(使用此技能):
mkdocs.yml 以提取站点信息/docs 以获取指标(章节、MicroSims、术语表)collect-site-metrics.py 以收集统计信息高质量的 README 应具备:
每周安装次数
83
仓库
GitHub 星标数
54
首次出现
Jan 23, 2026
安全审计
安装于
gemini-cli80
codex80
opencode80
cursor78
github-copilot76
claude-code73
Generate or update a comprehensive README.md file for GitHub repositories following best practices.
This skill automates the creation of professional, well-structured README.md files for GitHub repositories. It generates all essential sections including badges for technologies used, project overview, site metrics, getting started instructions, project structure, and contact information. The skill is particularly optimized for MkDocs-based intelligent textbook projects but can be adapted for any repository type.
Use this skill when:
Before generating the README, gather information about the repository:
.git/config or the working directorymkdocs.yml if it exists to extract:
/docs directoryUser Dialog Triggers:
Create badges for all relevant technologies and platforms. Use shields.io format for consistency.
Badge Order:
Badge Templates:
[](https://www.mkdocs.org/)
[](https://squidfunk.github.io/mkdocs-material/)
[](SITE_URL)
[](REPO_URL)
[](https://claude.ai/code)
[](https://github.com/dmccreary/claude-skills)
Check for these additional badges:
[](https://p5js.org/)[](https://www.python.org/)[](https://developer.mozilla.org/en-US/docs/Web/JavaScript)Look for license information in:
LICENSE file in rootdocs/license.mdmkdocs.yml (copyright field)Default to Creative Commons BY-NC-SA 4.0 if not specified:
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
Other common licenses:
[](https://opensource.org/licenses/MIT)[](https://opensource.org/licenses/Apache-2.0)[](https://www.gnu.org/licenses/gpl-3.0)After badges, add a prominent link to the live website (if deployed):
## View the Live Site
Visit the interactive textbook at: [https://username.github.io/repo-name](https://username.github.io/repo-name)
Create a compelling 1-3 paragraph overview that answers:
Guidelines:
Example for Intelligent Textbook:
## 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.
Gather and display project metrics to show completeness and scope.
Run Python script to collect metrics:
Call scripts/collect-site-metrics.py (or create it if needed) to gather:
Learning Graph Metrics (from docs/learning-graph/):
Content Metrics :
docs/chapters/).md files in docs/)Interactive Elements :
docs/sims/)quiz.md)Format as a table:
## 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)
Book-Specific Metrics:
For specialized textbooks, add domain-specific metrics:
Provide clear instructions for using and customizing the project.
Standard sections:
Example:
## Getting Started
### Clone the Repository
```bash
git clone https://github.com/username/repo-name.git
cd repo-name
This project uses MkDocs with the Material theme:
pip install mkdocs
pip install mkdocs-material
Build the site:
mkdocs build
Serve locally for development (with live reload):
mkdocs serve
Open your browser to http://localhost:8000
mkdocs gh-deploy
This will build the site and push it to the gh-pages branch.
Navigation:
Interactive MicroSims:
Customization:
Edit markdown files in docs/ to modify content
Modify mkdocs.yml to change site structure
Add your own MicroSims in docs/sims/
Customize theme in docs/css/extra.css
Create an ASCII tree diagram showing the repository structure with explanatory comments.
Use this approach:
Example:
## Repository Structure
repo-name/ ├── docs/ # MkDocs documentation source │ ├── chapters/ # Chapter content │ │ ├── 01-intro/ │ │ │ ├── index.md # Chapter markdown │ │ │ └── quiz.md # Chapter quiz │ │ └── 02-concepts/ │ ├── sims/ # Interactive p5.js MicroSims │ │ ├── graph-viewer/ │ │ │ ├── main.html # Standalone simulation │ │ │ └── index.md # Documentation │ ├── learning-graph/ # Learning graph data and analysis │ │ ├── learning-graph.csv # Concept dependencies │ │ ├── learning-graph.json # vis-network format │ │ └── quality-metrics.md # Quality analysis │ ├── glossary.md # ISO 11179-compliant definitions │ ├── faq.md # Frequently asked questions │ └── references.md # Curated references ├── skills/ # Claude AI skills (if present) │ └── [skill-name]/ │ ├── SKILL.md # Skill definition │ └── *.py # Supporting scripts ├── mkdocs.yml # MkDocs configuration └── README.md # This file
Direct users to the GitHub Issues page:
## 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)
Reinforce licensing terms and attribution requirements:
## 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.
Express gratitude to the open source community and key projects:
## 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.
Customize based on actual dependencies:
Provide a way for users to reach out:
## 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.
Customize with actual maintainer information:
Include these sections if relevant to the project:
Contributing Guidelines:
## 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.
Citation Information:
## 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
Before finalizing the README:
Quality checklist:
Generate the final README.md file in the repository root with all sections in order:
Formatting best practices:
# not underlines)The skill includes Python scripts for automated metrics collection:
scripts/collect-site-metrics.py
Scans the repository and generates a metrics report including:
Usage:
cd skills/readme-generator/scripts
python collect-site-metrics.py /path/to/repo
Output: JSON object with all metrics
scripts/validate-readme.py
Validates README.md for:
Usage:
python validate-readme.py README.md
Required:
README.md - Complete README in repository rootOptional:
README-backup.md - Backup of previous README (if updating)docs/readme-metrics.json - Metrics data in JSON formatUser: "Generate a README for this repository"
Claude (using this skill):
mkdocs.yml to extract site info/docs for metrics (chapters, MicroSims, glossary)collect-site-metrics.py to gather statisticsA high-quality README should have:
Weekly Installs
83
Repository
GitHub Stars
54
First Seen
Jan 23, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli80
codex80
opencode80
cursor78
github-copilot76
claude-code73
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
159,700 周安装
生物序列检索工具 - DNA/RNA/蛋白质序列跨数据库智能检索与消歧义
1,300 周安装
Shadertoy 着色器开发指南:GLSL 片段着色器、WebGL 图形编程与实时渲染教程
1,300 周安装
Context7 文档查询技能 - 实时获取最新代码文档和API参考,告别过时训练数据
1,300 周安装
Cosmos 漏洞扫描器 - 9种关键漏洞模式,审计Cosmos SDK与CosmWasm智能合约安全
1,400 周安装
AddressSanitizer (ASan) 内存错误检测工具:模糊测试与C/C++调试指南
1,400 周安装
C++专家技能:现代C++20/23开发、高性能计算、零开销抽象编程指南
1,400 周安装
Educational Resources :
docs/glossary.md)docs/faq.md)docs/references.md)Media Assets :
.png, .jpg, .svg files)