Building Chrome Extension

We built the Building Chrome Extension skill because we saw too many engineers drowning in browser extension documentation. You're a working developer. You want to build a tool that lives in the browser toolbar, injects scripts, or modifies page content. Instead of shipping, you spend days debugging why your background script dies, why manifest.json rejects your build, or why the Chrome Web Store rejects your ZIP.

The browser extension landscape shifted hard with Manifest V3. The old background page model is gone. Service workers have a strict lifecycle. Content Security Policy (CSP) blocks inline scripts. Permissions are granular. If you treat extension development like standard web development, you'll fail. We created this skill to give you the exact toolchain, validation, and architectural guidance you need to ship extensions without the head-scratching.

The MV3 Migration Trap and Manifest Nightmares

You start a new extension. You create manifest.json. You think you're done. You load the folder into chrome://extensions in Developer Mode. Nothing happens. The browser logs a validation error. You check the schema. You missed action. You added browser_action instead. In MV3, browser_action and page_action are deprecated in favor of action ^[1]. You fix that. You reload. Now your popup is blank. You realize you forgot web_accessible_resources to serve the popup HTML. You add it. Now your content script can't talk to the background. You try chrome.runtime.sendMessage, but the service worker terminated before the message arrived.

This isn't just configuration trivia. The manifest.json file is the only file that every extension using WebExtension APIs must contain ^[4]. It defines your permissions, your entry points, your CSP, and your resource mappings. One wrong field and the extension is dead in the water. An extension consists of a collection of files, packaged for distribution and installation ^[5]. But the packaging is trivial compared to the architecture. You need to understand how the service worker lifecycle works, how chrome.scripting differs from chrome.tabs, and how to structure your build so Vite generates the correct service worker entry point.

If you're coming from a standard web stack, you might assume you can just spin up a Vite project and point it at the extension. You can't. The extension context has restrictions. You can't use fetch to arbitrary origins without host_permissions. You can't use inline event handlers. You can't load remote code. These aren't suggestions; they're enforced by the browser. Without a validated manifest and a pre-configured build pipeline, you're guessing. And guessing costs time.

Why "Just Add a Popup" Costs You Days of Rework

Every hour you spend debugging content_security_policy or web_accessible_resources is an hour you aren't shipping features. The cost of getting this wrong isn't just frustration; it's lost credibility and delayed releases.

When you submit an extension to the Chrome Web Store, the review process is automated and strict. If your manifest lacks required fields, or if your service worker crashes on load, your submission gets rejected. Rejections trigger a manual review queue that can take days. You lose momentum. Your internal stakeholders see you as "that dev who can't ship the tool." Your users see a broken icon in their toolbar.

The complexity multiplies if you're migrating from Manifest V2. Many organizations still maintain legacy extensions. You end up supporting two codebases. The MV2 codebase uses a persistent background page. The MV3 codebase uses a stateless service worker. You have to rewrite your state management. You have to migrate from webRequest to declarative_net_request. You have to audit every content script for CSP violations. This migration debt can easily consume weeks of engineering time.

You might be tempted to solve the problem with a different technology. If you just need offline capabilities, you could look at building a PWA from an existing site. But a PWA doesn't give you access to chrome.tabs, chrome.storage.local, or the ability to inject content scripts into third-party pages. If you need browser integration, you need an extension. If you try to hack around MV3 limitations with a background page, you'll hit the 30-second timeout and your extension will silently fail for power users. The WebExtensions glossary clarifies that these APIs are cross-browser, but the implementation details vary. You need a skill that handles the Chrome-specific quirks so you can focus on the logic.

How a Compliance Tool Team Lost 40 Hours to Service Worker Lifecycle

Imagine a team building a security scanner for a corporate intranet. They need to inject a script into 50 internal domains to check for missing headers. They start with a popup-based extension. They write the content script. They test it on http://intranet.corp. It works. They feel good.

