Github Readme

GitHub README -- Generation and Optimization

Headless Contract

For deterministic local preview/write flows, use:

python3 scripts/run_headless.py readme --path /path/to/repo
python3 scripts/run_headless.py readme --path /path/to/repo --generate-assets
python3 scripts/run_headless.py readme --path /path/to/repo --write

readme defaults to preview mode. It writes .github-audit/readme-data.json plus README-REPORT.md, README-PREVIEW.md, and README-SUMMARY.json. --write is the explicit approval gate for rewriting README.md. --generate-assets reuses an existing banner asset when present, otherwise it can generate a KIE-backed banner plus assets/social-preview.jpg and records local/raw/settings links in the cache and report artifacts.

Process (GARE Pattern)

1. Gather

Step 0 -- Check shared data cache: Before gathering, check .github-audit/ for cached data from other skills. Reference: github/references/shared-data-cache.md for schemas.

• seo-data.json (REQUIRED -- do NOT skip) -- primary keyword, secondary keywords, PAA

questions, AI visibility. If this cache file is missing, you MUST gather SEO data before proceeding. Check if DataForSEO MCP tools are available (search for dataforseo_labs_google_keyword_suggestions). If available, run the keyword research inline: generate 2 seed keywords from repo description → call keywordsuggestions for each → filter by volume/difficulty/relevance → call serporganicliveadvanced on the best candidate to verify GitHub repos can rank for it. This costs ~20-30 cents and is NON-NEGOTIABLE -- a README without data-backed keywords is a failed deliverable. If DataForSEO MCP is genuinely not configured (tools not found), THEN and ONLY THEN fall back to codebase-derived keywords and mark SEO as "unverified."

• repo-context.json (optional) -- repo type, intent, language, metadata. If missing,

gather yourself via gh repo view.

• legal-data.json (optional) -- license type for badge selection. If missing, just

check LICENSE file directly.

• audit-data.json (optional) -- README quality findings from prior audit. If present,

use to prioritize which sections need the most improvement.

• Codebase scan: What does this project actually do?
• Read package.json/setup.py/Cargo.toml for description, scripts, dependencies
• Check for existing docs, examples, config files
• Identify main entry point and key exports/commands
• Existing README: Read current README.md (if any)
• Also check for README.rst (reStructuredText) -- some Python/Sphinx projects use it
• If both exist, README.md takes priority (GitHub renders it on the landing page)
• Assess structure, headings, content depth
• Identify what's missing vs. ideal for this repo type
• SEO data: Use keyword opportunity data from the orchestrator's SEO data pass,

or run github-seo inline if running standalone.

• If SEO data block was provided (from Step 3.5 of orchestrator), use it directly:
• Primary keyword (Sweet Spot category) → goes in H1 tagline and first paragraph
• Secondary keywords (Worth It category) → go in H2 headings where natural
• "Skip" keywords → do NOT target in H1/H2, but if a Skip keyword appears

naturally in body text and is semantically relevant, that's fine -- just don't optimize headings or structure around it. The distinction is between "targeting" (building structure around a keyword) and "mentioning" (natural use in prose).

• AI citation status → if not cited, add stronger "X is a Y that does Z" definition
• If running standalone via github-readme, gather SEO data yourself:
• If DataForSEO MCP available: run the Keyword Opportunity Framework from

github-seo skill (seed generation → keyword expansion → volume → difficulty → SERP viability check). The SERP check is critical -- only target keywords where GitHub repos actually appear in Google results.

• If DataForSEO not available: analyze codebase, check competitor repos via

gh search repos, apply patterns from github-seo-guide.md

• In all cases, produce: primary keyword, secondary keywords, recommended H1, H2 headings
• Every keyword placed in the README must have a justification (volume data, competitor

analysis, or codebase relevance)

• Legal data: Check LICENSE type for License section
• Audit data: If a prior github-audit run exists, use its README quality findings
• Intent + repo type: From orchestrator context
• Banner status: Does the repo already have a banner image? Check for assets/banner.webp, assets/banner.jpg, assets/banner.png, or any image referenced at the top of README

2. Analyze

Reference: Read github/references/readme-framework.md for structure patterns. Reference: Read github/references/repo-type-templates.md for per-type README structure.

Docs-site detection: If the Homepage URL points to a documentation site (readthedocs, github.io, custom docs domain) or the README links to external docs, apply adjusted expectations:

• Do NOT penalize for missing Installation/Configuration/API sections if docs

cover them -- the README is a gateway, not the full docs

• DO still require: strong H1 + tagline, opening paragraph with keywords,

badges, one code example, Contributing link, License mention

• Note in your analysis: "External docs detected at [URL] -- scoring adjusted"
• Completeness score should evaluate whether the README effectively directs

users to the docs, not whether it duplicates them

Score the current README (if exists) using these objective rubrics. Each criterion has specific checkpoints worth defined points. Score by counting what's present -- not by subjective impression.

