firefox-addon-manifest-scaffold

name

firefox-addon-manifest-scaffold

description

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.

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

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.