git:20260921.a2e8de7 to git:20260921.029882f

497 added, 98 removed. Audit A to A.

---

name: github-readme

- description: Write or improve repository documentation from actual capabilities, verified setup and examples, useful comparisons, and audience needs. Optional artwork and research never block the README.

+ description: Generate or optimize GitHub README files with SEO-optimized structure, badges, and 21:9 banner image generation via GPT Image 2.

---

- # GitHub README

+ # GitHub README -- Generation and Optimization

- Make the project understandable and usable for its intended audience. Preserve

- accurate existing material, upstream credits, and the owner's voice.

+ ## Headless Contract

- ## Runtime and scope

+ For deterministic local preview/write flows, use:

- Resolve **GITHUB_HOME** from this skill directory: `../../github` in source,

- `../github` when installed. Verify `scripts/run_headless.py` exists and read

- `GITHUB_HOME/references/portable-workflows.md`. Resolve **TARGET** separately.

+ ```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

+ ```

- ```text

- python "<GITHUB_HOME>/scripts/run_headless.py" readme --help

- python "<GITHUB_HOME>/scripts/run_headless.py" readme --path "<TARGET>"

- python "<GITHUB_HOME>/scripts/run_headless.py" readme --path "<TARGET>" --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

+ may contain legacy provider behavior. Do not use that flag for new image

+ production; use `scripts/render_social_preview.py` and the social preview SOP.

+ This SOP does not claim the legacy headless runtime has been migrated.

+ ## 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

- Default mode creates `readme-data.json`, `README-REPORT.md`, `README-PREVIEW.md`,

- and `README-SUMMARY.json` at returned artifact paths. Inspect the preview before

- `--write`, which can replace curated content. A targeted edit is often better

- than using an entire generated template. A generated score is not validation.

+ ### Current Score: XX/100

+ [breakdown by criterion]

- ## Gather before drafting

+ ### Proposed Structure:

+ 1. Banner image (approved typography and branding)

+ 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]

- - Read the existing README in its actual format, including RST or other supported

- formats. Do not convert it merely for consistency with a template.

- - Inspect manifests, entrypoints, help output, exports, configuration, tests,

- examples, install scripts, and docs. Establish what works today, what is planned,

- required versions, platform support, and optional integrations.

- - Establish the audience's first useful task. Read external docs when they are

- necessary to assess a gateway README; report inaccessible docs as unavailable.

- - Verify installation sources, package names, license references, and release

- claims. Do not infer that a package is published merely from its manifest.

- - Reuse relevant audit/research context after freshness checks. `seo-data.json`

- is optional. Accurate terminology from implementation is observed evidence,

- even when search-volume measurements are unavailable.

- - Inventory existing images and the owner's design direction. No image is

- required to begin or finish documentation work.

+ ### 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]

- ## Build the right structure

+ ### Keyword Integration:

+ - H1: "[primary keyword]"

+ - First paragraph: "[primary keyword] naturally embedded"

+ - H2 headings: [list with secondary keywords]

- | Project | First useful path | Additional detail when relevant |

- |---|---|---|

- | Library | Install, import, minimal working example, output | Supported versions, API links, lifecycle, compatibility |

- | CLI | Install, invoke one real command, inspect result | Flags, config precedence, exit codes, troubleshooting |

- | Service/application | Run locally, health check, use a workflow | Configuration, persistence, deployment, operational limits |

- | Skill/plugin | Install/load, trigger a task, inspect an artifact | Host capabilities, path resolution, permissions, portability |

- | Research/data | Reproduce a result or load a sample | Methodology, data origin/license, limitations, citation |

- | Documentation | Find the right guide and complete its task | Navigation, prerequisites, version scope, contribution route |

+ ### Data Sources Used:

+ - [list: codebase scan, SEO analysis, audit findings, etc.]

+ ```

- A concise README can link to substantial docs without duplicating them. Use a

- clear title, short explanation of purpose and boundaries, a verified first-use

- path, relevant examples, and links the user needs. Add sections because they

