playbooks

home / skills / xenitv1 / claude-code-maestro / browser-extension

browser-extension skill

/skills/browser-extension

This skill helps you craft Manifest V3 browser extensions with robust persistence, security, and cross-browser compatibility.

npx playbooks add skill xenitv1/claude-code-maestro --skill browser-extension

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
4.6 KB
---
name: browser-extension
description: Master specialized skill for building 2025/2026-grade browser extensions. Deep expertise in Manifest v3, Service Worker persistence (Alarms, Offscreen API), Side Panel API, and Cross-Browser compatibility.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---
<domain_overview>
# 🌐 BROWSER EXTENSION: THE 2026 MASTERCLASS
> **Philosophy:** Extensions are ephemeral, restricted, yet powerful. Persistence is an Art. Security is a Mandate. 
> **Design Constraint:** For UI/UX, Aesthetics, and Layout, YOU MUST REFER TO THE `frontend-design` SKILL.
**PERSISTENCE PARADOX GUARD (CRITICAL):** Never rely on global variables or in-memory state in background scripts. AI-generated code frequently fails by assuming Manifest V3 service workers are persistent. They are NOT; they terminate after 30 seconds of inactivity. You MUST backup every piece of state to `chrome.storage` or `IndexedDB` immediately upon change. This skill aims to eliminate "volatile-state" bugs typical of generic AI implementations. If data is not in durable storage, it does not exist.
</domain_overview>
<manifest_architecture>
## 🏗️ PROTOCOL 1: THE MANIFEST V3 CONSTITUTION
All extensions must be built on Manifest v3. No exceptions.
1. **Manifest Blueprint:**
    *   **Service Workers:** No persistent background pages. Use `"background": { "service_worker": "background.js" }`.
    *   **No Remote Code:** All scripts must be local. `unsafe-eval` is forbidden.
    *   **Permissions:** Principle of Least Privilege. Use `optional_permissions` where possible.
    *   **Action UI:** Prefer `action` over `browser_action` or `page_action`.
2. **Side Panel Supremacy:**
    *   Requirement: Use `chrome.sidePanel` for persistent, non-intrusive experiences.
    *   API: `chrome.sidePanel.setOptions({ path: 'sidepanel.html', enabled: true })`.
</manifest_architecture>
<persistence_engine>
## ⚡ PROTOCOL 2: THE PERSISTENCE ENGINE (ANTI-TERMINATION)
Service Workers sleep. You must keep the logic alive.
1. **The Alarm Pulse:**
    *   Use `chrome.alarms` to wake up the Service Worker every 1-5 minutes for background sync.
2. **The Offscreen Document (When needed):**
    *   Use the `offscreen` API for tasks like DOM parsing, heavy calculations, or keeping the SW alive via periodic messaging.
3. **State Management Protocol:**
    *   **NEVER** rely on global variables.
    *   **Mandatory:** Use `chrome.storage.session` for transient session-only secrets.
    *   **Mandatory:** Use `IndexedDB` or `chrome.storage.local` for large datasets and persistent user data.
</persistence_engine>
<security_fortress>
## 🔐 PROTOCOL 3: THE SECURITY FORTRESS
1. **Context Bridge Safety:**
    *   Content Scripts are "Hostile Territory". Always sanitize data passed to the Service Worker via `chrome.runtime.sendMessage`.
2. **Declarative Net Request:**
    *   Use `declarativeNetRequest` for blocking/modifying headers. Only use `webRequest` as a fallback for Firefox if dynamic rules are critical.
</security_fortress>
<design_integration>
## 🎨 PROTOCOL 4: DESIGN & UI/UX (INTEGRATED)
> **Direct Instruction:** You are an extension developer, not a designer. You must outsource the "Soul" of the UI.
1. **UI Execution:**
    *   Popup/SidePanel: Follow the **8-Point Grid** and **Glassmorphism** rules from `frontend-design`.
    *   Component Atomization: Use Atomic Design 2.0 principles.
    *   Friction: Ensure the popup interaction is < 400ms (Doherty Threshold).
