/beautify-github-readme

name: beautify-github-readme
description: Redesign GitHub README homepages or create project-native pure SVG, hybrid SVG-composed PNG/WebP, and opt-in animated GIF assets. Use when a user asks to beautify, redesign, rebrand, visually upgrade, simplify, or audit a GitHub README; create only a hero, section headers, diagrams, badges, motion graphics, showcase modules, or other README assets; or turn a repository homepage into a cohesive visual story. If whole-README work versus asset-only work is unclear, ask which scope the user wants. For hero-like assets where pure SVG and generated raster material are both viable, explain the tradeoffs and confirm the implementation before creating the asset.

Beautify GitHub README

Turn a repository homepage or requested visual asset into a concise, theme-specific visual story. Treat Markdown as the content layer, deterministic SVG as the layout system, and generated raster material as an optional visual ingredient.

Workflow

1. Confirm the mode before editing

Use exactly one execution mode:

• **README mode** — improve the whole README: information order, copy hierarchy, proof, Markdown, and visual system.
• **Asset-only mode** — create only the requested static SVG or visual asset set. Static SVG is the default. Only after the user explicitly opts into meaningful motion, optionally deliver a GitHub-safe GIF while keeping the SVG as the editable fallback. Do not rewrite, reorder, or embed anything in the README unless the user explicitly adds that scope.

If the mode is not explicit, ask one compact question before making changes:

> Would you like me to improve the whole README or only create visual assets? If asset-only, tell me whether you need a hero, section headers, workflow, badge, motion graphic, or a coordinated set.

When a hero, badge, workflow, or diagram has meaningful motion and the user has not specified static or animated output, ask one compact follow-up:

> Should this stay as a static SVG, or would you like a GitHub-safe GIF animation with the SVG kept as the editable fallback?

GIF is opt-in and never the default. If the user declines, does not answer, or has no meaningful motion case, continue with static SVG only. Do not ask when motion would be purely decorative or the user already chose the output. Read-only inspection is allowed before the answer when it helps understand the repository. Do not interpret “use this Skill,” a repository path, or “beautify it” as permission to modify the whole README. Once the user chooses asset-only mode, expanding into README edits requires new authorization.

If the user explicitly asks only for an audit, audit without editing and do not force the two-mode question.

2. Inspect before designing

• Read the existing README, repository tree, package metadata, screenshots, examples, design tokens, logo, and real outputs.
• In asset-only mode, inspect only the context needed to design the requested assets. Reading the README for context does not authorize changing it.
• For a GitHub URL, inspect the current remote page and default branch before proposing changes.
• Identify the audience, the problem solved, the clearest proof, the shortest path to first use, and any claims that lack evidence.
• Preserve unrelated user changes. Start read-only; do not commit, push, rename, or publish without explicit authorization.

3. Confirm the visual implementation before creating hero-like assets

For a hero, large banner, showcase board, or expressive title system where both implementations are viable, explain the difference and ask before producing the asset:

> Which implementation would you like? > > - **Pure SVG** — fully deterministic, lightweight, sharply scalable, easy to edit, and best for typography, diagrams, code, icons, and geometric or pixel-art scenes. It does not use image generation and is weaker for realistic people, hair, organic texture, complex materials, or cinematic lighting. > - **Hybrid SVG composition** — use SVG for layout and typography, optionally use ImageGen for a project-specific raster subject, remove its background when appropriate, and compose the layers into a final PNG/WebP. It supports richer characters, materials, and lighting, but is heavier, partly stochastic, and requires generation plus visual validation. Keep the SVG layout source and transparent subject PNG.

Do not ask this question when the user already chose an implementation, requested an audit, or the asset is obviously deterministic, such as a workflow, architecture diagram, badge, compact section header, or code-native illustration. Do not suggest hybrid composition merely to add decoration. Prefer real screenshots, outputs, logos, or existing project art over generated material.

If the user delegates the decision, default to pure SVG unless generated or photographic material clearly communicates the repository's identity or mechanism better. Do not begin ImageGen work until the user selects hybrid composition or explicitly delegates the choice.

Hybrid composition is an implementation source, not normally the published SVG. Relative raster references inside SVG are unreliable across renderers, while base64-embedded raster layers can make the SVG unnecessarily large. Publish the verified final PNG/WebP by default and keep the SVG layout plus raster layers as editable sources.

4. Extract the project story

Write these before drawing:

Audience:
One-sentence value:
Primary proof:
First successful action:
Visual theme:

Do not invent adoption, benchmarks, compatibility, testimonials, or features. Prefer a real screenshot, output, diagram, or generated artifact over decorative stock imagery.

5. Define a theme-specific visual system

Read [references/visual-direction.md](references/visual-direction.md). Freeze a compact art-direction spec:

Palette: background / foreground / primary / accent / muted
Typography: system font stack / scale / weight contrast
S