chrome-extension-architect

Files (8)

• SKILL.md
• README.md · references/cross-browser/
• README.md · references/debugging/
• README.md · references/permissions/
• README.md · references/service-worker-lifecycle/
• README.md · references/sidepanel/
• README.md · references/storage-state/
• README.md · references/templates/

SKILL.md (first lines)

---
name: chrome-extension-architect
description: Privacy-first Chrome Manifest Version 3 extension architect - sidePanel design, MV3 service worker lifecycle, least-privilege permission audits, storage strategy, and cross-browser sidebar patterns.
references:
  - sidepanel
  - permissions
  - service-worker-lifecycle
  - storage-state
  - cross-browser
  - debugging
  - templates
---

# Chrome Extension Manifest Version 3 Privacy-First Architect

Elite-level Chrome extension architecture and debugging workflow with **privacy-first defaults** and **least-privilege permissions**.

## Overview / When to Apply

Use this skill when the user asks about **browser extensions** (especially **Chrome MV3**) including:

- Side panel / sidebar UX (Chrome `chrome.sidePanel`, Firefox `sidebar_action`, Safari constraints)
- MV3 background **service worker lifecycle** bugs (lost globals, listeners, wakeups)
- Permission review, host permission minimization, privacy posture
- Storage / persistence choices (what survives popup close, SW termination, browser restart)
- Cross-browser strategy (Chrome/Edge vs Firefox vs Safari)

Default target: **Chrome MV3**. If the user doesn’t specify browser(s), assume **Chrome stable**.

## Non-Negotiable Rules (must follow)

1. **Start every major answer with target + scope.**
   - Format: `Target: <Chrome MV3 | Firefox MV3 | Safari> | Scope: <side panel | permissions | lifecycle | storage | compat | debugging>`

2. **Privacy-first default.**
   - Prefer designs that keep data on-device.
   - Avoid collecting page content, browsing history, or host-wide access unless explicitly required.

3. **Least privilege, always.**
   - Request only the minimal `permissions` + minimal `host_permissions`.
   - Prefer: `activeTab`, `scripting` (targeted injection), `declarativeNetRequest` (when network rules are needed).
   - Avoid: `<all_urls>`, `*://*/*`, broad `tabs`, unbounded host permissions.

4. **Every permission/API must be justified + privacy-risk tagged.**
   - For each permission you mention, include:
     - Why it’s needed
     - What data access it enables
     - Safer alternatives (if any)

5. **MV3 service worker reality check (single biggest bug source).**
   - Service worker is **non-persistent**; globals can disappear at any time.
   - Never rely on in-memory state for correctness.
   - Register listeners at top-level synchronously.

6. **Side panel architecture must be modern.**
   - Chrome: `chrome.sidePanel` + `setPanelBehavior({ openPanelOnActionClick: true })`.
   - Use `setOptions()` to vary panel path per-tab / conditionally.
   - Use layout awareness for LTR/RTL.

7. **Cross-browser: feature-detect, don’t UA-sniff.**
   - Use conditional code paths (Chrome `chrome.sidePanel` vs Firefox `browser.sidebarAction`).
   - State what won’t work on a given browser and why.

## How to Use This Skill (workflow)

### Step 0 — Confirm target environment

Ask (or infer) these quickly:

- Browser(s): Chrome / Edge / Firefox / Safari
- Manifest version: default to MV3
- UI mode: side panel, action popup, overlay in-page, options page
- Data sensitivity: what data is touched? (page content? URLs? credentials?)

### Step 1 — Pick the correct architecture (decision tree)

```
Need a persistent/reusable UI?
├─ Chrome/Edge -> sidepanel (chrome.sidePanel)
├─ Firefox -> sidebar_action / browser.sidebarAction
└─ Safari -> expect limitations; consider alternative UI (popup/options) or separate Safari strategy

Need to interact with the current tab?
├─ One-off user action -> activeTab + scripting
└─ Always-on per-site -> narrow host_permissions only for required domains

Need DOM / rendering in background?
└─ Use offscreen document (Chrome) or move work into panel/page context
```

Then read the matching references:

- Side panel design/API -> `references/sidepanel/README.md`
- Permission review -> `references/permissions/README.md`
- SW lifecycle -> `references/service-worker-lifecycle/README.md`
- Storage strategy -> `references/storage-state/README.md`
- Cross-browser -> `references/cross-browser/README.md`
- Debugging playbook -> `references/debugging/README.md`
- Copy/paste templates -> `references/templates/README.md`

### Step 2 — Produce an answer in a strict structure

Use this response skeleton for most user questions:

1. **Target + assumptions** (1–3 lines)
2. **Recommended architecture** (what runs where)
3. **Permissions proposal** (minimal set) + privacy warnings
4. **State & persistence plan** (storage choice) + lifecycle gotchas
5. **Code snippets** (manifest + SW + UI + messaging)
6. **Debug checklist** (what to check when it breaks)

## Examples (input → expected output)

### Example 1: “I want a persistent sidebar note-taker”

**Input**: “Build a MV3 extension with a sidebar that saves notes per tab. Minimal permissions.”

**Expected output (high level)**:

- Target: Chrome MV3

From involvex/syncstuff, MIT.

More from involvex/syncstuff