- answer questions, not to reach a heading, table, badge, or word count.

+ ### 4. Execute (with user approval)

- ## Support discovery with useful content

+ **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

+ using the approved font and artwork.)"

- Use the terminology the intended audience uses, tied to capabilities present in

- the implementation. Explain concrete use cases, expected outputs, limitations,

- and supported integrations. Descriptive headings and links should remain natural;

- do not force a keyword into every heading or alt text.

+ 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.

- When comparison/alternative intent is relevant, include a fair table or dedicated

- doc using current primary sources. Choose criteria users actually decide on:

- workflow, output, supported platforms, self-hosting, integration surface, cost

- model if verified, and known tradeoffs. Cite sources and dates; distinguish

- measured tests from vendor statements and unknowns. Link to competitors normally;

- do not invent weaknesses, claim superiority without tests, or copy their text.

+ 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.

- Include a migration guide or worked example when it helps users evaluate or

- switch tools. A reproducible example and candid limitation can be more valuable

- than broad positioning. Route deeper query research to `github-seo` only when it

- advances the task. Do not promise rankings, search snippets, AI citations, or stars.

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

- ## Write and validate

+ **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.

- 1. Choose a focused outline based on observed gaps. For a rewrite, preserve the

- content that is already correct and useful. State material assumptions.

- 2. Draft commands against actual source and supported versions. Show expected

- output when checked. Label illustrative output and optional configuration.

- Use placeholder secret names, never credentials or private endpoints.

- 3. When the user requested generation or improvement, write the authorized

- changes and inspect the diff. A review-only request produces a draft/plan.

- Do not require separate plan, preview, and write confirmations for the same

- authorized work.

- 4. Validate relative links, headings/anchors, referenced files, code fences, and

- critical commands. Run relevant existing checks. If installation cannot be

- exercised safely or an external dependency is missing, state that limitation.

- 5. Read the result for accuracy, tone, and needless repetition. Keep roadmap

- claims separate from shipped behavior. Remove placeholders from production

- instructions or clearly list unresolved ones.

+ ## README Generation Rules

- Use `GITHUB_HOME/references/readme-framework.md` and `repo-type-templates.md`

- for ideas, not mandatory rubrics. Preserve LICENSE and upstream acknowledgments

- through structural rewrites. Never fabricate benchmark numbers or compatibility.

+ ### Image Format Optimization (applies to ALL images)

- ## Optional artwork

+ Reference: Read `github/references/banner-generation.md` -- see the

+ **Image Format Optimization** section for the full decision table.

- Use existing approved assets when they help explain the product. Screenshots,

- output samples, and small diagrams can be more useful than a decorative banner.

- Add accurate alt text, check legibility and file size, and preserve source assets.

- Do not delete originals or strip provenance metadata merely to hide generation.

+ **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.

- Generate artwork only when requested, using the host's configured image tool.

- If unavailable, finish the text and report the missing optional capability.

- No provider registration, key request, mascot, banner, avatar, social preview,

- or vendor badge is required. The compatibility `--generate-assets` flag performs

- local asset reuse/preparation; it is not an image-generation provider. Inspect

- its proposed output before using it, since preparation may create derived files.

+ When generating or placing images in the README:

+ - **Banners**: render approved typography to PNG, then derive **WebP** for README delivery.

+ 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

- For a requested social preview, check current platform constraints and account

- capability, inspect the final image, and provide its actual path plus repository

- settings link. Do not assume a private repository's plan from visibility alone.

- Only provide a remote asset link once verified on its actual branch/ref.

+ **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)")

