README Optimization: Writing READMEs That Rank in Search and AI
Your README is the single most important file for repository discoverability. It is the page Google indexes, the content AI assistants extract, and the first thing developers read when deciding whether to use your tool. Despite this, most READMEs are either empty, a single paragraph, or a wall of unstructured text. The Claude GitHub audit finds that README Quality is the category where most repositories lose the most points.
Why READMEs Matter for Search
Google treats your GitHub README page like any other web page. It evaluates heading hierarchy, keyword density in the first paragraph, content length, and structured data patterns. A README with clear H2 headings, a descriptive opening paragraph, and 500+ words of structured content will outrank a repository with identical code but a two-line README.
AI assistants including ChatGPT, Perplexity, and Google AI Overviews also extract README content when recommending tools. They favor structured, extractable content: explicit feature lists, clear installation commands, and question-format headings that match how developers phrase queries. If your README answers the question "how do I validate API requests in Express?" better than competing READMEs, AI systems are more likely to cite your repository.
The Optimal README Structure
The audit scoring rubric evaluates these elements, listed in order of impact:
H1: Project Name and Subtitle
Your H1 should be your project name. Immediately after it, include a one-sentence description that contains your primary keyword. For example: "FastValid - lightweight request validation middleware for Express and Node.js." This sentence becomes the snippet Google shows in search results and the summary AI assistants extract when mentioning your project.
Badges Row
Place badges immediately after the H1 for build status, version number, license type, and download count. Badges serve two purposes: they provide at-a-glance trust signals to developers, and they add structured metadata that automated analysis tools can parse. The /github release command generates appropriate CI badges based on your actual workflow configuration.
Description Paragraph
The first paragraph after badges is critical. Keep it to 2-3 sentences that explain what the tool does, who it is for, and what problem it solves. Include your primary and secondary keywords naturally. Avoid starting with "This is a..." or "A simple..." because these waste the most valuable real estate in your README. Lead with the benefit or capability.
Table of Contents
For READMEs longer than 300 words, include a table of contents with anchor links to each H2 section. This improves navigation for human readers and provides a structured outline that search engines and AI assistants use to understand your content hierarchy. GitHub automatically generates anchor IDs for headings, so linking is straightforward.
Features Section
Use a bulleted list of concrete features. Each bullet should be a single sentence describing a specific capability, not a vague benefit. "Validates request bodies against JSON Schema with custom error messages" is better than "Easy validation." Feature lists are the most commonly extracted content by AI assistants because they are structured, scannable, and directly answer "what does this tool do?" queries.
Installation Section
Provide copy-paste installation commands in a fenced code block. Include commands for all relevant package managers (npm, yarn, pnpm for Node.js projects). The installation section should work on its own without requiring the reader to visit another page. Developers who reach this section are ready to try your tool, and any friction at this point loses them.
Usage Examples
Include at least one complete, runnable code example that demonstrates the core use case. The example should be self-contained, meaning a developer can copy it into a new file and run it without modifications. Annotate the example with brief comments explaining each step. Usage examples are the second most commonly extracted content by AI assistants after feature lists.
API Reference or Configuration
For libraries and tools with configuration options, document them in a table or structured list. Each option should have its name, type, default value, and a one-line description. This section serves developers who have already decided to use your tool and need reference documentation.
Contributing and License
Link to your CONTRIBUTING.md file and state your license type. These are trust signals that tell developers the project is maintained and they are legally allowed to use it. The /github legal and /github community commands generate these files if they are missing.
Keyword Placement Strategy
After researching keywords with /github seo (see the keywords guide), place them in these high-impact locations:
- H1 subtitle - include the primary keyword in the sentence immediately following your project name
- First paragraph - use both primary and secondary keywords naturally within the first 160 characters
- H2 headings - use question-format headings when possible ("How to install" rather than "Installation") to match search queries
- Feature list - each bullet is an opportunity to include a related keyword naturally
- Code example comments - comments in code blocks are indexed and can include keyword-rich descriptions
Avoid keyword stuffing. One natural mention of each target keyword is enough. Google and GitHub both penalize unnatural repetition, and human readers will find it off-putting.
Content Length and Depth
The audit rubric rewards READMEs with sufficient depth to be genuinely useful. As a baseline, aim for 500-1500 words for a library or tool, and 300-800 words for a smaller utility or configuration. The word count is not a target to inflate with filler. Every sentence should provide information that helps a developer understand, install, or use your tool.
READMEs shorter than 200 words consistently score below 10 out of 25 in the README Quality category. READMEs in the 800-1200 word range with proper structure typically score 20-25.
AI Citation Patterns
To make your README content more likely to appear in AI-generated answers, follow these patterns:
- Answer-first paragraphs - start each section with the key information, then elaborate. AI systems extract the first sentence of sections more often than buried details.
- Explicit comparisons - if your tool improves on alternatives, state the comparison directly. "Validates 3x faster than express-validator by using compiled schemas" is more citable than "Fast validation."
- Concrete numbers - include specific metrics when available: bundle size, benchmark results, number of supported formats. Specificity makes content more trustworthy to AI systems.
- Self-contained sections - each H2 section should make sense on its own without requiring context from other sections. AI assistants often extract individual sections rather than the full README.
The /github readme command generates an optimized README using keyword data from /github seo and all the patterns described above. Run it as the final step in the standard operating procedure after setting up legal, community, and release files.
Common README Mistakes
- No README at all - scores 0 in the highest-weighted category
- Single paragraph with no headings - search engines and AI cannot extract structured information
- Installation instructions that require external context - "see the docs" instead of inline commands
- No code examples - developers cannot evaluate the tool without seeing how it works
- Marketing language instead of technical detail - "blazingly fast" means nothing without benchmarks
- Outdated examples - code that no longer works with the current version destroys trust