Skip to content
Back to search

github-profile-readme-generator

Builds an animated GitHub profile README from your real GitHub data, after a few design questions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/walthermorarivera--github-profile-readme-generator/badge.svg)](/listings/walthermorarivera--github-profile-readme-generator)

HTML

<a href="/listings/walthermorarivera--github-profile-readme-generator"><img src="/api/listings/walthermorarivera--github-profile-readme-generator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

/plugin marketplace add WaltherMoraRivera/github-profile-readme-generator
/plugin install github-profile@github-profile-readme-generator

Then just say **"set up my GitHub profile"**. The agent:

1. Checks `gh`, Python and git, and reads your public GitHub data. 2. Asks for a theme (13, including Linux distro variants) and a setup mode, like an installer: - **Quick**: one more question (do you have an image or GIF for the header?). The agent picks your projects, stats and texts from your GitHub data and shows you a preview. - **Custom**: you choose the language, featured projects, stats, header and every text. 3. Turns your GIF or image into a header that works in both themes. 4. Builds a local preview. You approve it, change something, or switch from quick to custom. 5. Backs up your current profile, then publishes only what you approve.

Backups

Before every publish, the agent saves your profile as it is on GitHub to a `backup/<date>` branch of your profile repository (README, images and data). Ask **"show my profile backups"** or **"restore my profile from November 15"**: it lists them with date and theme and brings the one you pick back as a new commit, after backing up the current one, so nothing is lost. Without Claude, inside your profile repository:

python3 path/to/scripts/backup.py create          # save the current profile
python3 path/to/scripts/backup.py list            # see backups
python3 path/to/scripts/backup.py restore 2026-11-15-1030 && git push

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "github-profile-readme-generator",
  4. "description": "Builds an animated GitHub profile README from your real GitHub data, after a few design questions.",
  5. "owner": {
  6. "name": "Walther Mora Rivera"
  7. },
  8. "plugins": [
  9. {
  10. "name": "github-profile",
  11. "source": "./plugin",
  12. "description": "Design, preview and publish a GitHub profile README: SVG cards with live stats, 13 themes inspired by developer tools, editors, browsers, databases, git, operating systems and retro screens, light and dark modes, an optional animated header from your own image or GIF, quick or custom setup, and restorable backups."
  13. }
  14. ]
  15. }
