القائمة
Creates or updates the GitHub README for a textbook project with badges, project overview, site metrics, and getting-started instructions.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Generates illustrated graphic novel narratives about scientists, mathematicians, and historical figures for intelligent textbooks, with image prompts for each panel. Use when adding historical-figure or case-study stories to a textbook's Stories section.
Installs and configures intelligent-textbook infrastructure - scaffold a brand-new MkDocs Material textbook (init textbook), install any of 40 features (math, mascot, learning graph viewer, Google Analytics GA4, custom 404, kanban board), and generate book metrics. Routes to the appropriate installation guide.
Creates interactive educational MicroSims, routing to the best-matched generator - p5.js, Chart.js, Plotly, Mermaid, vis-network, timelines, maps, Venn, causal-loop/feedback-loop diagrams (CLD), concept-classifier sorting quizzes, infographic overlays with callout labels, and Docker Python labs (runnable code blocks). Generates complete MicroSim packages with HTML, JavaScript, CSS, documentation, and metadata.
Generates a comprehensive learning graph from a course description, including 200 concepts with dependencies, taxonomy categorization, and quality validation reports. Use this when the user wants to create a structured knowledge graph for educational content.
Wires Google Analytics 4 into an MkDocs Material site — creates a GA4 property, writes the Measurement ID into mkdocs.yml, verifies the tag, and deploys. Use when adding analytics to a textbook for the first time.
Generates detailed chapter content for an intelligent textbook — text, diagrams, MicroSims, and exercises at the appropriate Bloom's level. Use when a chapter's index.md exists with title, summary, and concept list.
| name | readme-generator |
| description | Creates or updates the GitHub README for a textbook project with badges, project overview, site metrics, and getting-started instructions. |
| license | Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) |
| model | sonnet |
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:
Do NOT include a "GitHub repo" badge that links the README back to its own repository. Anyone reading the README is already on GitHub (or already has the repo cloned), so a self-link adds no value. The GitHub Pages badge is fine because it points to a different surface (the published site).
Badge Templates:
[](https://www.mkdocs.org/)
[](https://squidfunk.github.io/mkdocs-material/)
[](SITE_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.
Read the canonical metrics file — do NOT re-derive counts.
Book-wide totals are the single source of truth in
docs/learning-graph/book-metrics.json (produced by the book-metrics tool and
validated against src/book-metrics/book-metrics.schema.json). README metrics
MUST come from this file so the README, LinkedIn announcement, and case-study
card all show identical numbers.
# 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
The metrics object provides: concepts, chapters, microsims, stories,
glossaryTerms, faqs, quizQuestions, chapterQuizzes, chapterReferences,
references, diagrams, equations, words, links, appendices,
mascotImages, developmentStage, and equivalentPages. For identity
fields (title, author, repo URL, license) read book-metadata.json /
mkdocs.yml.
Only fall back to scripts/collect-site-metrics.py (markdown/image scanning)
for counts the metrics file does not provide — e.g. image-asset counts or
code-block counts. Never recount concepts/chapters/words by hand.
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:
docs/ to modify contentmkdocs.yml to change site structuredocs/sims/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 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: