readme-generator_skill

Overview

This skill creates or updates a README.md in the project root that follows GitHub best practices. It assembles badges, a concise project overview, site metrics, getting-started instructions, repository structure, license and contact information. The output is optimized for MkDocs-based intelligent textbook projects but adapts to any repository. It prompts the user only when repository metadata or deployment URLs are missing.

How this skill works

The skill inspects the repository root for existing README.md, mkdocs.yml, LICENSE, docs/, requirements.txt, and common package files to detect technologies and metadata. It generates appropriate shields.io badges, extracts or computes site metrics (chapters, markdown files, word counts, quizzes, images) by scanning docs/, and builds standard sections: overview, metrics, getting started, structure, issues, license, acknowledgements, and contact. When needed it asks for missing repo or site URLs and optionally backs up an existing README.md before updating.

When to use it

• Creating the initial README for a new repository
• Updating an outdated or minimal README to match best practices
• Documenting a MkDocs textbook or interactive site before publishing
• After adding new technologies, dependencies, or major content changes
• Preparing the repo for public release or sharing with collaborators

Best practices

• Keep the overview short and answer what, who, and why in active voice
• Include clear badges (tech, license, live site) and a prominent live-site link if deployed
• Provide reproducible getting-started steps: clone, install, build, serve, and deploy
• Include site metrics and a concise repository tree to communicate scope and completeness
• Add issue reporting, license, acknowledgements, and a maintainer contact section for clarity

Example use cases

• Generate a README for a new MkDocs-based interactive textbook with MicroSims and quizzes
• Refresh README after a major content generation pass or restructuring of docs/
• Add deployment and live-site links when enabling GitHub Pages
• Create a license and contribution section when preparing the repo for open-source release
• Produce a metrics table for project dashboards or progress reports