readme-generator

What this skill does

# README Generator

Generate or update a comprehensive README.md file for GitHub repositories following best practices.

## Purpose

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.

## When to Use This Skill

Use this skill when:

- Starting a new GitHub repository that needs a README.md
- Updating an existing README.md to follow best practices
- After significant project changes that should be documented
- Before publishing or sharing a repository
- When migrating from another documentation system
- After adding new technologies or dependencies

## Workflow

### Step 1: Analyze Repository Context

Before generating the README, gather information about the repository:

1. Check if README.md already exists in the root directory
2. Identify the repository name from `.git/config` or the working directory
3. Read `mkdocs.yml` if it exists to extract:
   - Site name
   - Site description
   - Site URL (for GitHub Pages link)
   - Repository URL
4. Check for documentation in `/docs` directory
5. Identify technologies used (look for package.json, requirements.txt, mkdocs.yml, etc.)

**User Dialog Triggers:**

- If README.md exists: Ask "README.md already exists. Would you like to update it or create a backup first?"
- If repository URL not found: Ask "What is the GitHub repository URL? (e.g., https://github.com/username/repo-name)"
- If site URL not configured: Ask "Is this site deployed to GitHub Pages? If yes, what's the URL?"

### Step 2: Generate Badges

Create badges for all relevant technologies and platforms. Use shields.io format for consistency.

**Badge Order:**

1. MkDocs (if mkdocs.yml exists)
2. MkDocs Material (if theme is Material)
3. GitHub Pages live badge (if site is deployed)
4. Claude Code badge
5. Claude Skills badge (if .claude/skills or skills/ directory exists)
6. License badge
7. Additional technology badges (Python, JavaScript, p5.js, etc.)

**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:**

```markdown
[![MkDocs](https://img.shields.io/badge/Made%20with-MkDocs-526CFE?logo=materialformkdocs)](https://www.mkdocs.org/)
[![Material for MkDocs](https://img.shields.io/badge/Material%20for%20MkDocs-526CFE?logo=materialformkdocs)](https://squidfunk.github.io/mkdocs-material/)
[![GitHub Pages](https://img.shields.io/badge/View%20on-GitHub%20Pages-blue?logo=github)](SITE_URL)
[![Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-DA7857?logo=anthropic)](https://claude.ai/code)
[![Claude Skills](https://img.shields.io/badge/Uses-Claude%20Skills-DA7857?logo=anthropic)](https://github.com/dmccreary/claude-skills)
```

**Check for these additional badges:**

- p5.js: `[![p5.js](https://img.shields.io/badge/p5.js-ED225D?logo=p5.js&logoColor=white)](https://p5js.org/)`
- Python: `[![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)](https://www.python.org/)`
- JavaScript: `[![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?logo=javascript&logoColor=black)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)`

### Step 3: Add License Badge

Look for license information in:

1. `LICENSE` file in root
2. `docs/license.md`
3. `mkdocs.yml` (copyright field)

**Default to Creative Commons BY-NC-SA 4.0 if not specified:**

```markdown
[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
```

**Other common licenses:**

- MIT: `[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)`
- Apache 2.0: `[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)`
- GPL-3.0: `[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)`

### Step 4: Create Website Link Section

After badges, add a prominent link to the live website (if deployed):

```markdown
## View the Live Site

Visit the interactive textbook at: [https://username.github.io/repo-name](https://username.github.io/repo-name)
```

### Step 5: Write Overview/Short Description

Create a compelling 1-3 paragraph overview that answers:

- What is this project?
- Who is it for?
- Why is it valuable?
- What makes it unique or special?

**Guidelines:**

- Keep it concise but engaging
- Use active voice
- Highlight key features or benefits
- Mention the educational framework if applicable
- For textbooks: mention target audience (grade level, prerequisites)

**Example for Intelligent Textbook:**

```markdown
## 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: Add Site Status and Metrics

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.

```bash
# 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:**

```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 |
|