Readme Enhance

README Enhancement Generator

Enhance GitHub repository README files with marketing badges and NotebookLM-style infographics that capture project architecture, features, technology, and purpose. Create engaging visual elements that attract users and communicate project value.

Overview

This skill analyzes a project's codebase, documentation, and configuration to generate:

1. Marketing badges (shields.io format) for project metrics and status
2. A visual infographic (SVG by default, or AI-generated image prompt)
3. Updated README.md with badges, infographic, and generation prompt display

Workflow

Step 1: Check for Configuration

Look for optional settings file at .claude/github-social.local.md.

Parse YAML frontmatter for readme-enhance settings:

• provider: Image generation provider (svg, dalle-3, gemini, manual) - default: svg
• badge_style: Badge style (flat, flat-square, plastic, for-the-badge) - default: for-the-badge
• badge_color: Default badge color
• infographic_style: architecture | features | hybrid - default: hybrid
• infographic_output: Output path for infographic - default: .github/readme-infographic.svg
• dark_mode: Dark mode support (false, true, both) - default: false
• update_readme: Whether to modify README.md directly - default: true

Command-line overrides (highest priority):

• --provider=svg|dalle-3|gemini|manual
• --badges-only (skip infographic)
• --infographic-only (skip badges)
• --dry-run (preview without changes)

If no config exists, use defaults: provider: svg, badge_style: for-the-badge, infographic_style: hybrid.

Step 2: Analyze Project

Gather project context by reading available files:

Primary sources:

1. README.md - Current content, existing badges
2. package.json / Cargo.toml / pyproject.toml / go.mod - Name, version, description
3. CLAUDE.md - Project context and guidelines
4. .github/workflows/ - CI/CD configuration
5. LICENSE - License type

Extract these elements:

• Project name: Official name from manifest
• Version: Current version number
• License: License type (MIT, Apache-2.0, etc.)
• Primary language: From file extensions or manifest
• Package registry: npm, crates.io, PyPI, Go modules
• CI system: GitHub Actions, CircleCI, Travis
• Purpose: What problem does it solve?
• Architecture: Key components and data flow
• Features: Top 3-5 capabilities
• Technology stack: Languages, frameworks, tools

Step 3: Generate Badge Set

Create shields.io badges based on project analysis.

Core Badges (always include if applicable):

Engagement Badges (include for open source):

• GitHub Stars
• GitHub Issues
• Last Commit
• PRs Welcome

Plugin-Specific Badges:

• Claude Code Plugin badge (for Claude plugins)
• MCP Server badge (for MCP integrations)

Context-Dependent Badges (include if detected):

• Coverage (if test coverage configured)
• Documentation (if docs site exists)
• Downloads (if published to registry)
• Discord/Slack (if community links found)
• Sponsors (if FUNDING.yml exists)

Badge Generation Rules:

1. Detect repository owner and name from git remote
2. Use consistent style across all badges
3. Order badges by importance: status > version > metrics > engagement
4. Limit to 8-12 badges to avoid clutter

See references/badge-catalog.md for comprehensive badge patterns.

Step 4: Generate Infographic

Route to appropriate generation method based on provider setting.

Step 4a: Generate SVG Infographic (Default)

When provider: svg or not configured, generate a clean SVG infographic directly.

Determine Layout based on project type:

SVG Infographic Structure (1280x640):

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640">
  <defs>
    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" style="stop-color:[domain-color-1]"/>
      <stop offset="100%" style="stop-color:[domain-color-2]"/>
    </linearGradient>
  </defs>

  <!-- Background -->
  <rect width="1280" height="640" fill="url(#bg)"/>

  <!-- Header Panel (top 15%) -->
  <text x="640" y="60" font-family="..." font-size="36" font-weight="700"
        text-anchor="middle" fill="#f8fafc">PROJECT-NAME</text>
  <text x="640" y="90" font-family="..." font-size="18"
        text-anchor="middle" fill="#94a3b8">Tagline here</text>

  <!-- Main Content Area (middle 70%) -->
  <!-- Architecture section OR Features section OR Hybrid -->

  <!-- Footer Strip (bottom 15%) -->
  <text x="640" y="600" font-family="..." font-size="14"
        text-anchor="middle" fill="#64748b">
    Install: npm install project-name | docs.example.com
  </text>
</svg>

Infographic Sections:

1. Header Panel (top 15%)

   • Project name with stylized typography
   • One-line tagline capturing essence
   • Optional: key metric badge (stars, downloads)

2. Architecture Panel (weight varies)

   • Component boxes with connections
   • Data flow arrows
   • Layer visualization

3. Features Panel (weight varies)

   • 3-5 capabilities as icons + labels
   • Benefit statements
   • Visual hierarchy

4. Technology Strip (optional)

   • Language/framework icons as simple shapes
   • Stack visualization

5. Footer Strip (bottom 15%)

   • Install command
   • Links hint

