# Firefox Addon Manifest Scaffold

> Scaffolds a new manifest.json for a Firefox WebExtension, or lints an existing one for technical/schema problems (wrong shape for Manifest V2 vs V3, missing browser_specific_settings.gecko.id, invalid content_security_policy or web_accessible_resources shape, action/browser_action mismatches, etc.). Use whenever someone is starting a new Firefox extension, asks to generate or fix a manifest.json, wants to migrate MV2 to MV3, or their extension fails to load with a manifest-related error — even without saying "manifest," e.g. "set up a new Firefox extension," "why won't my extension load," "convert this to manifest v3." Part of a Firefox add-on suite with firefox-addon-policy-check, firefox-addon-data-taxonomy, and firefox-addon-amo-submission. UNOFFICIAL, not built or endorsed by Mozilla — schema facts come from docs that can change, and this isn't a substitute for `web-ext lint` or loading the extension in Firefox.

- Skill: `mozilla/firefox-addon-manifest-scaffold` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add mozilla/firefox-addon-manifest-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mozilla/firefox-addon-manifest-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mozilla (https://skillmd.com/u/mozilla)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mozilla/firefox-addon-manifest-scaffold

---


# Firefox Add-on Manifest Scaffold/Lint (unofficial)

## Say this up front

This is an unofficial helper for manifest.json *schema* correctness — not a
Mozilla tool, and not a check of Mozilla's Add-on Policies (that's a
different skill in this suite: `firefox-addon-policy-check`). A manifest that
passes every check here can still be rejected on policy grounds, and facts
about the schema can drift as Firefox evolves — always also run `web-ext
lint` and load the extension via `about:debugging` before trusting it's
submission-ready.

## Two modes

### Mode A: scaffolding a new manifest.json

Ask (conversationally, not necessarily all at once) whatever of this you
don't already know from context:

- Extension name and one-line description.
- Manifest V2 or V3? Default to recommending V3 unless they have a concrete
  reason to want V2 (existing MV2 codebase, a dependency on an MV2-only key).
  Explain briefly why if they don't specify: MV3 is where Firefox and every
  other browser are investing, but Firefox doesn't implement extension
  service workers regardless of version, so `background.scripts` still works
  fine under MV3.
- What permissions/host access does it actually need? Push back gently on
  `<all_urls>` if they haven't said why they need it — ask what URLs or APIs
  are actually involved.
- Does it need a background script, a toolbar button/popup, an options page?
- Will it collect or transmit any data leaving the browser? If yes, don't
  guess at `data_collection_permissions` here — point them at the
  `firefox-addon-data-taxonomy` skill for that specific piece, then fold the
  result back into the manifest you're building.

Read `references/manifest-schema-notes.md` for the exact shape of each key
under MV2 vs MV3 (background, action/browser_action, content_security_policy,
web_accessible_resources, permissions/host_permissions,
browser_specific_settings.gecko) and write the manifest.json accordingly.
Set `browser_specific_settings.gecko.id` — mandatory for MV3 signing, and
worth setting for MV2 too so AMO doesn't hand out a random GUID on first
signing.

After writing it, run the linter on your own output (Mode B) as a sanity
check before handing it to the user — cheap insurance against a copy-paste
mistake.

### Mode B: linting an existing manifest.json

```bash
python3 <skill_dir>/scripts/lint_manifest.py <path-to-manifest-or-extension-root> --json
```

This checks things like: mandatory keys present; `default_locale`/`_locales`
pairing; `content_security_policy` and `web_accessible_resources` shaped
correctly for the declared `manifest_version` (these are two of the most
common "why won't Firefox load my extension" bugs when porting between MV2
and MV3); `action` vs `browser_action` matching the manifest version;
`background.persistent: true` under MV3 (hard error); `gecko.id` format and
presence; `data_collection_permissions` key names being valid taxonomy
values (not their business logic — that's `firefox-addon-data-taxonomy`).

Findings come with a severity: `error` (Firefox will refuse to load this or
AMO's validator will reject it), `warn` (works, but likely friction), `info`.
Report all three, but lead with the errors — those are the ones actually
blocking the user, not just stylistic.

If the user is migrating MV2 → MV3, run the linter, then walk through each
error explaining the MV2 shape they have versus the MV3 shape they need,
using `references/manifest-schema-notes.md` as the source of truth for both.

## When you're not sure

Firefox's actual behavior is the real spec; MDN and this reference file are
both just documentation of it, and documentation can lag behind reality or
be wrong. If a finding here contradicts what the user is actually observing
in Firefox, trust Firefox and say so rather than insisting the lint is right.