Structure (20 points max)

| Checkpoint | Points | |------------|--------| | Exactly one H1 heading | 4 | | H1 includes descriptive tagline (not just project name) | 4 | | Proper heading hierarchy (no skipped levels) | 4 | | At least 4 H2 sections | 4 | | Table of Contents present (for READMEs with 4+ sections) | 4 |

Content Depth (20 points max)

| Checkpoint | Points | |------------|--------| | Installation/setup instructions with code block | 5 | | At least one usage example with code block | 5 | | Configuration, API reference, or detailed options/commands section (skip if repo type doesn't need config -- redistribute 4 pts to other Content checkpoints) | 4 | | Architecture/how-it-works explanation | 3 | | Troubleshooting, FAQ, or common issues | 3 |

SEO Optimization (20 points max)

| Checkpoint | Points | |------------|--------| | Primary keyword in H1 (verified via SEO data, not guessed) | 6 | | Primary keyword in first paragraph | 4 | | Secondary keywords in at least 2 H2 headings | 4 | | All images have descriptive alt text with keywords | 3 | | Descriptive link text (no "click here") | 3 |

Badges (10 points max)

| Checkpoint | Points | |------------|--------| | At least one badge present | 3 | | License badge | 2 | | Version/release badge | 2 | | CI/build status or other quality signal badge | 3 |

Visual Appeal (10 points max)

| Checkpoint | Points | |------------|--------| | Banner image at top | 4 | | Code blocks use syntax highlighting (language specified) | 2 | | At least one table for structured data | 2 | | Short paragraphs (no walls of text over 5 sentences) | 2 |

Completeness (10 points max)

| Checkpoint | Points | |------------|--------| | All required sections for repo type present | 4 | | Contributing section or link to CONTRIBUTING.md | 2 | | License section with link to LICENSE file | 2 | | Links to external resources (docs, homepage, etc.) | 2 |

AI Citability (10 points max)

| Checkpoint | Points | |------------|--------| | Clear "X is a Y that does Z" definition in first 2 sentences | 4 | | Structured comparison table (vs alternatives) | 2 | | Answer-first formatting for key questions (FAQ or PAA-derived) | 2 | | Specific quantifiable claims (stats, benchmarks, counts) | 2 |

3. Recommend

Present README plan before writing:

## README Optimization Plan

### Current Score: XX/100
[breakdown by criterion]

### Proposed Structure:
1. Banner image (generated via KIE.ai GPT Image 2)
2. H1: [Project Name -- keyword-rich tagline]
3. Badges: [CI, version, license, downloads]
4. Opening paragraph: [with primary keyword]
5. Table of Contents
6. [Section list based on repo type]

### Banner Concept:
- Visual: [description of banner concept based on project domain]
- Aspect ratio: 21:9 (default) or [user preference]
- Resolution: 1K (default) or [user preference]

### Keyword Integration:
- H1: "[primary keyword]"
- First paragraph: "[primary keyword] naturally embedded"
- H2 headings: [list with secondary keywords]

### Data Sources Used:
- [list: codebase scan, SEO analysis, audit findings, etc.]

4. Execute (with user approval)

PAUSE HERE for interactive runs. After presenting the optimization plan (Step 3), ask the user: "Ready to generate the optimized README? (This will also generate a banner image if KIEAPIKEY is available.)"

Do NOT generate the README until the user confirms. The plan is the checkpoint -- the user may want to adjust the keyword strategy, change the tone, skip the banner, or add/remove sections before you write anything.

If the user invoked the skill with a clear directive like "generate a readme" or "optimize this readme", treat that as pre-approval and proceed without pausing. For deterministic run_headless.py readme --write, the --write flag is the explicit approval signal.

Generate the full README.md or a rewritten version of the existing one.

Write to shared data cache after generating the README:

mkdir -p .github-audit
grep -qxF '.github-audit/' .gitignore 2>/dev/null || echo '.github-audit/' >> .gitignore

Write .github-audit/readme-data.json with: timestamp, scorebefore, scoreafter, bannergenerated, bannerpath, keywordsintegrated (primaryinh1, primaryinfirstparagraph, secondaryinh2 list), sections list. Reference: github/references/shared-data-cache.md for exact schema.

README Generation Rules

Image Format Optimization (applies to ALL images)

Reference: Read github/references/banner-generation.md -- see the Image Format Optimization section for the full decision table.

The pipeline: always generate as PNG (lossless source), then convert to the optimal delivery format. See banner-generation.md for the full Image Format Pipeline section.

When generating or placing images in the README:

• Banners (AI-generated): request PNG from KIE.ai, convert to WebP (quality 80).

WebP is ~30% smaller than JPEG and GitHub renders it natively.

• Screenshots (terminal, UI): keep as PNG. Lossless, sharp text, often smaller

than lossy formats for flat-color content. Do NOT convert screenshots.

• Logos/icons: PNG or SVG. Clean edges need lossless compression.
• Flag existing repo images using the wrong format or that are oversized:
• PNG banners/photos > 200KB: convert to WebP (saves 60-70%)
• JPEG screenshots with blurry text: should be PNG
• Any image > 1MB: flag for optimization

Offer to convert, not just flag. Use Pillow to convert, strip metadata, and show savings:

from PIL import Image
import os
src = Image.open("assets/banner.png")
clean = Image.new(src.mode, src.size)  # strip all metadata
clean.putdata(list(src.getdata()))
clean.save("assets/banner.webp", "WEBP", quality=80, method=6)
old = os.path.getsize("assets/banner.png")
new = os.path.getsize("assets/banner.webp")
print(f"{old//1024}KB -> {new//1024}KB ({100-new*100//old}% smaller, metadata stripped)")

Banner Image (Standard Practice -- Two-Step)

Every README should include a professional banner. Generate one as part of the standard README creation/optimization workflow using the two-step process.

Reference: Read github/references/banner-generation.md for full details including prompt strategy, text compositing script, and positioning principles.

Banner + Social Preview flow (MANDATORY -- do not skip any step):

1. Craft a background prompt (visual metaphor, NO text in image, subject offset to one side)
2. Call KIE.ai GPT Image 2 API to generate background (21:9)
3. Poll for completion, download the generated source as assets/banner-source.png
4. Composite text overlay via Pillow (project name, tagline, optional features)
5. Convert to WebP (quality 80): assets/banner.webp, delete source PNG
6. Place at the very top of README, before H1:
7. Generate social preview from the banner (see Social Preview Pipeline below)

This is a 7-step flow, not 6. The social preview is not optional.

Prerequisite: Load KIEAPIKEY from the standard dotenv locations:

if [ -z "$KIE_API_KEY" ]; then
  for envfile in ./.env.local ./.env github/.env.local github/.env ~/.env.local ~/.env; do
    if [ -f "$envfile" ]; then
      export $(grep -v '^#' "$envfile" | xargs) 2>/dev/null
      break
    fi
  done
fi
[ -n "$KIE_API_KEY" ] && echo "KIE_API_KEY loaded" || echo "KIE_API_KEY NOT FOUND"

If the key is not found after checking those dotenv locations, STOP and show this message:

Banner generation requires a KIE.ai API key. It takes about 2 minutes to set up:

1. Go to https://kie.ai/api-key and create a free account
2. Copy your API key
3. Paste it into `./.env.local` (preferred) or `github/.env`:
   KIE_API_KEY=your_key_here

Want to set this up now, or skip the banner and continue with the README?

Wait for the user to respond. If they want to set it up, help them. If they say skip/continue/later, generate the rest of the README with a placeholder comment: `` at the top.

Social Preview Pipeline (MANDATORY after banner generation)

After generating the README banner, ALWAYS run the social preview pipeline. This is step 7 of the banner flow. Do NOT skip it.

Reference: Read github/references/banner-generation.md section "Social Preview Image Generation" for the full pipeline and Pillow script.

The pipeline:

1. Feed the banner into KIE.ai as input_urls with gpt-image-2-image-to-image at 16:9 aspect ratio.

This recomposes the design for the new ratio (AI adapts layout, centers elements). Use the raw GitHub URL of the pushed banner as the input_urls source. If the banner is WebP, convert to PNG first (GPT Image 2 rejects WebP input).

1. Poll for completion, download the 16:9 result.
2. Crop the 16:9 to 2:1 (center crop, trim ~5% from top and bottom).
3. Resize to exactly 1280x640 (GitHub's required dimensions).
4. Save as JPEG at quality 85 (GitHub rejects WebP for social previews, and

PNGs at 1280x640 often exceed the 1MB upload limit). Strip all metadata.

1. If over 1MB, re-save at quality 70.
2. Save to assets/social-preview.jpg.
3. Show the user the result via Read tool, provide clickable links, and provide

the manual upload instructions for https://github.com/{owner}/{repo}/settings.

Fallback: No banner exists (new project or banner was skipped): If there is no banner to feed as input_urls, generate the social preview from scratch as a standalone gpt-image-2-text-to-image KIE.ai call at 16:9. Use this prompt formula:

Professional 16:9 social preview card for a GitHub project called "[Project Name]".
Dark background with [color accent matching project theme]. Text "[Project Name]"
centered in bold white sans-serif, subtitle "[one-line description]" below in
smaller text. Clean, modern tech aesthetic. Centered composition with padding
on all edges (critical for the 2:1 crop that follows).

Then run the same crop/resize/JPEG pipeline as the banner-based path (steps 3-8). The key difference: explicitly ask for centered composition with edge padding, because there's no existing design to recompose from and the 2:1 crop will trim the top and

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: avalonreset
• Source: avalonreset/legends-github
• License: MIT

Install and usage instructions live in the source repository linked above.