</design_integration>
<audit_and_reference>
## 🛠️ PROTOCOL 5: SCRIPT ENFORCEMENT (THE SENTINEL)
Every extension build MUST pass the high-tier audit suite.
1. **[manifest-auditor.js](skills/browser-extension/scripts/js/manifest-auditor.js):**
    *   **Rule:** MV3 compliance and CSP safety. No broad permissions.
2. **[persistence-check.js](skills/browser-extension/scripts/js/persistence-check.js):**
    *   **Rule:** Service Worker "Heartbeat" verification and State integrity.
3. **[asset-master.js](skills/browser-extension/scripts/js/asset-master.js):**
    *   **Rule:** Icon dimensional audit and asset optimization.
---
## 📂 COGNITIVE AUDIT CYCLE
1. Run `node scripts/js/manifest-auditor.js` -> Clean?
2. Run `node scripts/js/persistence-check.js` -> Heartbeat detected?
3. Run `node scripts/js/asset-master.js` -> Assets optimized?
4. **MANDATORY:** Run `playwright test` -> All paths pass?
5. Is it Manifest v3 compliant?
6. Does the Service Worker handle termination gracefully (State stored)?
7. Are permissions minimized?
8. Is the UI justified by a "Narrative-First" screenplay from `frontend-design`?
> **Link:** [frontend-design](skills/frontend-design/SKILL.md) 
</audit_and_reference>

Overview

This skill is a masterclass for building production-ready browser extensions in 2025/2026, centered on Manifest V3, reliable Service Worker patterns, Side Panel API, and cross-browser compatibility. It enforces a persistence-first mindset so extensions remain robust despite service worker termination and strict platform security. The guidance combines concrete architecture rules, runtime persistence techniques, and an audit cycle for repeatable, secure builds.

How this skill works

The skill inspects extension manifests, background/service worker code, and runtime persistence to ensure no volatile in-memory state is relied upon. It validates MV3 constraints (no remote code, least-privilege permissions), implements Alarm-based heartbeats, and recommends Offscreen documents for DOM work or heavier tasks. It also enforces Side Panel integration and runs script-level audits for manifest, persistence, and assets before test runs.

When to use it

  • When building any new Chrome-compatible extension that must be durable across service worker restarts.
  • When migrating legacy MV2 extensions to Manifest V3 with correct persistence and security.
  • When implementing background sync, scheduled work, or periodic tasks that must survive worker termination.
  • When you need a non-intrusive UI using the Side Panel or need consistent cross-browser behavior.

Best practices

  • Always use Manifest V3 with a service_worker background; never assume SW persistence—persist state immediately to chrome.storage or IndexedDB.
  • Use chrome.alarms to wake the service worker every 1–5 minutes for sync/housekeeping; use offscreen documents for DOM parsing or heavy CPU work.
  • Follow Principle of Least Privilege: request minimal runtime permissions and prefer optional_permissions when feasible.
  • Sanitize all data from content scripts before sending to the service worker; treat content scripts as untrusted.
  • Use declarativeNetRequest for request blocking/modification; fall back to webRequest only where Firefox requires it.

Example use cases

  • A note-taking side panel that saves every edit to IndexedDB to prevent loss when the service worker sleeps.
  • A cross-tab sync agent that uses chrome.alarms as a heartbeat and chrome.storage.session for transient auth tokens.
  • An enterprise privacy extension that applies declarativeNetRequest rules and validates them through the manifest auditor.
  • A background scraper that spawns an offscreen document for DOM parsing and stores results in chrome.storage.local.

FAQ

What do I do if my service worker loses state between wakes?

Persist every state change immediately to chrome.storage.local or IndexedDB; on activation, reload state from storage. Do not use globals.

How often should I schedule alarms?

Use a 1–5 minute window for regular heartbeats; adjust based on battery/network impact and only run expensive tasks when necessary.