Building with AI agents

The kit ships tested surfaces for coding agents: six prompt recipes, a shared instructions file, machine-readable docs, and an MCP preset for debugging in a live Chrome.

The recipes

Six tested recipes live in .claude/commands/*.md. Each encodes the kit’s real invariants: exact file paths, the policy guard, the definition of done. An agent that runs it lands green instead of rediscovering MV3 the hard way.

Recipe	What it does
/add-feature	Scaffold a feature off YourFeature.tsx, including gateAction/gateFeature wiring and the 2-file paywall recipe.
/add-surface	Add a WXT entrypoint (a popup-style page or a content script) following the shadow-UI and module conventions.
/change-gate-preset	Switch paywall timing presets in background/gates.ts with the Chrome Web Store policy guard restated.
/add-permission	Add a chrome.* permission the safe way: manifest + module.json rationale + e2e guard, permission-before-code.
/prep-store-submission	Pre-flight a store submission: zips, remote-code audit, store assets, privacy-disclosure answers.
/add-migration	Change a chrome.storage shape with a numbered defineMigrations bump and tests.

In Claude Code they’re picked up automatically as slash commands. Open a session at the repo root and type:

/add-feature summarize-page

In Cursor (or any other agent), each file is a self-contained prompt. Open .claude/commands/<recipe>.md, paste the body into chat, and replace $ARGUMENTS with your specifics.

What else ships

• AGENTS.md: the single source of agent instructions: the architecture map, the verified MV3 pitfalls, the gate policy guard, and the security invariants. CLAUDE.md and .cursor/rules/ are symlinks to it, so Claude Code, Cursor, and anything AGENTS.md-aware read the same file.
• llms.txt + markdown mirror: this docs site publishes /llms.txt and every page as plain markdown, so agents can fetch any guide by URL.
• Docs bundle: one concatenated markdown file (and a zip of the individual pages) for pasting the whole docs set into a context window.

Debugging with Chrome DevTools MCP

The repo ships a project-scope MCP preset in .mcp.json for Google’s chrome-devtools-mcp server, which lets an agent drive and inspect a live Chrome. The agent can see the failure instead of guessing: read service-worker console output and manifest errors, screenshot the popup or welcome page, watch the background’s network calls, and click through a gate wall to verify timing.

Claude Code detects .mcp.json at the repo root automatically; it asks for approval on first use, nothing else to configure. Or add it explicitly:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

Cursor: add the same server in Cursor Settings → MCP, using the identical config shape:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Useful variants (append to args): --isolated for a throwaway profile, or --browser-url http://127.0.0.1:9222 to attach to a Chrome you started yourself with your unpacked extension already loaded (usually what you want for extension debugging, paired with pnpm dev).

Guardrails: agents don’t get a pass

Everything in AGENTS.md binds agent-written code exactly as it binds yours. The failure modes agents hit most are the MV3 service-worker rules and hand-writing paywall UI instead of using the gate engine. Review agent diffs against the pitfalls anyway.

The definition of done is the same for agents as for humans. From the repo root:

pnpm typecheck && pnpm lint && pnpm turbo run test
pnpm --filter @extensionstart/extension e2e

Don’t let an agent declare victory without the e2e run.