home / skills / phrazzld / claude-config / browser-extension-dev

browser-extension-dev skill

needs review

This skill guides browser extension development with Manifest V3, minimal permissions, and cross-browser strategies to simplify secure, interoperable

npx playbooks add skill phrazzld/claude-config --skill browser-extension-dev

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

Files (1)

SKILL.md

2.9 KB

---
name: browser-extension-dev
description: |
  Browser extension development with security and cross-browser support. Use when:
  - Building Chrome, Firefox, or Safari extensions
  - Requesting permissions in manifest
  - Implementing content scripts or background workers
  - Handling cross-browser compatibility
  - Planning extension updates
  Keywords: browser extension, Manifest V3, content script, background script,
  permissions, Chrome extension, Firefox addon, WebExtensions API
effort: high
---

# Browser Extension Development

Manifest V3, minimal permissions, cross-browser first.

## Manifest V3

**Required for new extensions:**
```json
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "permissions": ["storage"],
  "host_permissions": ["https://api.example.com/*"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [{
    "matches": ["https://*.example.com/*"],
    "js": ["content.js"]
  }],
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'none'"
  }
}
```

## Minimal Permissions

**Request only what you need. Justify each permission:**

| Permission | Use Case |
|------------|----------|
| `storage` | Save user preferences |
| `activeTab` | Access current tab on user action |
| `scripting` | Inject scripts programmatically |
| `https://specific.com/*` | Access specific API |

**Never:** `<all_urls>` without documented justification.

**Use optional permissions for non-core features:**
```javascript
chrome.permissions.request({
  origins: ['https://optional.com/*']
}, (granted) => {
  if (granted) enableFeature();
});
```

## Message Passing

**Always validate messages at boundaries:**
```javascript
// background.js
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // Validate sender
  if (!sender.tab) return;

  // Validate message structure
  if (message.type !== 'FETCH_DATA') return;
  if (typeof message.url !== 'string') return;

  // Process safely
  fetchData(message.url).then(sendResponse);
  return true; // async response
});
```

**Never trust data from content scripts without validation.**

## Cross-Browser Support

```javascript
// Use webextension-polyfill for API normalization
import browser from 'webextension-polyfill';

// Feature detection
if (browser.storage?.sync) {
  await browser.storage.sync.set({ key: value });
} else {
  await browser.storage.local.set({ key: value });
}
```

**Test on Chrome, Firefox, Safari, Edge.**

## Updates

- Semantic versioning (MAJOR.MINOR.PATCH)
- Changelog accessible in-extension
- Gradual rollout for major changes
- Highlight permission changes to users
- Maintain backward compatibility
- Preserve user data across versions

## Anti-Patterns

- `<all_urls>` permission hoarding
- `eval()` or remote code execution
- Trusting content script data without validation
- Manifest V2 for new development
- Chrome-only without cross-browser testing
- Silent permission scope creep

Overview

This skill guides browser extension development with a focus on Manifest V3, minimal permissions, secure messaging, and cross-browser compatibility. It helps you design extensions for Chrome, Firefox, Safari, and Edge while avoiding common security and privacy pitfalls. Use it to plan manifests, permission requests, content/background scripts, and update strategies.

How this skill works

I inspect your extension design and recommend a Manifest V3 structure, permission scopes, and content/background script patterns that reduce risk. I validate message-passing boundaries, suggest feature-detection or polyfills for cross-browser APIs, and propose an update and versioning plan that preserves user data. Recommendations are concrete: manifest snippets, permission rationale, message validation examples, and rollout practices.

When to use it

Starting a new extension project (Manifest V3 required).
Requesting or narrowing permissions in your manifest.
Implementing content scripts, service workers, or message passing.
Ensuring compatibility across Chrome, Firefox, Safari, and Edge.
Planning release, changelog, or staged rollouts with preserved user data.

Best practices

Request the minimal permissions and justify each entry; avoid <all_urls> unless documented.
Use Manifest V3 service worker background scripts and content-security-policy for extension pages.
Validate all incoming messages and sender metadata before processing.
Use webextension-polyfill or feature detection to normalize cross-browser APIs.
Use optional permissions for non-core features and ask at runtime when needed.
Follow semantic versioning, show changelogs in-extension, and warn users of permission changes.

Example use cases

Create a Chrome/Firefox extension that injects content scripts only on allowed host patterns.
Design a background service worker that fetches from a specific API using host_permissions.
Add an opt-in feature that requests optional origins at runtime with chrome.permissions.request.
Migrate an existing Manifest V2 extension to Manifest V3 with cross-browser fallbacks.
Plan a staged rollout and changelog that preserves storage and highlights permission changes.

FAQ

Do I always need Manifest V3?

Yes for new extensions: develop with Manifest V3 and avoid Manifest V2 for new projects.

When is <all_urls> acceptable?

Only with a clear, documented user benefit and explicit justification; prefer scoped host_permissions instead.

How do I support both Chrome and Safari?

Use webextension-polyfill, feature detection, and test on each browser; implement fallbacks for missing APIs.