Repo geo

repo-geo

Make a repository accurately findable and citable by AI search systems. Audit first, report, get confirmation, then edit.

Core principle

Every change must make it easier for a model to accurately understand what already exists. Never add content that restates information already on the page. If a proposed change does not add new information, drop it. Ranking tricks, padding, and score-chasing are out of scope and actively harmful.

Workflow

Run these phases in order. Do not skip to editing.

Phase 1 — Detect repo type

Inspect the repo root and classify into exactly one of:

• backend — no site output. Signals: pyproject.toml, go.mod, Cargo.toml, package.json without a bundler/framework, presence of openapi.* / main.go / src/lib, absence of index.html / public/.
• fullstack — both. Signals: next.config.*, nuxt.config.*, remix.config.*, or a web/ + server/ split, or package.json with both a server framework and a UI framework.
• frontend — site or client app. Signals: index.html, public/, dist/, vite.config.*, static site generators (Hugo, Astro, Docusaurus, VitePress).

State the classification and the evidence you used before continuing. If ambiguous, ask.

Also determine: is there a published site (a domain this repo deploys to)? Site-level items only apply if yes. Read references/repo-types.md for the per-type action table.

Phase 2 — Audit (read-only)

Run the audit script:

python3 scripts/audit.py <repo-path>

For multiple repos, pass several paths — it emits a per-repo result plus a summary table.

The script emits JSON. It handles the mechanical checks (file presence, word counts, metadata fields, spec conformance). You must handle the judgment calls yourself by reading the files: whether the README opening is a genuine quotable definition, whether comparison content is substantive, whether an existing FAQ is padding. The script flags candidates; you decide.

Do not modify anything in this phase.

Phase 3 — Report

Present a table: check / status (OK, WEAK, MISSING) / where / what to do. Then a recommendation list sorted by value-to-effort, split into:

• A — this skill can do it (files in the repo)
• B — you must do it (GitHub web settings, Search Console, Bing Webmaster Tools, package registry pages)

Include a realistic expectation note (see references/evidence.md, "Expectation management"). Do not oversell.

Phase 4 — Confirm

Ask which A-items to apply. Default-select the high-value ones. Two decisions always need an explicit answer:

1. Training crawlers (GPTBot, CCBot, Meta-ExternalAgent) — default is block, but this is the user's call, never yours. Blocking them does not affect AI search results; it only keeps content out of training data.
2. Deletions — if the audit flagged padding (a redundant FAQ, a restated section), propose removal explicitly and get a yes.

Phase 5 — Apply

Rules:

• Never overwrite human-written prose. Augment, or generate only where the file is absent.
• One file at a time. Use templates in templates/ as a starting structure, not as literal output — fill them with facts read from the actual repo.
• Facts must come from the repo (real version numbers, real install commands, real benchmarks). Never invent numbers.
• Do not touch anything in references/dont-do.md.

Phase 6 — Verify

• git diff --stat, and walk through the diff with the user.
• Validate any generated llms.txt against the spec: required H1, blockquote summary, H2 sections containing only link lists.
• Check every generated link resolves.
• Re-read generated prose once, asking of each paragraph: does this say something not already said elsewhere? Delete it if not.

What good looks like

README opening. The first ~200 characters should be a self-contained definition a model can lift verbatim: what it is, what category, what it does. Pake is a Rust-based CLI that turns any webpage into a lightweight desktop app — not A cool little tool I built on weekends.

Specificity over generality. Pages with real data, clear definitions, and side-by-side comparison have >50% more measured influence than vague ones. Version numbers, sizes, benchmarks, explicit "unlike X, this does Y".

Length. High-citation pages average ~2000 words with 10+ headings; low-influence pages average 170 words. Target 1000–3000 words for a core doc page. But length must come from substance, never padding.

Natural-language URLs. /projects/pake tells a model what the page is before it reads a line. /page?id=47 says nothing.

English. Over 83% of global citation samples are English. An international project needs an English README, even if the primary one is Chinese.

Per-topic pages. Split a monolithic README into docs/ pages, each self-contained with a quotable summary, features, comparison, use cases, install command.

Reference files

• references/crawlers.md — crawler taxonomy and robots.txt policy
• references/evidence.md — what the research supports, and expectation management
• references/dont-do.md — hard constraints, read before editing
• references/repo-types.md — per-type action table

Templates

templates/ holds starting structures for llms.txt, llms-full.txt, robots.txt, a README skeleton, and a per-project knowledge page. Read the relevant one before generating that file.