See references/svg-infographic-patterns.md for complete layout templates.

Step 4b: Generate AI Image Prompt

When provider: dalle-3, gemini, or manual:

Craft a detailed NotebookLM-style infographic prompt:

Prompt Structure:

NotebookLM-style infographic for [project-name], [style] layout,
[Header: project name, tagline],
[Architecture section: component visualization],
[Features section: capability icons and labels],
[Technology section: stack badges],
[Color palette based on domain],
clean modern design, professional typography,
1280x640 pixels for GitHub README display

Negative: cluttered, low contrast, hard to read text, realistic photos

For dalle-3 or gemini, call the respective API (see social-preview skill for API details).

For manual, output the prompt for user to copy.

Step 5: Update README.md

Badge Placement Strategy:

1. Locate existing badge section (lines starting with [![ after H1)
2. If found, replace entire badge block
3. If not found, insert after first H1 heading
4. Preserve any custom badges not matching generated patterns

Badge Section Format:

# Project Name

[![License](badge-url)](link)
[![Version](badge-url)](link)
[![Build](badge-url)](link)
...

Infographic Placement with Prompt Display:

Insert after badges, before main description. Always include the collapsible prompt section (like documentation-review pattern):

# Project Name

[![badges...](badges)]

Short one-line description.

<!-- Infographic: Visual summary of project -->
<p align="center">
  <img src=".github/readme-infographic.svg" alt="Project Overview" width="800">
</p>

<details>
<summary>View infographic generation prompt</summary>

[The exact prompt or SVG generation description used]

Layout: [style] layout (1280x640) Background: [color description]

Sections:

1. HEADER: "[project-name]" - [tagline]
4. FOOTER: [install command] | [links]

Color palette: [colors with hex codes] Style: [style description]

</details>

## Features

...rest of README...

Dark Mode Support:

If dark_mode: both, use the <picture> element:

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/readme-infographic-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset=".github/readme-infographic.svg">
    <img src=".github/readme-infographic.svg" alt="Project Overview" width="800">
  </picture>
</p>

Step 6: Output Results

If update_readme is true:

1. Write SVG infographic to infographic_output path
2. If dark_mode: both, write dark variant as well
3. Update README.md with badges, infographic, and prompt display
4. Report changes made

If update_readme is false (or --dry-run):

1. Output badge markdown for manual insertion
2. Display SVG content or image prompt
3. Show README changes that would be made
4. Provide placement instructions

Color Palettes by Domain

DevTools/CLI:

• Background: #0f172a → #1e293b
• Accent: #06b6d4 (cyan)
• Text: #f8fafc

AI/ML:

• Background: #1e1b4b → #312e81
• Accent: #8b5cf6 (violet)
• Text: #f8fafc

Web/Frontend:

• Background: #0c4a6e → #075985
• Accent: #3b82f6 (blue)
• Text: #f8fafc

Data/Analytics:

• Background: #1e3a5f → #0f172a
• Accent: #f59e0b (amber), #3b82f6 (blue)
• Text: #f8fafc

Security:

• Background: #0f172a → #1e293b
• Accent: #22c55e (green), #eab308 (yellow)
• Text: #f8fafc

Infrastructure:

• Background: #1e293b → #334155
• Accent: #06b6d4 (cyan)
• Text: #f8fafc

Error Handling

No README.md found: Create minimal README with project name from manifest, then enhance.

No package manifest found: Use git remote URL to extract project name, prompt for missing info.

Git remote not configured: Ask user for repository owner/name for badge URLs.

Existing custom badges: Preserve badges that don't match generated patterns, merge intelligently.

SVG file too large (>100KB): Simplify layout, reduce sections, warn user.

Configuration Reference

Full configuration options in .claude/github-social.local.md:

---
# Image generation provider
provider: svg              # svg | dalle-3 | gemini | manual

# Badge settings
badge_style: for-the-badge # flat | flat-square | plastic | for-the-badge
badge_color: blueviolet    # Default color for custom badges

# Infographic settings
infographic_style: hybrid  # architecture | features | hybrid
infographic_output: .github/readme-infographic.svg
dark_mode: false           # false | true | both

# Behavior
update_readme: true        # Modify README.md directly
custom_badges: []          # Additional custom badges to include
exclude_badges: []         # Badge types to exclude
---

Additional Resources

Reference Files

For detailed patterns and comprehensive catalogs:

• references/badge-catalog.md - Complete badge patterns by category
• references/svg-infographic-patterns.md - SVG layout templates by project type
• references/infographic-prompts.md - AI image prompt templates
• references/readme-templates.md - Badge placement and README structure patterns

Example Files

Working examples for different project types:

• examples/badges-devtools.md - Badge set for CLI/DevTools projects
• examples/badges-library.md - Badge set for libraries and SDKs
• examples/infographic-example.md - Complete infographic prompt example

Converted and distributed by TomeVault — claim your Tome and manage your conversions.