readme-forge-design

Make READMEs and GitHub profiles look designed, without external services: every asset is an SVG committed to the repo.

Skill directory: SKILL_DIR = the folder containing this file. Scripts are stdlib-only Python 3.8+.

Division of labour. This skill owns the look. The core readme-forge skill owns the facts: it writes project READMEs from the code and checks every command, env var and path with verify_readme.py. When you design a project README, run the core skill's fact-gathering and verification first, or keep the existing text untouched. Scoring (score_readme.py) and link checks (check_links.py) also come from the core skill; if it isn't installed, tell the user in one line and skip those steps.

Mode K — Page kit (whole README as cards)

Read references/page-kit.md first.

1. Gather real content. Profile: the batched interview from references/profile-readme.md. Project: run the core skill's fact-gathering; commands and install steps stay in markdown blocks so verify_readme.py can check them. If the user pasted a sample README (theirs or someone else's), map each of its patterns with the "Learning from a sample README" table in page-kit.md: typing banner → hero roles, YAML about-me → code, portrait → portrait, badge wall → certs, project table → projects with links, LeetCode/Codeforces → stats. Take the layout, never the content, and drop widgets whose hosts are dead.
2. python SKILL_DIR/scripts/make_page.py --init profile|project > page.json. Fill every {{…}} from that content and delete fields or blocks with no data (the script refuses to run with placeholders left). Never invent metrics, awards or descriptions. Choose the theme from the brand (page-kit.md rule 4), or pass accents to match a logo.
3. python SKILL_DIR/scripts/make_page.py --spec page.json --preview preview.html writes every card (light + dark) and the README. Open the preview, check both themes for clipped text, shorten copy that the script had to shrink a lot, and re-run.
4. Score with the core skill (score_readme.py, --profile for profiles) and check_links.py when network is allowed. Don't commit preview.html.
5. Tell the user what was written, where it goes, and any setup (the snake workflow; stats cards are a shared public instance).

Mode G — Design (header, footer, banners)

Read references/design.md first.

1. Choose the header pattern (centered stack / minimal / splash / profile hero) and a banner style + palette from the style table (project type, brand colour, audience). If it isn't obvious, generate 2–3 options and show the user.
2. Generate the assets (dark + light, self-contained, committed to the repo):

   python SKILL_DIR/scripts/make_banner.py --style <style> [--palette <p>] [--accent "#HEX"] [--logo <file>] --title "<name>" --subtitle "<pitch ≤ 12 words>" [--tag "<category>"] --out .github/assets
   python SKILL_DIR/scripts/make_banner.py --kind footer --style <minimal|wave|vortex> --title "<credit line>" --out .github/assets
   python SKILL_DIR/scripts/make_banner.py --kind divider --style <aurora|beam> --out .github/assets

   python SKILL_DIR/scripts/make_banner.py --list prints every style and palette. For profiles, put the assets in assets/. For Hugging Face, use #hf-dark-mode-only / #hf-light-mode-only instead of <picture>.
