feat: add codebase landing copy skill

README.md

@@ -9,10 +9,10 @@ Reusable agent plugins and skills following AGENTS/skills conventions.
 
 ## Plugins
 
-| Plugin                        | Description                                                                                                                      |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| [vault](./vault/)             | Zettelkasten-style vault workflows for Obsidian notes                                                                            |
-| [development](./development/) | Agent context, PR fixups, CLI design, OSS readiness and marketing, session log audits, decision records, and self-hosted runners |
+| Plugin                        | Description                                                                                                                                                      |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [vault](./vault/)             | Zettelkasten-style vault workflows for Obsidian notes                                                                                                            |
+| [development](./development/) | Agent context, PR fixups, CLI design, codebase-grounded landing copy, OSS readiness and marketing, session log audits, decision records, and self-hosted runners |
 
 ## Layout
 

development/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "development",
-  "version": "0.0.5",
-  "description": "Developer workflow skills for agent context, PR fixups, CLI design, OSS readiness, OSS marketing, session log audits, decision records, and GitHub Actions self-hosted runners.",
+  "version": "0.0.6",
+  "description": "Developer workflow skills for agent context, PR fixups, CLI design, codebase-grounded landing copy, OSS readiness, OSS marketing, session log audits, decision records, and GitHub Actions self-hosted runners.",
   "author": {
     "name": "Mark Phelps"
   },
@@ -15,6 +15,10 @@
     "AGENTS.md",
     "cli",
     "command-line",
+    "landing-page",
+    "homepage",
+    "product-marketing",
+    "evidence",
     "open-source",
     "oss",
     "readme",
@@ -38,8 +42,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Development",
-    "shortDescription": "Agent context, PR fixup, CLI design, OSS readiness, OSS marketing, session log audit, decision records, and self-hosted runner workflows",
-    "longDescription": "Development workflow skills for auditing agent context files, fixing existing GitHub PRs, designing humane command-line interfaces, preparing GitHub repos for open source release, sharpening OSS README positioning, mining local agent session logs for papercuts in your own tools, writing and maintaining decision and plan records (ADRs), and running GitHub Actions self-hosted runners on a Linux host.",
+    "shortDescription": "Agent context, PR fixup, CLI design, codebase-grounded landing copy, OSS readiness, OSS marketing, session log audit, decision records, and self-hosted runner workflows",
+    "longDescription": "Development workflow skills for auditing agent context files, fixing existing GitHub PRs, designing humane command-line interfaces, writing product landing-page copy backed by shipped code, preparing GitHub repos for open source release, sharpening OSS README positioning, mining local agent session logs for papercuts in your own tools, writing and maintaining decision and plan records (ADRs), and running GitHub Actions self-hosted runners on a Linux host.",
     "developerName": "Mark Phelps",
     "category": "Development",
     "capabilities": ["Read", "Write"],
@@ -49,6 +53,8 @@
       "Create a concise AGENTS.md for this repo based on its actual tooling and structure.",
       "Review this CLI against clig.dev and suggest concrete improvements.",
       "Design commands, flags, help text, and output behavior for a new command-line tool.",
+      "Write landing-page copy for this product using only capabilities proven by its codebase.",
+      "Fact-check this product pitch against the code that actually ships and provide an evidence table.",
       "Audit this repo for open source readiness and first-contributor friction.",
       "Prepare README, CONTRIBUTING, issue templates, and PR templates for an OSS launch.",
       "Run an OSS marketing pass on this README so first-time visitors understand why to try it.",

development/AGENTS.md

@@ -18,6 +18,8 @@ agent context.
 
 - `cli-design`: design, build, or review command-line interfaces using the
   Command Line Interface Guidelines from clig.dev
+- `codebase-landing-copy`: write product landing-page copy grounded in
+  capabilities that are proven by shipped code
 - `context-file-tuneup`: audit and rewrite `CLAUDE.md` / `AGENTS.md` files so
   they stay short, specific, and grounded in the repo
 - `decision-records`: write or update decision and implementation-plan records

development/README.md

@@ -1,15 +1,16 @@
 # Development Plugin
 
 Developer workflow skills for repo-facing agent context, GitHub PR follow-up,
-command-line interface design, open source release preparation, audits of your
-own agent session logs, decision records, and GitHub Actions self-hosted
-runners.
+command-line interface design, codebase-grounded landing copy, open source
+release preparation, audits of your own agent session logs, decision records,
+and GitHub Actions self-hosted runners.
 
 ## Skill Set
 
 | Skill                       | What It Does                                                                                             | When to Invoke                                                                                                                              |
 | --------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `cli-design`                | Designs and reviews command-line interfaces using clig.dev guidance.                                     | When creating CLI commands, flags, help text, output contracts, error messages, or destructive workflows.                                   |
+| `codebase-landing-copy`     | Writes product landing-page copy grounded in shipped code and an evidence ledger.                        | When writing or fact-checking landing pages, homepages, product pitches, hero copy, or store listings for a repo-backed product.            |
 | `context-file-tuneup`       | Audits, rewrites, and tightens `CLAUDE.md` / `AGENTS.md` context files.                                  | When reviewing, shrinking, restructuring, or improving agent context.                                                                       |
 | `decision-records`          | Writes and maintains decision and plan records (ADRs) and their registry table, preserving history.      | When recording an architecture, product, design, or dependency decision, amending or superseding a record, or starting a records directory. |
 | `github-pr-fixup`           | Addresses unresolved GitHub PR review comments and failing CI on the existing source branch.             | When a user gives you an existing PR URL and wants review feedback or CI failures fixed without a new PR.                                   |
@@ -34,6 +35,8 @@ runners.
   of opening a new PR.
 - OSS readiness and OSS marketing are separate concerns. Readiness covers
   contribution mechanics; marketing covers first-visit clarity and conversion.
+- Codebase landing copy is for a product's own landing page and must trace
+  claims to shipped code; use OSS marketing for open-source README positioning.
 - Session log audits need a project the user built with agents and used
   recently. Every finding must carry a dated receipt from a real session.
 - Decision records are historical evidence. Preserve IDs, filenames, and past

development/skills/codebase-landing-copy/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: codebase-landing-copy
+description:
+  Write or improve landing-page marketing copy for a product by reading its
+  codebase, so every claim is backed by code that actually ships. Produces a
+  scannable page (hero, how it works, features, who it's for) that lets a
+  first-time visitor understand the product in under 10 seconds, plus an
+  evidence table mapping each claim to the file that proves it. Use this
+  whenever the user wants landing page copy, homepage copy, a product pitch, a
+  hero section, feature bullets, a "what is this" blurb, or App Store / Product
+  Hunt listing copy, or asks to rewrite, tighten, or fact-check existing
+  marketing copy for an app, CLI, library, or SaaS whose source code is
+  available, even if they don't say "landing page." Also use when the user asks
+  "is my site overselling?" or "what does this product actually do?" for a repo.
+  For an open source repo's README positioning, use oss-marketing instead.
+---
+
+# 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).