README.md · README · 194 lines
  1. > [!CAUTION]
  2. > **This project moved to [ProfileStudio/ProfileStudio](https://github.com/ProfileStudio/ProfileStudio).**
  3. > This repository is archived and no longer updated. To switch the Claude Code plugin:
  4. >
  5. > ```text
  6. > /plugin marketplace add ProfileStudio/ProfileStudio
  7. > /plugin install profilestudio@profilestudio
  8. > ```
  9. # GitHub Profile README Generator
  10. **English** · [Español](README.es.md)
  11. Generate a polished GitHub profile README from your real GitHub data: SVG cards with live stats,
  12. 13 themes inspired by the tools developers use every day, light and dark modes, and an optional **animated header** made from your own image or GIF. A
  13. Claude Code agent asks you a few design questions, builds a preview and publishes it when you
  14. approve. No Claude? The generator is a single Python script with no dependencies.
  15. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  16. ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776ab.svg)
  17. ![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-d97757.svg)
  18. ## Live example
  19. <a href="https://github.com/WaltherMoraRivera"><img src="https://raw.githubusercontent.com/WaltherMoraRivera/WaltherMoraRivera/main/assets/header.svg" width="100%" alt="Header of github.com/WaltherMoraRivera: terminal theme, cyan accent, animated pixel-art portrait"></a>
  20. [github.com/WaltherMoraRivera](https://github.com/WaltherMoraRivera): terminal theme, Spanish, animated pixel-art portrait.
  21. ## 13 themes, inspired by the tools you use every day
  22. | Theme | Dark | Light |
  23. |---|---|---|
  24. | **terminal** · shell prompts, one accent, Linux distro variants | <img src="plugin/skills/github-profile/reference/styles/terminal-dark.jpg" alt="Terminal theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/terminal-light.jpg" alt="Terminal theme, light"> |
  25. | **editor** · tabs, line numbers, your data written as code | <img src="plugin/skills/github-profile/reference/styles/editor-dark.jpg" alt="Editor theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/editor-light.jpg" alt="Editor theme, light"> |
  26. | **classic** · 90s desktop windows and block progress bars | <img src="plugin/skills/github-profile/reference/styles/classic-dark.jpg" alt="Classic theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/classic-light.jpg" alt="Classic theme, light"> |
  27. | **win11** · flat rounded windows, caption buttons | <img src="plugin/skills/github-profile/reference/styles/win11-dark.jpg" alt="Windows 11 theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/win11-light.jpg" alt="Windows 11 theme, light"> |
  28. | **macos** · traffic lights, unified title bar | <img src="plugin/skills/github-profile/reference/styles/macos-dark.jpg" alt="macOS theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/macos-light.jpg" alt="macOS theme, light"> |
  29. | **ide** · tool window strip, run toolbar, Kotlin-style code | <img src="plugin/skills/github-profile/reference/styles/ide-dark.jpg" alt="IDE theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/ide-light.jpg" alt="IDE theme, light"> |
  30. | **vim** · mode in the status line, relative line numbers, markdown buffer | <img src="plugin/skills/github-profile/reference/styles/vim-dark.jpg" alt="Vim theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/vim-light.jpg" alt="Vim theme, light"> |
  31. | **notebook** · numbered cells, code input and its output | <img src="plugin/skills/github-profile/reference/styles/notebook-dark.jpg" alt="notebook theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/notebook-light.jpg" alt="notebook theme, light"> |
  32. | **handheld** · 90s handheld console screen: four greens, portrait recolored | <img src="plugin/skills/github-profile/reference/styles/handheld-dark.jpg" alt="handheld theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/handheld-light.jpg" alt="handheld theme, light"> |
  33. | **crt** · phosphor screen with scan lines and glow, amber or green | <img src="plugin/skills/github-profile/reference/styles/crt-dark.jpg" alt="CRT theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/crt-light.jpg" alt="CRT theme, light"> |
  34. | **browser** · address bar, headings highlighted like the element inspector | <img src="plugin/skills/github-profile/reference/styles/browser-dark.jpg" alt="Browser theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/browser-light.jpg" alt="Browser theme, light"> |
  35. | **sql** · database console: headings as queries, cards as their results | <img src="plugin/skills/github-profile/reference/styles/sql-dark.jpg" alt="SQL theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/sql-light.jpg" alt="SQL theme, light"> |
  36. | **git** · commit graph in the gutter, headings as commits with hash and refs | <img src="plugin/skills/github-profile/reference/styles/git-dark.jpg" alt="Git theme, dark"> | <img src="plugin/skills/github-profile/reference/styles/git-light.jpg" alt="Git theme, light"> |
  37. Every card follows the viewer's GitHub theme on its own. The terminal theme also comes in Linux
  38. distribution variants (`ubuntu`, `arch`, `debian`, `fedora`, `mint`, `cachyos`): their color, and
  39. `you@archlinux: ~` in the title bar; `crt` takes `amber` or `green` phosphor. `classic` and `handheld`
  40. keep a fixed palette. Themes are inspired by these systems and use no logos.
  41. ## What you get
  42. - **Header**: name, role, bio and tags, plus an animated GIF, a still image, a neofetch-style
  43. panel or nothing on the right.
  44. - **Profile signal**: four live stats of your choice (repos, contributions, pull requests, stars,
  45. followers, projects in production).
  46. - **Selected work**: four project cards with description, stack, status, commit count, last push
  47. and language split.
  48. - **Language stack** by bytes of code, and your **toolkit** grouped by area.
  49. - **Contribution heatmap** for the last 52 weeks, with active weeks and longest streak.
  50. - English or Spanish, `README.md` generated from one `profile.json`, and an optional weekly
  51. refresh workflow.
  52. ## Quick start with Claude Code
  53. ```text
  54. /plugin marketplace add WaltherMoraRivera/github-profile-readme-generator
  55. /plugin install github-profile@github-profile-readme-generator
  56. ```
  57. Then just say **"set up my GitHub profile"**. The agent:
  58. 1. Checks `gh`, Python and git, and reads your public GitHub data.
  59. 2. Asks for a theme (13, including Linux distro variants) and a setup mode, like an installer:
  60. - **Quick**: one more question (do you have an image or GIF for the header?). The agent picks
  61. your projects, stats and texts from your GitHub data and shows you a preview.
  62. - **Custom**: you choose the language, featured projects, stats, header and every text.
  63. 3. Turns your GIF or image into a header that works in both themes.
  64. 4. Builds a local preview. You approve it, change something, or switch from quick to custom.
  65. 5. Backs up your current profile, then publishes only what you approve.
  66. ### Backups
  67. Before every publish, the agent saves your profile as it is on GitHub to a `backup/<date>` branch
  68. of your profile repository (README, images and data). Ask **"show my profile backups"** or
  69. **"restore my profile from November 15"**: it lists them with date and theme and brings the one you
  70. pick back as a new commit, after backing up the current one, so nothing is lost. Without Claude,
  71. inside your profile repository:
  72. ```bash
  73. python3 path/to/scripts/backup.py create # save the current profile
  74. python3 path/to/scripts/backup.py list # see backups
  75. python3 path/to/scripts/backup.py restore 2026-11-15-1030 && git push
  76. ```
  77. ## Quick start without Claude
  78. You need Python 3.9+ and the [GitHub CLI](https://cli.github.com) signed in (`gh auth login`).
  79. ```bash
  80. git clone https://github.com/WaltherMoraRivera/github-profile-readme-generator
  81. gh repo create <you>/<you> --public --clone # or clone it if it already exists
  82. cd <you>
  83. mkdir -p scripts data
  84. cp ../github-profile-readme-generator/plugin/skills/github-profile/scripts/generate.py scripts/
  85. cp ../github-profile-readme-generator/plugin/skills/github-profile/templates/profile.example.json data/profile.json
  86. cp ../github-profile-readme-generator/plugin/skills/github-profile/templates/gitignore .gitignore
  87. # edit data/profile.json, then:
  88. python3 scripts/generate.py
  89. ```
  90. Open `preview.html` to check it. If you already had a profile, save it first with
  91. `python3 ../github-profile-readme-generator/plugin/skills/github-profile/scripts/backup.py create`,
  92. then commit and push `README.md assets data scripts .gitignore`.
  93. A public repository named exactly like your account is shown on your profile page.
  94. Every option is documented in
  95. [`configuration.md`](plugin/skills/github-profile/reference/configuration.md).
  96. ### Animated header from a GIF
  97. Needs Pillow (`python3 -m pip install --user pillow`).
  98. ```bash
  99. python3 plugin/skills/github-profile/scripts/frames.py my.gif data/portrait-sheet.png --bg white --native auto --height 450
  100. ```
  101. - `--bg`: your GIF's solid background (`white`, `black`), or `none` if it is already transparent.
  102. - `--native auto`: detects upscaled pixel art and keeps it sharp. A 21-frame portrait came out at
  103. under 100 KB.
  104. - `--fade-sides 0.12 --colors 0`: softens a figure cut by the left and right edges.
  105. Then set in `profile.json`: `"portrait": "data/portrait-sheet.png"`,
  106. `"portrait_frames": "data/portrait-sheet.json"`, `"portrait_width": 250`.
  107. For a still image on a solid dark background, `scripts/cutout.py` removes the background.
  108. ## Your own colors
  109. Change colors in `data/profile.json`, without touching the script, so you keep getting updates:
  110. - **Your own accent**: `"accent": {"light": "#4b5563", "dark": "#d4d8de"}` (or a single `"#ff6600"`).
  111. - **Fine-tune a theme**: `theme_overrides` sets background, title bar, panels, text, the colors of
  112. numbers, language colors and extra CSS, per mode. `"color_scheme": "dark"` keeps it dark for
  113. everyone.
  114. The generator warns when a color is hard to read. All keys:
  115. [`configuration.md`](plugin/skills/github-profile/reference/configuration.md#custom-colors).
  116. ## How it works
  117. - `generate.py` calls the GitHub REST and GraphQL APIs through your `gh` login and writes plain SVG
  118. files. Nothing is hosted elsewhere, so nothing can go down.
  119. - GitHub shows README images as `<img>`. Inside an SVG, CSS still works there, so each card carries
  120. `prefers-color-scheme` colors for both themes, and the header animation is a CSS sprite sheet
  121. that steps one frame at a time. It stops for viewers who prefer reduced motion.
  122. - Text in SVG does not wrap, so the generator wraps it by estimated width, on the safe side.
  123. ## Good to know
  124. - **Pinned repositories** can only be set by you on your profile ("Customize your pins"); GitHub has
  125. no API for it.
  126. - **Private work** shows in the heatmap only if you enable "Include private contributions on my
  127. profile" in your settings.
  128. - **Weekly refresh**: `templates/update-profile.yml` runs only when the repo has a `PROFILE_TOKEN`
  129. secret, a read-only token you create. The default Actions token sees public activity only and
  130. would lower your numbers. Without it, refresh by running the generator and pushing.
  131. - **Images look old after a push?** Each image path carries a hash of the file (`?v=…`), so new
  132. cards show at once; if one does not, reload with Ctrl+F5.
  133. - **"Made with" badge**: a small badge at the bottom right, in your theme's colors, links back to
  134. this generator. Remove it with `"made_with": false` in `profile.json`.
  135. - **Art by someone else** needs a visible credit (`credits` in `profile.json`).
  136. Known pitfalls and how they were solved:
  137. [`lessons.md`](plugin/skills/github-profile/reference/lessons.md).
  138. ## Repository layout
  139. ```
  140. .claude-plugin/marketplace.json Claude Code marketplace
  141. plugin/.claude-plugin/plugin.json plugin manifest
  142. plugin/skills/github-profile/
  143. ├── SKILL.md the agent's workflow and configuration questions
  144. ├── scripts/generate.py generator (standard library only)
  145. ├── scripts/frames.py GIF → animated sprite sheet (Pillow)
  146. ├── scripts/cutout.py removes a dark background (Pillow + numpy)
  147. ├── templates/ profile.example.json, workflow, .gitignore
  148. └── reference/ configuration, lessons, style screenshots
  149. ```
  150. ## License
  151. [MIT](LICENSE) © 2026 Walther Mora Rivera. Built with Claude Code.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.