YuShenLiu06/PCHSystem / .claude/skills/beautify-github-readme
beautify-github-readme
VerifiedRedesign 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.0 KB |
| agents/openai.yaml | config | 328 B |
| references/content-architecture.md | markdown | 1.3 KB |
| references/github-readme-canvas.md | markdown | 3.3 KB |
| references/hybrid-svg-production.md | markdown | 4.5 KB |
| references/motion-production.md | markdown | 6.7 KB |
| references/project-native-hero.md | markdown | 5.9 KB |
| references/showcase-contribution.md | markdown | 2.5 KB |
| references/svg-production.md | markdown | 9.9 KB |
| references/visual-direction.md | markdown | 3.6 KB |
| scripts/audit_readme.pyexecutable | script | 2.7 KB |
| scripts/render_motion_gif.pyexecutable | script | 19.3 KB |
references/visual-direction.md
View on GitHub# Theme-specific visual direction
## Derivation order
Choose the visual system in this order:
1. Real product semantics: what the repository actually helps people do.
2. Existing identity: logo, UI tokens, screenshots, diagrams, code style, or documentation tone.
3. Audience expectation: technical trust, creative energy, research clarity, or operational confidence.
4. Visual finish: palette, type scale, material, motif, and composition.
Do not start with a fashionable finish and force the project into it.
## Theme cues
| Repository type | Useful visual cues | Avoid |
| --- | --- | --- |
| CLI / developer tool | terminal rhythm, cursor, monospace accents, logs, precise grids | fake code, neon overload |
| AI product | relationships, transformations, evidence, input/output contrast | generic glowing brain imagery |
| Design resource | keylines, material samples, artboards, crop marks, specimen walls | portfolio decoration with no proof |
| Data / research | coordinates, annotations, charts, source labels, measured spacing | dashboard clichés unrelated to the data |
| Library / framework | modules, composition, API flow, dependency structure | pretending documentation is a marketing site |
| Creator project | voice, editorial imagery, sequences, human scale | generic SaaS landing-page sections |
## Monochrome technical direction
For infrastructure, security, research, systems, hardware, and other serious technical repositories, consider a black-and-white direction before adding brand color:
- Use black, warm white, and two neutral grays.
- Use a strict grid, thin rules, large numbers, mono metadata, and restrained diagrams.
- Mix sans-serif, monospace, or a sober serif only when the project supports it.
- Replace decorative cards with architecture, specifications, boundaries, results, or real interfaces.
- Avoid gradients, glossy materials, playful rounded tiles, and ornamental shadows.
Monochrome should still come from the project. A security repository may emphasize boundaries and permissions; hardware may emphasize dimensions, interfaces, and real objects; research may emphasize methods, results, and limits.
## Visual grammar
Freeze five decisions before producing assets:
- **Palette** — 3 to 5 colors with explicit hex values and clear roles.
- **Type** — system font stack; one large display scale, one section scale, one body scale.
- **Shape** — one radius family, one stroke weight, one spacing unit.
- **Motif** — one small recurring project-specific cue.
- **Density** — one deliberate rhythm: sparse editorial, compact technical, or expressive gallery.
The motif is the strongest anti-template device. Repeat it lightly in the hero, section transitions, and showcase, but never as wallpaper everywhere.
## Composition patterns
- **Artifact wall** — several screenshots or outputs, slightly rotated around a shared axis. Best when visual proof is the product.
- **Before / after** — show the transformation when the mechanism matters.
- **System map** — show one source feeding several components or outputs.
- **Annotated specimen** — enlarge one real artifact and label the decisions that matter.
- **Sequence strip** — show three to six dependent stages.
Prefer one strong composition over several small decorative graphics.
## Restraint rules
- Use shadow only to separate overlapping artifacts; keep it soft and low-opacity.
- Do not add top borders to every screenshot or card.
- Keep decorative dots, grids, and lines subordinate to content.
- If several modules compete for attention, remove one before reducing everything.
- A README should feel designed at GitHub's content width, not like a full-screen website squeezed into Markdown.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |