Repository navigation
Releases
readme-forge v1.4.0
This release teaches the skill your style: it learns from what you keep, edit and delete, on your machine.
Added
scripts/learn.py: the skill learns each user's style. Every choice it makes (sections, length, heading emoji, banner style, palette, profile archetype, page theme) is an arm of a contextual bandit, with the mode, project kind and language as context. Rewards come from the user's edits:snapshotrecords what was generated, andobservescores what survived (a deleted section, a regenerated banner or a README cut by more than a quarter counts as a rejection).suggestranks options by posterior mean and picks the best one, using Thompson sampling only to choose among options tied for best, and keeps the skill's default until there is evidence. Older feedback decays, so tastes can change. Stated preferences (prefer "never use emoji in headings") are kept as rules. Data stays in~/.readme-forge(no README text, no network);show,off,onandresetcontrol it. A missing or moved README, a corrupted data file or snapshot, and a bad--repopath never teach it anything wrong. Both SKILL.md files run the loop, and 28 unit tests cover it.- Brand icons in
.github/assets/brand/: a README page with a check mark on a violet-to-cyan tile, as a vectoricon.svg, PNGs at 1024, 512, 400 and 240 px, and a multi-sizefavicon.ico. It stays readable down to 16 px. The README hero card shows the mark. - A form for the Show and tell discussion category, for sharing READMEs made with the skill.
gallery/gallery.jsonand the gallery website: every banner style, full README design, profile style, button and footer, and the before/after demo, with the command that makes each one. Anyone can add their README by pull request (gallery/README.md);tests/test_gallery.pychecks every entry.
Changed
- Releases are cut from tags like
v1.4.0only. A movingv1tag now follows the latest 1.x release, souses: tanmayai23/README-Editor-skill@v1in the README and the Action docs resolves; until now nov1tag existed. The release job moves it after publishing. check_links.pyhas a new status,UNVERIFIED, for hosts that block bots (npm, LinkedIn and others) and GitHub pages that need a login, such as/stargazers. It is reported but doesn't fail the run. Exit code 1 still meansBROKENorWIDGET-ERROR.
Fixed
- The readme-forge-design skill description was 1051 characters, over the 1024 that claude.ai accepts, so uploading
readme-forge-design.zipfailed. It is now 1009, andtests/test_skills.pychecks the name and description limits of both skills. - Files with a UTF-8 BOM or in UTF-16, common on Windows, are read correctly by
analyze_repo.pyandscore_readme.py. Before, apackage.jsonorpyproject.tomlwith a BOM lost every fact, and a README with a BOM scored 8/100 with "no title" (#24). analyze_repo.pyskips files that.gitignoreexcludes, so generated or vendored code no longer decides the primary language or adds env vars (#26).score_readme.pybuilds heading anchors the way GitHub does: backticks and link syntax are removed, and duplicate headings get-1,-2(#27). It also stops reporting working relative links as missing: URL-encoded paths, paths from the repo root (/docs/...) and example links inside code blocks (#28).check_links.pychecks reference-style links ([id]: url), including badges, reads URLs with parentheses in full, and skips code (#29). It follows 307 and 308 redirects on every Python version (#30).- Animated banners now stop when the OS asks for reduced motion. The orbit, terminal, bold, spotlight and ribbon styles used SMIL, which CSS can't pause; they now use CSS animations (#32).
make_banner.pyaccepts--accentas#RGBor#RRGGBBand rejects anything else with a clear message instead of crashing. Chinese, Japanese and Korean titles and long subtitles shrink, wrap or end with an ellipsis to stay inside the banner (#33).analyze_repo.pyno longer crashes on a symlink to missing model weights, and it reads env vars in files such aslatest.pywhose names contain "test" (#34).
readme-forge v1.3.0
Added
- Page kit in readme-forge-design (
scripts/make_page.py): designs a whole README, not only the header and footer. One JSON spec becomes a set of matching SVG cards in light and dark plus the finished README. Blocks: terminal-window hero with a dripping edge, contact dock, numbered section headers, about card, tech-stack grid, project cards (feature / card / link), achievement cards (photo or emblem), themed stats widgets, Markdown passthrough and a mirrored footer. Six themes (keynote,aurora,sunset,ocean,forest,mono) or customaccents;ambient,entranceandstaticmotion, CSS only. Paired cards share a height, linked cards are written on one line so GitHub keeps dark mode and the link, and the script refuses specs with{{placeholders}}left. Mode K in SKILL.md,references/page-kit.md, starter specs intemplates/page/, and two examples (examples/keynote-profile/,examples/keynote-project/). assets/icons.json: 103 brand icons from Simple Icons (CC0) for the stack and dock cards, with aliases (aws,gcp,node,k8s…) and line icons for mail, website, résumé and more. Unknown names fall back to a monogram tile.- Page kit blocks learned from popular profile READMEs:
code(about-me as a YAML or JSON editor card with syntax colours),portrait(dot-matrix halftone drawn from a PNG by a stdlib PNG decoder; only the dots are stored),certs(badge and certification wall), heroroles(rotating role line that replaces readme-typing-svg and shows the first role in frame 0), projectlinks(cards in a table with a Live · Code row under each), andstatsoptions for top languages, LeetCode, Codeforces, the 3D contribution calendar and a view counter. 14 more brand icons (117), including Codeforces, HackerRank, CodeChef, GeeksforGeeks, Java (OpenJDK), HTML and CSS. New fictional exampleexamples/keynote-coder/. references/page-kit.md: "Learning from a sample README", a table that maps common profile patterns (capsule-render headers, typing banners, YAML about-me, badge walls, project tables, coding-profile cards) to page-kit blocks and lists the widgets whose hosts are dead.
Changed
- README: the install command now sits on the first screen; a Limitations section collects what the claim check, score, diagrams and analyzer can't do (moved out of the FAQ); a Support section and
.github/FUNDING.ymladd a Buy Me a Coffee link and GitHub's Sponsor button. - The page kit's stats card no longer sets
include_all_commits: the public github-readme-stats instance answers "Could not fetch total commits" for many users. Turn it back on with"all_commits": truewhen self-hosting.widgets.mdnotes this, adds the Codeforces card and marks the MonkeyType card as dead (HTTP 404). - The project README is built from page-kit cards (
.github/page.json): a hero with a dripping edge, three ways-to-use-it cards, a claim-check feature card with four feature cards, a validated-score card and a mirrored footer. Headings, commands and data stay as real Markdown, so anchors and the claim check still work. score_readme.py --profilecounts page-kit section cards (alt text like02 — Tech stack) as section headings, so a card-built profile is scored on its content instead of losing points for missing Markdown headings.
Fixed
- The demo GIF and video ended on
/plugin install readme-forge, which fails on its own. The end card now shows the repository address,github.com/tanmayai23/README-Editor-skill, where the README has the working install command.
readme-forge v1.2.0
This release makes accuracy the headline: every README the skill writes is checked claim by claim against the code, and the design features move to an optional plugin.
Added
-
scripts/verify_readme.py: extracts every command, script, flag, env var and path from a README and checks each one against the repository. Reports verified / not found / unverifiable and an accuracy percentage;--min-accuracygates CI. The skill now requires zero "not found" claims before it finishes. -
GitHub Action (
uses: tanmayai23/README-Editor-skill@v1): scores and fact-checks READMEs on pull requests, upserts one PR comment, writes the job summary, and can fail belowmin-score/min-accuracy. Forked PRs degrade to a warning (#1). -
Unit tests (
python -m unittest discover -s tests) with fixtures for all 15 ecosystemsanalyze_repo.pydetects, forimport_graph.pyin Python, JS/TS, Go and Rust, for the verifier and for the Action. -
Swift (SwiftPM), Zig and Haskell (Stack, Cabal) detection; Deno tasks and
Deno.env.get;mix phx.serverfor Phoenix. -
Shader banner styles in readme-forge-design, rebuilt in SVG from the look of no-code WebGL shader scenes:
vortex(spinning blades, liquified contour swirl, condensed serif caps; logo sits in the eye),beam(light racing around the edge over a nebula),shatter(voronoi glass with glowing cracks),prism(RGB-split blinds with a swipe reveal).vortexfooter,beamdivider, andinfernoandprismpalettes. All four animate with CSS only, so reduced motion stops them. -
make_banner.py --style pulse: soft concentric rings breathing behind the title, with dark and light variants (#15, thanks @Sultanast01). -
make_banner.py --href URLfor headers and footers: prints the banner already wrapped in a link, in the form GitHub renders correctly. -
8 profile archetypes covering every category of the awesome-github-profile gallery:
game-mode,typing,anime-art,fancy-fonts,descriptive,simple-innovative,iconsandjust-image.profile-readme.mdmaps each of the gallery's 16 categories to a template. -
Community tic-tac-toe for profiles (
workflows/tictactoe.yml+game/tictactoe.py): visitors click a square, which opens an issue, and an Action plays the move, redraws the board, keeps a scoreboard and closes the issue. Issue titles are validated and passed throughenv, never into the shell. -
scripts/fancy_text.py: converts text to Unicode bold, italic, sans, mono and double-struck styles, including the letters outside the math block (ℎ, ℂ, ℝ…). -
score_readme.pywarns when styled Unicode text runs past headings and a tagline, since screen readers spell it letter by letter. -
Spotify now-playing widget (kittinan/spotify-github-profile) in
widgets.md. -
score_readme.pyreports a<picture>that GitHub empties, either opened after<a href>on the same line or glued to the paragraph line above it.
Changed
- Split into two plugins.
readme-forgekeeps facts, verification, scoring, Hugging Face cards and companion docs. Banners, CTA buttons, design templates, profile READMEs, widgets andfancy_text.pymove to the optionalreadme-forge-designplugin (claude plugin install readme-forge-design --marketplace tanmayai23/README-Editor-skill). Releases shipreadme-forge.zipandreadme-forge-design.zip. - The project README leads with the claim check, drops the banner gallery (now in readme-forge-design), the badge wall and the star-history chart, passes
verify_readme.pyat 100%, and uses the new vortex header. pulsebanners animate with CSS instead of SMIL, so reduced motion stops them.- The release job fails when the tag doesn't match the plugin version or the CHANGELOG has no section for it (#19).
Fixed
score_readme.pycounted<img>written inside inline code or code blocks as a real image and reported missing alt text.analyze_repo.py: Java'ssrc/main/java/com/example/was treated as a sample folder, hiding its env vars; Go modules with onlycmd/<x>got ango installpath that fails; justfile assignments were listed as recipes and recipes with default parameters were missed.import_graph.py: tsconfig path aliases were lost when the file had a//comment;from . import xlinked to__init__.pyinstead of the submodule;go.modin a subfolder wasn't found; Rustmod x;insidenet/mod.rsand nesteduse crate::paths resolved to the wrong file (#25, #31).- Linked banners and CTA buttons showed the light variant in dark mode and opened the SVG file instead of the link.
make_banner.py --kind buttonprinted<a href><picture>on one line with the<source>on the next, and GitHub drops the<source>from that form. The snippet now puts<a>,<picture>and</a>on separate lines. hero-landing.md,header-profile.mdandheader-centered.mdtemplates: blank line after<a id="top"></a>, so the header<picture>no longer gets emptied.