# Github Readme > Generate or optimize GitHub README files with SEO-optimized structure, badges, and 21:9 banner image generation via GPT Image 2. - **Type:** Skill - **Install:** `agentstack add skill-avalonreset-legends-github-github-readme` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [avalonreset](https://agentstack.voostack.com/s/avalonreset) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [avalonreset](https://github.com/avalonreset) - **Source:** https://github.com/avalonreset/legends-github/tree/main/skills/github-readme ## Install ```sh agentstack add skill-avalonreset-legends-github-github-readme ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # GitHub README -- Generation and Optimization ## Headless Contract For deterministic local preview/write flows, use: ```bash 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 keyword_suggestions for each → filter by volume/difficulty/relevance → call serp_organic_live_advanced 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 KIE_API_KEY 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: ```bash mkdir -p .github-audit grep -qxF '.github-audit/' .gitignore 2>/dev/null || echo '.github-audit/' >> .gitignore ``` Write `.github-audit/readme-data.json` with: timestamp, score_before, score_after, banner_generated, banner_path, keywords_integrated (primary_in_h1, primary_in_first_paragraph, secondary_in_h2 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: ```python 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. ```markdown ``` **Prerequisite:** Load KIE_API_KEY from the standard dotenv locations: ```bash 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). 2. Poll for completion, download the 16:9 result. 3. Crop the 16:9 to **2:1** (center crop, trim ~5% from top and bottom). 4. Resize to exactly **1280x640** (GitHub's required dimensions). 5. 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. 6. If over 1MB, re-save at quality 70. 7. Save to `assets/social-preview.jpg`. 8. 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](https://github.com/avalonreset) - **Source:** [avalonreset/legends-github](https://github.com/avalonreset/legends-github) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-avalonreset-legends-github-github-readme - Seller: https://agentstack.voostack.com/s/avalonreset - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.