# Repo Geo

> Audit and optimize a code repository for AI/LLM discoverability (GEO). Use when the user asks to make a repo discoverable by AI, mentions GEO, llms.txt, AI visibility, "让 AI 搜到我的项目", "给这个仓库做 GEO", AI SEO for a project, or wants README/docs structured so ChatGPT, Claude, and Perplexity cite it accurately. Works on backend-only, frontend-only, and full-stack repos.

- Skill: `bazingaorg/repo-geo` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add bazingaorg/repo-geo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bazingaorg/repo-geo/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: BazingaOrg (https://skillmd.com/u/bazingaorg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bazingaorg/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:

```bash
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.