Skip to content

Create a README.md Generator Skill

use the skill-generator skill to create a new skill called readme-generator. This skill will create or update a README.md file in the github home directory of the current project. The README.md file it generates will confirm to GitHub best practices. Use the following steps:

STEP 1: Badges

Scan the GitHub repo for all the open source packages and put in badges at the top of the README.md for these packages. Also put in the appropriate badge for the software license. Use the following order:

  1. mkdocs badge
  2. mkdocs-material badge
  3. GitHub pages live badge
  4. Claude Code badge
  5. Claude Skills badge

Examples:

MkDocs Material for MkDocs GitHub Claude AI

STEP 2: License Badge

Look for a license file and put in the badge for the license. By default we always will use the Creative Commons Attribution Noncommercial ShareAlike License.

Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0 DEED)

License: CC BY-NC-SA 4.0

After all badges are done, always provide a link to the working Google Docs website.

STEP 4: Overview/Short Description

Provide a short description of the website in 1-2 paragraphs of text. Describe who would use the website and why it is wonderful.

STEP 5: Site Status and Metrics

Provide a brief overview of the status of the textbook in terms of the components that have been added and what remains to be done. Look in the docs/learning-graph for status and book metrics. You can also find tools in the src/site-analytics that you can run to update the site metrics.

Sample book metrics include:

  1. Number of Concepts in the Concept Graph
  2. Number of Chapters
  3. Number of Markdown Files
  4. Total Number of Words (in all markdown files)
  5. Number of MicroSims (look in docs/sims)
  6. Number of Glossary Terms
  7. Number of FAQ questions
  8. Number of Quizzes
  9. Total Number of Quiz Questions
  10. Number of Equations
  11. Number of Markdown Lists, Tables
  12. Number of References
  13. Number of Images (png, jpg)

Book Specific Metrics

For specific types of books, other metrics might be used. For example in a circuits textbook, the number of circuit diagrams might be important. A history book might have a count of the maps and timelines.

STEP 6: Getting Started

How to get started using the book or customizing the book.

Sample UNIX shell git clone command.

Sample UNIX shell commands to use mkdocs

  1. mkdocs build - transform markdown into HTML
  2. mkdocs serve - test on a local web server
  3. mkdocs gh-deploy - publish to github pages

Using the Book

  1. Navigation
  2. Table of Contents
  3. Search
  4. Search Results
  5. Interactive MicroSims
  6. Using a single iframe from the book
  7. Using an entire chapter
  8. Creating a custom version of the book for your classroom

STEP 7: Book Structure

An documented ASCII tree with comments as it would be generated by the UNIX tree command. Do not list ALL the files, just a sample struture.

STEP 8: Reporting Issues

Tell them to use the GitHub issues area:

https://github.com/dmccreary/REPO_NAME/issues

STEP 9: Review License

Remind them that we always seek attribution for our work.

STEP 10: Acknowledgements of Open Source Community

Put in our sincere appreciation for the open source community. Include the teams from:

  1. mkdocs build tool
  2. mkdocs-material theme
  3. NYU and the team that supports p5.js
  4. vis-network tools for visualizing graphs
  5. python community for extended tools to manage content

STEP 11: How To Contact Me

Please contact me on Please contact me on LinkedIn if you have questions.

STEP 12: Misc

Any miscellaneous information you think is relevent