They try to scan a subpage: http://intranet.corp/deep/path. The content script fails. They realize they only granted activeTab permission. They switch to host_permissions with a wildcard. Now it works on the subpage. They celebrate. They add a feature to block trackers using declarative_net_request. They misconfigure the rule set. Their extension breaks the login flow for the HR portal. The team spends two days debugging why the login form won't submit. They realize the rule was too broad and was blocking the POST request.

They try to fix the state management. They store scan results in chrome.storage.local. They realize the service worker terminated between scans. The data is lost. They try to keep the service worker alive with a heartbeat, but that's a hack and violates best practices. They need to restructure their data flow to be stateless or use chrome.storage.sync with proper persistence.

The team checks the JavaScript APIs documentation to see how to interact with the browser, but the extension context is different from a Node.js script or a VS Code extension. The messaging protocol is asynchronous. The error handling is different. They find the MDN examples showing a working pattern, but adapting them to their specific corporate constraints takes another week. A similar struggle happens when teams try to build an Electron desktop app for the same problem—Electron gives you a full Chromium instance, but you lose the seamless browser integration and the ability to run in the background without a window. The extension team eventually fixes it, but they burned 40 hours on configuration errors that a validated manifest and a clear service worker guide would have prevented.

What Changes When Your Extension Builds Clean on First Try

Once you install this skill, the friction disappears. You're no longer guessing about MV3 requirements. You have a validated pipeline that catches errors before they reach the browser.

You run validators/validate-manifest.sh and jq enforces MV3 compliance. It checks for required fields, validates permission arrays, and ensures your service worker references are CSP-compatible. It exits non-zero on failure, so you can't commit a broken manifest. Your templates/vite.config.ts is pre-wired with vite-plugin-web-extension. The manifest is injected automatically. The build target is set correctly. Watch mode works as expected. You don't have to manually edit the manifest after every change.

The scripts/build-and-package.sh script automates the entire workflow. It installs dependencies, runs the production build, and packages the extension into a distributable ZIP using web-ext. You go from code to ZIP in seconds. The references/mv3-core-concepts.md file serves as your canonical guide. It covers the architectural shifts: service workers, CSP restrictions, chrome.scripting API, declarative_net_request, and web_accessible_resources rules. You don't have to memorize the docs. You just open the reference and follow the pattern.

Errors are caught at build time. You know exactly how to structure your popup, background, and content scripts. You can ship extensions that pass review on the first attempt. You save weeks of debugging and migration time. You focus on the features your users actually need.

What's in the Building Chrome Extension Pack

This is a multi-file deliverable. Every file is designed to work together to eliminate the guesswork from MV3 development.

• skill.md — Orchestrator skill guide detailing the MV3 development lifecycle, toolchain selection, and cross-references to all templates, validators, and references.
• templates/manifest.json — Production-grade Manifest V3 schema with all required fields, permissions, action/background setup, and web_accessible_resources configuration.
• templates/vite.config.ts — Vite configuration optimized for MV3 extensions using vite-plugin-web-extension, including manifest injection, build targets, and watch mode.
• scripts/build-and-package.sh — Executable shell script that automates dependency installation, production build, and web-ext packaging into a distributable ZIP.
• validators/validate-manifest.sh — Programmatic validator using jq to enforce MV3 compliance, checking required fields, permission arrays, and CSP-compatible service worker references. Exits non-zero on failure.
• references/mv3-core-concepts.md — Canonical reference covering MV3 architectural shifts: service workers, content security policy restrictions, chrome.scripting API, declarative_net_request, and web_accessible_resources rules.
• references/web-ext-workflow.md — Canonical reference detailing web-ext CLI and API usage for building, running, watching, and signing extensions for distribution platforms.
• examples/worked-popup-extension.md — Step-by-step worked example for a popup-based extension, including file structure, UI code, background script, and testing instructions.

Ship Your First Pro Extension Today

Stop wrestling with MV3 quirks. Start shipping tools your users actually install. Upgrade to Pro to install the Building Chrome Extension skill and get the validated manifest, build pipeline, and architectural guidance you need to ship extensions without the head-scratching.