Build Chrome Extension

Build Chrome Extension

Build, debug, package, and ship Chrome Manifest V3 extensions. Optimize for restart-safe service workers, isolated content scripts, least-privilege permissions, and Web Store review readiness.

When To Use

Trigger when the request matches any of:

• creating a new Chrome MV3 extension or scaffolding from a framework (WXT, Plasmo, CRXJS, Vite)
• editing or generating manifest.json with manifest_version: 3, service_worker, content_scripts, host_permissions, action, or side_panel fields
• implementing or debugging chrome.runtime, chrome.storage, chrome.alarms, chrome.scripting, chrome.tabs, chrome.declarativeNetRequest, chrome.sidePanel, or chrome.offscreen APIs
• fixing MV3 service-worker lifecycle issues: idle termination, top-level listener registration, async onMessage returns, chrome.alarms vs setInterval
• bridging content scripts between ISOLATED and MAIN worlds, or routing fetches through the service worker for cross-origin host permissions
• migrating an MV2 extension to MV3 (background page → service worker, blocking webRequest → declarativeNetRequest, browser_action → action)
• validating a built dist/ or .output/chrome-mv3/ folder, packaging the Web Store zip, writing privacy/permission justifications, or preparing review notes
• choosing or comparing Chrome MV3 frameworks for a new project

Do NOT use this skill when:

• the target is Firefox, Safari, or a cross-browser polyfill (browser.* namespace, web-ext tooling, Safari App Extensions)
• the request is generic browser automation outside an extension context — route to run-agent-browser
• publishing a regular npm package or library — route to publish-npm-package
• building a different platform's extension surface (Raycast script command, VS Code extension, Edge enterprise-policy package) — route to that platform's skill

Pinned Defaults — Apply Before Generating Code

| Key | Default | |---|---| | Manifest target | manifest_version: 3 only; never generate MV2 | | Greenfield framework | WXT unless the repo already chose another MV3 tool | | Persistent state | chrome.storage.local; chrome.storage.session for ephemeral restart-safe state | | Background model | Event-driven service worker, listeners registered synchronously at top level | | Periodic work | chrome.alarms — never setTimeout/setInterval for background scheduling | | Network modification | chrome.declarativeNetRequest — never blocking webRequest | | Permissions | Least privilege; prefer optional_permissions and optional_host_permissions granted via chrome.permissions.request | | Loaded folder | Built output only: WXT .output/chrome-mv3-dev/ or .output/chrome-mv3/; Plasmo build/chrome-mv3-*; CRXJS/Vite dist/ | | Package preflight | Run scripts/check-mv3-manifest.sh and scripts/preflight-extension.sh against the production build before zipping |

MV3 Footguns — Keep In Working Memory

These are the failures that recur across every MV3 build. Internalize before writing code:

• Service workers idle out (~30s default). Global module-scope state disappears between events. Persist before each await and rehydrate at event entry.
• Register chrome.runtime.onMessage, onInstalled, onStartup, alarm, and tab listeners synchronously at top level. Late-registered listeners miss wake-up events.
• setTimeout/setInterval cannot keep a service worker alive and will not fire reliably across idle cycles. Use chrome.alarms.create with periodInMinutes >= 0.5.
• chrome.runtime.onMessage async handlers must return true synchronously to keep the message channel open; otherwise sendResponse throws.
• Content scripts run in an isolated world by default. The page's JS, frameworks, and window.* globals are invisible. Use world: "MAIN" only for page-JS access, then bridge with postMessage plus a same-origin token.
• Extension-origin fetch requires matching host_permissions. Content-script fetch is bound by the page's origin and CORS rules — route privileged requests through the service worker via chrome.runtime.sendMessage.
• MV3 CSP forbids inline `, eval(), new Function()`, and remote executable code. Bundle everything; no CDN-loaded scripts.
• Hand-written manifest.json paths must point at built artifacts (e.g. background.js, content.js, popup.html), never src/*.ts or unbuilt source.
• Requesting ` or broad host permissions at install time triggers Web Store review friction. Prefer activeTab` plus optional host grants.

Decision Rules

| Decision | Default | Escalate when | |---|---|---| | Background state | chrome.storage.session/local | Transactions, large indexes, binary blobs → IndexedDB | | Periodic work | chrome.alarms | Real-time stream → design reconnect + queue | | Network modification | declarativeNetRequest | Read-only observation → non-blocking webRequest | | Page data fetch | Service worker fetch with host permissions | Page origin is sufficient → content-script fetch | | Page JS access | world: "MAIN" bridge with payload validation | DOM-only access → stay in ISOLATED world | | UI state persistence | chrome.storage.session | Must survive browser restart → local or sync | | Host access | activeTab or optional host grants | Extension is non-functional without install-time host access | | Side panel vs popup | Side panel for persistent companion UI | Quick action or short form → popup | | Offscreen document | DOM/canvas/clipboard/audio/Worker from service worker | Popup/options/content script can own it → skip |

Routing Boundary

| Request shape | Action | |---|---| | "Build a Chrome extension" | Use this skill; target MV3 | | "Build for Chrome and Firefox" | Keep Chrome MV3 here; cross-browser layer is out of scope | | "Automate a website in a browser" | Route to run-agent-browser | | "Write Playwright tests for an extension" | Extension launch/load notes here; broader Playwright authoring is out of scope for this pack | | "Publish to npm" | Route to publish-npm-package | | "Submit to Chrome Web Store" | Use this skill; read references/publishing/web-store.md | | "Deploy via enterprise policy" | Out of scope unless a dedicated enterprise skill exists |

Workflow

1. Scope The Extension

Ask: "Which extension surfaces exist, which Chrome APIs are required, which permissions can be deferred to runtime?"

1. List required surfaces: popup, options, side panel, content script, service worker, offscreen document, devtools.
2. List required Chrome APIs and resulting permissions.
3. Split install-time vs optional_permissions/optional_host_permissions.
4. Choose the framework — see references/frameworks/comparison.md.
5. Record the built-output folder Chrome will load.

2. Scaffold Or Adapt

Ask: "Greenfield, existing framework build, or hand-written manifest?"

• Greenfield default: WXT.
• Existing Vite app becoming an extension: CRXJS.
• Custom build pipeline / explicit control: vanilla + Vite.
• Existing repo: follow its framework and output conventions.

Chrome must load the built output folder, never src/ or unbundled TypeScript.

3. Implement Extension Contexts

Ask: "Which context owns the state, which owns the DOM, which messages cross the boundary?"

Read the matching reference before writing code:

• Service worker lifecycle, persistence, alarms, offscreen → references/patterns/service-worker.md
• Content scripts, world isolation, idempotency, cross-origin routing → references/patterns/content-scripts.md
• Popup, options, side panel, devtools, new-tab surfaces → references/patterns/ui-surfaces.md
• One-time messages, ports, external/native messaging, page bridges → references/apis/messaging.md
• chrome.storage areas, quotas, typed wrappers, migrations → references/apis/storage.md
• Tabs, scripting, alarms, DNR, side panel, offscreen, runtime → references/apis/core-apis.md
• Manifest, permission, and MV2 migration decisions are covered by the pinned defaults and guardrails in this SKILL.md.

Validate every cross-boundary payload: messages, storage reads, external API responses, MAIN-world bridge data.

4. Validate Built Output

Ask: "Can Chrome load this exact folder, and do all manifest paths exist there?"

Run from the skill directory against your build folder:

scripts/check-mv3-manifest.sh dist
scripts/preflight-extension.sh dist

Adjust the path per framework:

| Framework | Dev output | Production output | |---|---|---| | WXT | .output/chrome-mv3-dev/ | .output/chrome-mv3/ | | Plasmo | build/chrome-mv3-dev/ | build/chrome-mv3-prod/ | | CRXJS | dist/ | dist/ | | Vanilla Vite | dist/ | dist/ |

Read scripts/check-mv3-manifest.md and scripts/preflight-extension.md before modifying either script.

5. Test Extension Behavior

Ask: "What failure only appears once Chrome loads the extension?"

• Unit-test pure logic and message/storage helpers; mock chrome.* only at boundaries.
• Manually load the built output via chrome://extensions → "Load unpacked".
• Inspect the service worker from the extensions page; trigger an idle/wake cycle.
• Test content-script injection on allowed and disallowed URLs.
• Verify the runtime permission request UX (chrome.permissions.request) before the host call.

Read references/testing/testing-guide.md for extension-specific tests and references/testing/debugging.md for service-worker, popup, content-script, permission, and storage debugging.

6. Package For Web Store Review

Ask: "Could a reviewer state the single purpose, each permission's need, the data use, and the remote-code posture in one sentence each?"

1. Build production output.
2. Run both bundled scripts against that production build.
3. Strip junk before zipping: source maps (unless intentionally shipped), tests, .DS_Store, __MACOSX, framework caches.
4. Create the zip from inside the built-output folder (so manifest.json sits at the zip root).
5. Prepare: privacy practices, per-permission justification, remote-code disclosure, data-use certification, reviewer test instructions.
6. Read references/publishing/web-store.md before submission.

Minimal Build Evidence

Match evidence to the task before stopping:

| Task | Evidence | |---|---| | New scaffold | Built-output path + check-mv3-manifest.sh result | | Feature change | Relevant unit/integration test + manual-load note when Chrome behavior changed | | Manifest/permission change | check-mv3-manifest.sh result + permission justification | | Content-script change | Allowed-URL injection result + disallowed-URL injection result | | Service-worker change | Restart-resilience note OR explicit "not exercised" caveat | | Package/Web Store work | preflight-extension.sh result + zip path + reviewer notes |

Output Contract

Final reports include:

• loaded build directory
• zip path (when packaged)
• Chrome version used for manual load (when manually tested)
• summary of permissions and host-permissions justification
• Web Store policy posture: single purpose, data use, remote code, MV3 compliance
• scripts/tests run, including failures
• reviewer notes for remaining manual checks

Guardrails

• Never generate or preserve Manifest V2 for new work.
• Never load src/ in Chrome unless the framework explicitly emits loadable code there.
• Never hold durable state in module-scope globals inside the service worker.
• Never rely on setTimeout/setInterval to keep the service worker alive.
• Never use blocking webRequest for normal MV3 network modification.
• Never request `` without a feature-level justification and a documented narrower alternative.
• Never expose arbitrary background fetch through unauthenticated content-script messages.
• Never ship remote executable code or undeclared remote-code behavior.
• Always validate built-output paths against manifest.json before claiming done.
• Always make each permission explainable in one sentence.

Bottom Line

MV3 punishes the same mistakes repeatedly: lost service-worker state, late-registered listeners, timer-based scheduling, isolated-world surprises, over-broad permissions, and shipping src/ instead of built output. Apply the pinned defaults, route to references for depth, run the bundled scripts against the built folder, and produce review-ready evidence.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yigitkonur
• Source: yigitkonur/skills-by-yigitkonur
• License: MIT

Install and usage instructions live in the source repository linked above.