codebase-landing-copy

# Codebase → Landing Page Copy Landing copy fails in two opposite ways: it's vague ("the modern platform for teams") so nobody gets what the product is, or it's aspirational ("AI-powered insights") and promises things the code doesn't do. This skill avoids both by treating the codebase as the source of truth and the visitor's first 10 seconds as the target. The code decides _what_ can be said; marketing craft decides _how_ it's said. ## The one hard rule **Every product claim must trace to code that ships to users.** You can rephrase, compress, reorder, and dramatize — you cannot add capabilities. If you can't point to the file, function, route, config option, or UI string that makes a claim true, the claim doesn't go on the page. This matters because a landing page is a promise. An invented feature costs the maintainer a trust hit (or a refund, or an angry issue) the first time a user looks for it. Being precise here is what makes the copy safe to publish without a second review pass. What counts as evidence, and what doesn't — see `references/evidence.md` before starting the audit. The short version: - ✅ Shipped: reachable code paths, registered routes/commands/menu items, UI strings, public API exports, documented config options wired into behavior, integrations with real client code. - ❌ Not shipped: TODO/FIXME, stubs that throw "not implemented", code behind a flag that defaults off, test-only fixtures, dead code with no caller, roadmap sections in the README, open issues, branch names, commented-out code. - ⚠️ Ambiguous (ask the user): beta flags, experimental modules, features gated to a paid tier, anything that's wired up but looks unfinished. ## Scope This skill writes copy for a product's own landing page, homepage, or store listing. For positioning an open source repo's README (Show HN launch, star conversion, comparison tables), use `oss-marketing`. The evidence ledger below still applies if you are asked to fact-check README claims. ## Workflow ### 1. Orient (read, don't write yet) Figure out what kind of product this is and who uses it. Look at, roughly in this order: 1. README, package manifest (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Package.swift`, `*.xcodeproj`), and any existing landing page / marketing site in the repo (`site/`, `www/`, `docs/`, `landing/`). 2. **Entry points** — what a user actually touches: CLI command definitions, HTTP routes, UI views/screens, menu items, public exports, onboarding flow. 3. **User-facing strings** — button labels, empty states, onboarding copy, settings labels, error messages. These are gold: they're already written in the product's voice and they prove the feature exists. 4. Integrations — HTTP clients, SDK imports, auth providers, file formats read/written. 5. Config/settings schema — each user-facing option is a capability. Don't read the whole repo. Follow entry points outward until you can answer: _what does a user do with this, and what happens?_ If the user supplied existing copy to improve, read it now too — you'll fact-check it in step 2. ### 2. Build the evidence ledger Write a working list of candidate claims, each with its proof. This is the backbone; the copy is written from it, not from memory. ``` | Claim (plain language) | Evidence | Status | |-----------------------------------------|--------------------------------------------|----------| | Summarizes articles with a local model | Sources/Summarizer.swift: summarize() | shipped | | Imports OPML | Sources/Import/OPMLImporter.swift | shipped | | Syncs across devices | README roadmap only | NOT SHIPPED | | Team workspaces | flag `teams_enabled` defaults false | ASK | ``` For **improving existing copy**: add every claim from the current page to the ledger and mark it. Unbacked claims in existing copy are the most valuable thing you'll find — surface them prominently rather than silently dropping them. Also note concrete, countable facts the code supports (number of integrations, supported formats, platforms, "no account required" if there's genuinely no auth). Specifics beat adjectives. Only use numbers you counted; never estimate performance, speed, or scale unless there's a benchmark in the repo — and cite it. ### 3. Find the one-sentence answer Before writing sections, write the sentence a visitor should walk away with: > **[Product] is a [category the visitor already knows] that [does the core job] > for [who].** Pick the core job by asking: if the product did only one thing, what would it be? That's usually the path the entry points converge on. Everything else is a supporting feature. Use a category the visitor already has a mental slot for ("an RSS reader", "a feature flag service", "a menu bar app") — novelty in category naming costs the visitor seconds they won't spend. ### 4. Write the copy Structure, top to bottom. Every section is optional except the hero; drop any section you can't fill with backed claims rather than padding it. **Hero (the 10-second zone)** — this alone must answer _what is it, who's it for, why care_. - **Headline** (≤ 10 words): the outcome or core job. Concrete verbs, no "revolutionize/supercharge/unlock/seamless/next-gen". - **Subhead** (1 sentence, ≤ 25 words): the one-sentence answer from step 3, made specific. - **Primary CTA**: the actual first action the product supports (Download for macOS / `brew install x` / Start free / Get the CLI). Pull the install command from the repo, don't invent one. - Optional: 3 proof bullets directly under the subhead — the three strongest shipped capabilities. **How it works** (3 steps max) — the real user flow from the entry points: e.g. _Connect → Configure → Get X_. Each step is a short bold label + one line. **Features** — 4–8 items. Each is: - a bold benefit-first label (3–6 words), then - one line saying what it does, concretely. Lead with the user's outcome, then the mechanism: "**Catch up in minutes** — Every article gets a short summary, generated on your Mac." Order by what a new visitor cares about most, not by code structure. **Who it's for** — only if the code or README signals a clear audience. 2–3 bullets. **Details / FAQ** — for real differentiators the code proves: open source (license file), self-hosted, offline, privacy (no network calls / no telemetry — verify!), platform support, pricing tier gating. Privacy and "no telemetry" claims especially need a real check of network code. **Closing CTA** — repeat the primary CTA. ### 5. Style rules for skimmability - Short paragraphs: 1–2 sentences, never more than 3. - Bullets over prose for anything list-shaped. Bold the first few words of each bullet so a skimmer reading only bold text still gets the pitch. - Plain words over jargon; product-specific terms only if the visitor must learn them to use the product. - Second person ("you"), active voice, present tense. - Cut every sentence that would be equally true of a competitor. - No superlatives you can't prove ("fastest", "best", "most secure"). - Match tone to the audience: dev tools are terse and code-forward (show a command); consumer apps are warmer and outcome-first. ### 6. Self-check before delivering Run these checks and fix failures before showing the user: 1. **10-second test**: read only the headline + subhead. Could a stranger say what it is and who it's for? If not, rewrite them. 2. **Bold-only test**: read only the bolded text top to bottom. Does it tell the story? 3. **Evidence test**: every claim on the page has a row in the ledger marked shipped. Nothing marked NOT SHIPPED or ASK appears in the copy. 4. **Swap test**: replace the product name with a competitor's. Any sentence that still reads true is filler — sharpen or cut it. ## Output format Deliver in this order: 1. **The copy** — as Markdown, ready to paste, using the section structure above. If the user has a site in the repo (HTML/JSX/MDX), offer to write it into their actual files, preserving their component structure. 2. **Evidence table** — every claim on the page → file/symbol that backs it. Keep it compact; this is what lets the user trust the copy without re-reading the code. 3. **Left out** — capabilities found but excluded, with the reason (not shipped / flagged off / ambiguous). For ASK items, ask the user to confirm in one list rather than one question at a time. 4. **Existing-copy corrections** (only when improving a page) — claims on the current page that the code doesn't support, with what the code actually does. 5. Optionally, 2–3 alternate headlines with a one-line note on the angle each takes. ## Example Input: a Swift macOS RSS reader repo with OPML import, per-article AI summaries via a local model, keyboard shortcuts, and a README "Roadmap: iCloud sync". Good hero: > # Read less. Know more. > > Cove is an RSS reader for Mac that summarizes every article with an AI model > running on your machine. > > - **Summaries on every article**, generated locally > - **Bring your feeds** — import any OPML file > - **Keyboard-first** — triage your inbox without the mouse Not allowed: "Sync across all your devices" (roadmap only), "Lightning-fast" (no benchmark), "Smart recommendations" (no code).