3. Pass --href <url> so the printed snippet is already wrapped in a link, and paste it exactly as printed. Never type <a href="…"><picture> on one line with the <source> on the next: GitHub empties that <picture>, so the dark variant never shows and the click opens the SVG file. Then put the pitch, badges (one style, palette colour) and link row below it, as in design.md §2. If the project has a logo (look for logo.*, icon.*, assets/brand/*, or ask), pass --logo. It is embedded in the SVG (no external request). Spotlight centres it above the title, vortex puts it in the eye of the vortex, and other styles place it on the left. Use a transparent PNG about 320 px wide or an SVG; a logo with a white box looks wrong on dark banners. Pick a palette (or --accent) that matches the logo's colours. Shader looks: vortex (default inferno palette: warm black, red-orange blades, condensed serif caps), beam (light racing around the edge over a nebula), shatter (voronoi glass), prism (RGB-split blinds with a swipe). These use CSS animation only, so they stop for visitors with reduced motion. For a ShaderGradient look, use --style shader --palette halo|pensive|interstella|universe|mandarin|nighty. For a landing-page feel, use the spotlight hero + CTA buttons (--kind button) from design.md §10 and templates/design/hero-landing.md, optionally repeating the CTA before the footer with templates/design/cta-section.md.
4. End with a footer (design.md §3): license line, credit, back-to-top, plus the footer SVG for polished projects and profiles.
5. Run the core skill's score_readme.py and fix the design findings (missing dark variant, mixed badge styles, external fonts in SVGs, oversized assets).
6. Visual check: if a browser is available, render the README or the SVGs and look at both themes. At minimum, open each SVG once to confirm the title is fully visible.

Never: hotlink a third-party banner by default, put the only copy of the pitch inside an image, use more than 2 animations above the fold, or animate the text in from blank.

Mode B — Profile README

1. Read references/profile-readme.md. Collect (batch in one question): GitHub username, name/role/one-liner, current focus, top skills (or derive from their public repos if they allow), socials, preferred archetype (minimal · stats dashboard · creative/animated · code-mode · data/ML · student · OSS maintainer · retro · badges wall · Actions-dynamic · org · game mode · typing · anime/art · fancy fonts · descriptive · simple-but-innovative · icons · just an image; if they name an awesome-github-profile category, use the mapping in profile-readme.md), and dark-mode preference.
2. Start from templates/profile/<archetype>.md. Replace every {{PLACEHOLDER}}; delete sections with no data rather than leaving placeholders. Generate the profile hero banner and footer with make_banner.py (Mode G) in the user's accent colour. Offer the 3D contribution calendar (workflows/profile-3d.yml) for profiles that want a 3D visual.
3. Widgets: pick from references/widgets.md. Rules: ≤ 4 dynamic cards; use <picture> or theme params for dark/light; give each a descriptive alt; add the self-host / Actions fallback comment for stats cards; skill icons only for skills the user really uses (≤ 15). Never invent stats, employers, projects or links: they come from the user or their public profile.
4. If the archetype needs automation (snake, latest blog posts, WakaTime, metrics, the tic-tac-toe game), also write the workflow from templates/profile/workflows/ (the game also needs templates/profile/game/tictactoe.py at .github/scripts/) and tell the user which secrets/settings to add. For fancy fonts, generate every styled string with python SKILL_DIR/scripts/fancy_text.py "TEXT" --style <style>; never type the Unicode yourself.
5. Run score_readme.py --profile and check_links.py from the core skill (if network allowed) and fix failures.
6. Tell the user exactly where it goes: repo named exactly like their username, public, README.md at root (org: .github repo → profile/README.md).

Learning loop — adapt to this user's taste

If the core skill is installed, use its scripts/learn.py (see "Learning loop" in its SKILL.md) for design choices too. Skip it if the user said not to learn.

1. Before choosing, run learn.py observe README.md, then learn.py suggest --repo <path> --context mode=<design|profile|page-kit> --decision banner.style:<your first choice>,<2–4 fitting alternatives> --decision banner.palette:<first choice>,<alternatives>. Put your own best choice first: it stays the pick until there is evidence. Add --decision profile.archetype:… for profiles and --decision page.theme:… for the page kit.
2. Use each pick and follow every saved preferences line, unless the user asks for something else now. Record rejections and praise with learn.py reward banner.style=<style> --value 0|1.
3. After generating, snapshot the choices with a file: marker, so the script can tell later whether the user kept or replaced the asset:

   python <core SKILL_DIR>/scripts/learn.py snapshot README.md --context mode=design --choice banner.style=beam@file:.github/assets/header-dark.svg --choice banner.palette=ghost@file:.github/assets/header-dark.svg

Final message to the user

Keep it short: which assets and files you wrote, how to preview both themes, and any setup they must do (Actions secrets, making the profile repo public).