+ ```

- ## Receipt

+ ### Banner and social preview

- Summarize the changed reader journey, useful content added or corrected, and

- validation performed. Separate **observed** results, **unavailable** checks, and

- **not_applicable** items. Link the edited README or draft. Report any unresolved

- claim or setup check; do not substitute a before/after score for evidence.

+ Preserve the owner's approved branding. For Legends, follow

+ [the README style](../../docs/LEGENDS-README-STYLE.md) and

+ [the social preview SOP](../../docs/SOCIAL-PREVIEW-SOP.md).

+ Use deterministic typography with the actual supplied font. KIE.ai is retired.

+ Render the social preview directly at 1280x640 with fixed type sizes and measured

+ safe margins. Do not crop a 16:9 image or shrink text to force it to fit.

+ Attempt authorized upload through available browser/computer-use tools, verify

+ it visually, and give a prepared manual handoff only when that route is blocked.

+ ### H1 (Exactly One)

+ For Legends banners, use the banner-only H1 from `docs/LEGENDS-README-STYLE.md`;

+ do not add a duplicate visible product heading. The following text-heading

+ guidance applies when the owner has no banner-heading convention.

+ - Format: `# Project Name - Keyword-rich tagline`

+ - Include primary keyword naturally (do NOT cram multiple keywords into the title)

+ - Keep under 80 characters

+ - The tagline should communicate what the project does, not list keywords

+ - Bad: `# MyTool - Fast Python CLI Tool Framework Library for Developers`

+ - Good: `# MyTool - Build CLI Applications in Minutes`

+ ### Opening Paragraph

+ - First sentence includes primary keyword

+ - Lead with the PROBLEM or NEED, then the solution. Not just "X is a Y that does Z"

+ but "Z is hard/missing/broken. X solves this by..."

+ - Keep it to 2-3 sentences. This becomes the Google search snippet.

+ - The reader should finish this paragraph knowing: what problem exists, what this

+ project does about it, and why they should keep reading.

+ - Bad: "MyTool is a Python framework for building CLI applications with plugins."

+ - Good: "Building CLI tools in Python means wrestling with argparse, plugin systems,

+ and config management. MyTool handles all of it so you can focus on your commands."

+ ### Badge Row

+ Place immediately after H1, before opening paragraph:

+ ```markdown

+ [![CI](badge-url)](link) [![Version](badge-url)](link) [![License](badge-url)](link)

+ ```

+ Select badges based on repo type (see `github/references/releases-guide.md` for URLs).

+ ### Heading Hierarchy

+ - H1: Project name (exactly one)

+ - H2: Major sections (Features, Installation, Usage, etc.)

+ - H3: Subsections within H2s

+ - NEVER skip levels (H1 → H3 without H2)

+ ### Section Flow

+ Every README, regardless of repo type, should follow this rhetorical arc:

+ 1. **Hook** (H1 + opening paragraph): What problem does this solve? Why should I care?

+ 2. **Orient** (features/overview): What does it do? What are the key capabilities?

+ 3. **Onboard** (installation + quick start): How do I get started right now?

+ 4. **Deepen** (usage, API, config, architecture): How do I use it for real?

+ 5. **Invite** (contributing, community, license): How do I get involved?

+ This is not a sales funnel. It is the natural order of questions a developer asks

+ when they land on a repo. Answer them in order and the README feels effortless to read.

+ ### Section Order by Repo Type

+ These map the flow above to concrete H2 sections:

+ **Library/Package:** Features > Installation > Quick Start > Usage > API > Configuration > Contributing > License

+ **CLI Tool:** Installation > Quick Start > Commands > Configuration > Examples > Contributing > License

+ **Framework:** Why This Framework > Getting Started > Documentation > Architecture > Contributing > License

+ **Application:** About > Screenshots > Getting Started > Deployment > Contributing > License

+ **Skill/Plugin:** What It Does > Installation > Commands > Configuration > Examples > License

+ ### Section Pruning

+ Not every project needs every section. A 50-line utility does not need an Architecture

+ diagram. A project with no competitors does not need a comparison table. Apply these rules:

+ - **Drop sections you cannot populate with real content.** A FAQ with invented questions

+ or a Contributing section that just says "PRs welcome" adds noise, not value.

+ - **FAQ requires real questions.** Only add a FAQ section if you have PAA data from SERP

+ results, actual GitHub issues asking common questions, or questions the user explicitly

