Confirm successful installation by checking the skill directory location:
.cursor/skills/readme-generator
Restart Cursor to activate readme-generator. Access via /readme-generator in your agent's command palette.
β
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
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:
Check if README.md already exists in the root directory
Identify the repository name from .git/config or the working directory
Read mkdocs.yml if it exists to extract:
Site name
Site description
Site URL (for GitHub Pages link)
Repository URL
Check for documentation in /docs directory
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?"
Default to Creative Commons BY-NC-SA 4.0 if not specified:
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
After badges, add a prominent link to the live website (if deployed):
## View the Live SiteVisit 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:
## OverviewThis 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.
Run Python script to collect metrics:
Call scripts/collect-site-metrics.py (or create it if needed) to gather:
Number of chapters (count directories in docs/chapters/)
Number of markdown files (.md files in docs/)
Total word count (sum of all markdown files)
Number of code blocks
Number of lists and tables
Interactive Elements:
Number of MicroSims (directories in docs/sims/)
Number of quizzes (files named quiz.md)
Total quiz questions (count in quiz files)
Educational Resources:
Number of glossary terms (in docs/glossary.md)
Number of FAQ questions (in docs/faq.md)
Number of references (in docs/references.md)
Media Assets:
Number of images (.png, .jpg, .svg files)
Number of diagrams (Mermaid, vis-network)
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:
Circuits textbook: Number of circuit diagrams, simulations
History textbook: Number of timelines, maps, primary source documents
Programming textbook: Number of code examples, exercises, projects
Math textbook: Number of equations, proofs, worked examples
Step 7: Add Getting Started Section
Provide clear instructions for using and customizing the project.
Standard sections:
Prerequisites (if any)
Clone the Repository
Installation (if dependencies needed)
Building the Site
Local Development
Deployment
Example:
## Getting Started### Clone the Repository```bash
git clone https://github.com/username/repo-name.git
cd repo-name
Install Dependencies
This project uses MkDocs with the Material theme:
pip install mkdocs
pip install mkdocs-material
Build and Serve Locally
Build the site:
mkdocs build
Serve locally for development (with live reload):
mkdocs serve
Open your browser to http://localhost:8000
Deploy to GitHub Pages
mkdocs gh-deploy
This will build the site and push it to the gh-pages branch.
Using the Book
Navigation:
Use the left sidebar to browse chapters
Click on the search icon to search all content
Each chapter includes quizzes and practice exercises
Interactive MicroSims:
Found in the "MicroSims" section
Each simulation runs standalone in your browser
Adjust parameters with sliders and controls
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
### 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
## Reporting IssuesFound 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)
Step 10: Add License Information
Reinforce licensing terms and attribution requirements:
## LicenseThis 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 [
β
Make data-driven prioritization decisions faster
Stakeholder Communication
Draft PRDs, status updates, and stakeholder presentations
βΊAccess to product documentation and roadmap tools (Jira, Notion, etc.)
βΊUnderstanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
βΊStakeholder contact information and communication channels
Time Estimate
30-60 minutes to see productivity improvements
Steps
1Install product management skill
2Start with user story generation for known feature
3Progress to competitive analysis: research 2-3 competitors
4Use for roadmap prioritization: apply RICE/ICE scoring
5Draft stakeholder communications and refine based on feedback
6Build template library for recurring PM tasks
7Share effective prompts with product team
Common Pitfalls
β Not validating competitive researchβverify facts before sharing
β Accepting user stories without involving engineering team
β Over-relying on frameworks without qualitative judgment
β Not customizing outputs to company culture and communication style
β Skipping stakeholder validation of generated requirements
Best Practices
β Do
+Validate research and competitive analysis with real data
+Collaborate with engineering when generating technical requirements
+Customize frameworks and templates to your company context
+Use skill for first drafts, refine with stakeholder input
+Document successful prompt patterns for PM tasks
+Combine AI efficiency with human judgment and intuition
β Don't
βDon't publish competitive analysis without fact-checking
βDon't finalize user stories without engineering review
βDon't make prioritization decisions solely on AI scoring
βDon't skip customer validation of generated requirements
βDon't ignore company-specific context and culture
π‘ Pro Tips
β Provide context: company goals, constraints, customer feedback
β Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
β Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
β Use skill for 70% generation + 30% customization to company needs
When to Use This
β Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
β Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path
1Basic: user stories, feature specs, status updates