+ provided. Never fabricate FAQ entries.

+ - **Architecture is for complex projects.** If the project is a single file or a small

+ library, skip it. If understanding the project requires knowing how components connect,

+ include it.

+ - **Comparison tables require real alternatives.** Only include "vs" comparisons if you

+ can name specific competing projects and make honest, factual comparisons.

+ - **When in doubt, leave it out.** A shorter README with strong sections beats a longer

+ one padded with filler. Every section should earn its place.

+ ### Content Rules

+ - Use code blocks for all code examples

+ - Use tables for structured data (commands, options, config)

+ - Use descriptive link text (never "click here")

+ - Keep paragraphs short (2-4 sentences)

+ - Include at least one code example in Quick Start

+ - NEVER use em dashes (--) in generated READMEs. Use commas, periods, or rewrite the sentence instead.

+ ### Disclaimer Rules

+ - If the project includes features that provide legal, financial, medical, or security

+ guidance (license selection, compliance checking, vulnerability scanning, etc.), the

+ README MUST include a brief disclaimer noting that the tool's output is automated

+ assistance, not professional advice. Place it in the relevant section or in a dedicated

+ "Disclaimer" subsection near the bottom (before License).

+ - Keep it short: one sentence acknowledging the limitation plus a pointer to the skill's

+ detailed disclaimers. Do not bury it or make it hard to find.

+ ### Example Quality

+ - Examples should show what happens, not just what to type. Include expected output

+ or describe the result after the code block ("This spawns 6 agents and returns a

+ score breakdown within 30 seconds.")

+ - For tools with visual output, describe what the user will see.

+ - For tools with before/after effects, show both states if practical.

+ - One detailed example is worth more than five one-liners.

+ ### SEO Rules

+ - Primary keyword in H1 and first paragraph

+ - Secondary keywords in H2 headings (where natural)

+ - Natural keyword density (1-3%)

+ - Semantic keyword variations throughout

+ - All images have descriptive alt text

+ ### AI Citability Rules

+ - Include a clear definition statement: "X is a Y that does Z"

+ - Add structured comparisons (tables) if alternatives exist

+ - Include specific statistics where available

+ - Use answer-first formatting for key questions

+ ### PAA-to-Content Integration (SERP Intelligence → README Sections)

+ When SEO data includes People Also Ask (PAA) questions from SERP responses,

+ **use them actively in the README** -- don't just report them. PAA questions are

+ Google-confirmed queries that real people ask about this topic.

+ **How to integrate PAA questions:**

+ 1. **Direct FAQ section** -- If 3+ relevant PAA questions were found, add a

+ `## Frequently Asked Questions` section near the bottom (before Contributing).

+ Format each as an H3 with a concise answer-first response (2-3 sentences).

+ This directly targets Google's PAA feature and AI Overview citations.

+ 2. **Fold into existing sections** -- If a PAA question maps to an existing section

+ (e.g., "How do I install X?" → Installation section), ensure that section

+ explicitly answers the question in its opening sentence.

+ 3. **H2 heading alignment** -- If a PAA question matches a natural H2 heading,

+ use the question's phrasing as inspiration (e.g., PAA "What are the advantages

+ of CadQuery?" → H2 "What Makes This Different").

+ **Selection criteria:**

+ - Only use PAA questions directly relevant to the project

+ - Skip PAA questions about competitors (e.g., "Is Knifeprint free?" in a codex-knife README)

+ - Skip off-topic PAA drift (Google's PAA often drifts to unrelated topics)

+ - Prioritize questions that showcase the project's strengths

+ ## Tone by Intent

+ | Intent | Tone | Focus |

+ |--------|------|-------|

+ | Open Source Community | Welcoming, inclusive | Getting Started prominent, Contributing prominent |

+ | Professional Portfolio | Polished, impressive | Technical depth, architecture, results |

+ | Business / Brand | Professional, value-driven | Value proposition, use cases, social proof |

+ | Internal to Public | Documentation-heavy | Architecture, API reference, deployment |

+ | Academic / Research | Formal, methodical | Methodology, citation, reproducibility |

+ | Hobby / Learning | Authentic, casual | Motivation, learning journey, experiments |

+ **Tone consistency rule:** Pick one tone from the table above at the start and hold it

+ through the entire README. Every section should read like the same person wrote it. If

+ the opening is direct and conversational, the Installation section should not suddenly

+ switch to formal documentation-speak. If the project is professional, the FAQ should not

+ get casual. Read the finished README top to bottom and check for tone shifts before

+ presenting the preview.

+ ## Output

+ When optimizing an existing README, follow this exact sequence:

+ ### Step 1: Score Current README

+ Present the 7-criterion score table (see Analyze step) with the current total.

+ ### Step 2: Present Plan

+ Show the optimization plan (see Recommend step) with proposed changes.

+ ### Step 3: Generate and Preview README

+ Generate the full optimized README.md content (or generate from scratch).

+ **Display the complete README in the terminal** so the user can review the copy,

+ headings, keyword placement, and overall flow before anything is written to disk.

+ Present it inside a markdown code fence so the raw markdown is visible:

+ ````

+ ```markdown

+ [full README content here]

+ ```

+ ````

+ Then ask: "Does this look good? I can adjust any section, rewording, or structure

+ before writing it. Say 'write it' to save, or tell me what to change."

+ **Do NOT write README.md until the user approves the preview.** The user may want

+ to iterate on the copy 2-3 times before committing. This is the most important

+ checkpoint -- the plan (Step 2) shows structure, but the preview shows actual words.

+ ### Step 4: Write README to Disk

+ After user approval, write the README.md file and generate the banner (if applicable).

+ ### Step 5: Score New README

+ Re-score the generated README against the same 7 criteria.

+ ### Step 6: Show Delta

+ ```

+ ## Before/After Comparison

+ |-----------|--------|-------|-------|

+ | Structure | X | Y | +Z |

+ | Content Depth | X | Y | +Z |

+ | SEO | X | Y | +Z |

+ | Badges | X | Y | +Z |

+ | Visual Appeal | X | Y | +Z |

+ | Completeness | X | Y | +Z |

+ | AI Citability | X | Y | +Z |

+ | **Total** | **X** | **Y** | **+Z** |

+ ```

+ ### Deliverables

+ - Approved banner image saved to `assets/banner.webp` when requested

+ - Verified `assets/social-preview.png` and explicit upload status when requested

+ - Full README.md content with banner at top

+ - Before/after score comparison

+ - List of changes made with reasoning

+ - Keyword integration summary

+ - Image format audit: flag any existing repo images using the wrong format or >1MB

+ ### Post-Generation Image Links (REQUIRED)

+ After generating or placing ANY image (banner, social preview, screenshot), always

+ output clickable links so the user can access the file immediately:

+ 1. **Local file link:** `file:///[absolute-path]/assets/banner.webp`

+ 2. **Raw GitHub URL** (after push): `https://raw.githubusercontent.com/{owner}/{repo}/main/assets/banner.webp`

+ 3. **Social previews:** follow the agent-first upload SOP. Provide manual upload

+ steps only after a concrete tool/authentication blocker. Include the exact

+ settings URL, ready image link and honest upload status.

+ Replace all placeholders with actual values. Never output just a relative path

+ like `assets/banner.webp` without the clickable link next to it.

+ ### Next Step

+ After completing README optimization, always end with this handoff:

+ ```

+ README optimization complete. All skills have been run.

+ Recommended final step:

+ github-audit -- re-run the audit to measure your improvement and get your new score

+ Once you've completed this process for all your repos:

+ github-empire -- portfolio-level optimization (profile README, cross-linking, avatar)

+ ```

+ If running as part of the audit SOP, reference the step number:

+ "Step 6 complete. Next skill: `github-audit` to measure your improvement."

+ If this is the user's last repo in a multi-repo session, also mention:

+ "All repos optimized. When you're ready for portfolio-level work, run `github-empire`."