Teach the skill to submit, share and diagnose, and pin it to the MCP

Author: cezaraugusto

.claude-plugin/plugin.json

@@ -9,7 +9,7 @@
   },
   "homepage": "https://github.com/extensiondev/skill",
   "repository": "https://github.com/extensiondev/skill",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "keywords": [
     "agent-skill",
     "browser-extension",

.github/workflows/ci.yml

@@ -24,6 +24,12 @@ jobs:
           repository: extension-js/extension.js
           path: extension.js
 
+      - name: Checkout the MCP server (mcp-sync source of truth)
+        uses: actions/checkout@v5
+        with:
+          repository: extensiondev/mcp
+          path: mcp
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
@@ -33,6 +39,7 @@ jobs:
         run: node --test test/*.test.mjs
         env:
           EXTENSION_JS_REPO: ${{ github.workspace }}/extension.js
+          EXTENSION_DEV_MCP_REPO: ${{ github.workspace }}/mcp
 
       - name: Validate against the Agent Skills spec
         run: npx -y skills-ref validate skills/extension-dev

.github/workflows/release.yml

@@ -32,6 +32,12 @@ jobs:
           repository: extension-js/extension.js
           path: extension.js
 
+      - name: Checkout the MCP server (mcp-sync source of truth)
+        uses: actions/checkout@v5
+        with:
+          repository: extensiondev/mcp
+          path: mcp
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
@@ -80,6 +86,7 @@ jobs:
         run: node --test test/*.test.mjs
         env:
           EXTENSION_JS_REPO: ${{ github.workspace }}/extension.js
+          EXTENSION_DEV_MCP_REPO: ${{ github.workspace }}/mcp
 
       - name: Read package metadata
         id: meta

CHANGELOG.md

@@ -2,7 +2,70 @@
 
 ## 1.0.0
 
-The skill moves to Apache-2.0.
+The skill moves to Apache-2.0, and it finally covers the tools it was
+missing, including store submission.
+
+### Added
+
+- **Store submission through extension.dev (`extension_submit`).** The
+  publishing reference ran to 175 lines about shipping to stores and never
+  named the tool that ships to stores. It now has a section of its own: what
+  the tool does and does not do, why `dryRun` defaults to true, how to read
+  the per-store preflight rows, and why `dryRun: false` is a one-way door
+  into store review. This was the largest gap in the skill: the most
+  consequential and least reversible action on the platform had no page.
+- **Reading project state (`extension_release_status`).** Read-only, and the
+  place a valid build sha comes from. The skill previously told agents to
+  pass a build sha to `extension_release_promote` without saying where one
+  comes from.
+- **Sharing a build (`extension_preview_web`, `extension_shares`).** How to
+  hand someone a link that opens the extension with no install, why
+  `share: true` is required outside the extension.dev monorepo, that a share
+  also serves the built code as a zip, and how to list or revoke a link
+  afterwards. A share made without knowing `extension_shares` exists cannot
+  be pulled back.
+- **Session diagnosis (`extension_doctor`).** A CLI command and an MCP tool
+  that names the broken leg of a dev session in dependency order. Run it
+  before theorizing when an act tool errors. Includes the two readings that
+  mislead: a `skip` means blocked, and a `read-only` status is a choice, not
+  a fault.
+- **Chrome theme verification (`extension_theme_verify`)**, noted in the
+  debugging reference as the tool for themes rather than extensions.
+- **A drift test against the MCP server** (`test/mcp-sync.test.mjs`). It
+  derives the live tool registry from the MCP's own sources instead of
+  trusting prose, and fails when the skill states the wrong tool count, names
+  a tool the server retired, promises an `extension` CLI command that is not
+  registered, calls a tool MCP-only when a CLI command exists for it, or when
+  a newly registered tool goes undocumented without a written reason. CI and
+  the release workflow now check out the MCP server alongside Extension.js.
+
+### Fixed
+
+- **The CLI parity claim was wrong.** The skill said nearly every MCP
+  capability had an `extension` CLI equivalent, with three exceptions. In
+  fact 13 of the 29 tools have a CLI command, and everything that talks to
+  extension.dev has none. An agent reading the old claim would confidently
+  tell a user to run commands that do not exist. The skill now lists the CLI
+  commands that exist and the tools that are MCP-only, and both lists are
+  held to their sources by the new drift test.
+- **The publishing and STORE.md references pointed at a package readers
+  cannot install.** They named a private deploy CLI as the way to mint a
+  Chrome refresh token and to hold credentials in a local dotfile. That
+  package publishes with restricted access, so the command answered 404 for
+  everyone outside the company. The Chrome credential guidance now recommends
+  the service account, which needs nothing minted, and credential storage is
+  described on the console path it actually uses. A test now fails if any
+  private package name reappears anywhere in this package.
+- **The tool count in the README** said 28; the server registers 29.
+- **`STORE.md` advice is now trustworthy where it was guesswork.** The MCP's
+  `STORE.md` parser is a pinned port of the one the real submission runs,
+  held to it by a test that replays both over the same corpus, so the skill
+  now says a missing-notes warning means a genuinely missing field. It also
+  records the fact that bit people: the submission reads `STORE.md` from the
+  source repository at the built commit, not from the working directory.
+- **The September 6, 2026 platform hold** is described accurately. Device
+  login works, and so does listing or revoking an existing share; five lanes
+  answer 403 `PLATFORM_NOT_OPEN` until that date.
 
 ### Changed
 
@@ -11,7 +74,12 @@ The skill moves to Apache-2.0.
   those rights on those versions. From 1.0.0 forward the license is
   Apache-2.0, which adds an express patent grant and requires anyone
   shipping a modified copy to state that they changed the files. Installing
-  this skill and using it to build extensions is unaffected.
+  this skill and using it to build extensions is unaffected. The skill
+  frontmatter and the plugin manifest, which still read MIT, now agree with
+  the LICENSE file.
+- The workflow gained a step for sharing a build and split publish from
+  submit, because conflating the two is how an irreversible store submission
+  happens by accident.
 
 ## 0.5.1
 
@@ -39,8 +107,8 @@ store reviewer notes, and version history, one section per store.
 
 - New reference `references/store-md.md` with the template, the maintenance
   rules (manifest change, release, rejection, privacy shift), and the table
-  of fields `extension-deploy` 1.4.0 submits automatically (Firefox reviewer
-  and release notes, Edge certification notes).
+  of fields a submission sends automatically (Firefox reviewer and release
+  notes, Edge certification notes).
 - Workflow step 6 and `references/publishing.md` now direct the agent to
   create and maintain `STORE.md` as soon as publishing intent appears.
 - The Chrome section mirrors the `CHROMEWEBSTORE.md` shape other agent

README.md

@@ -26,17 +26,20 @@ Powered by [extension.dev](https://extension.dev) and the open-source
 half of the extension.dev agent stack:
 
 - **[@extension.dev/mcp](https://www.npmjs.com/package/@extension.dev/mcp)**
-  gives agents *hands*: 28 MCP tools for scaffolding, building, live DOM
-  inspection, log streaming, publishing, and headless release promotion.
+  gives agents *hands*: 29 MCP tools for scaffolding, building, live DOM
+  inspection, log streaming, publishing, store submission, and headless
+  release promotion.
 - **@extension.dev/skill** gives agents *judgment*: when to use which tool,
   the cross-browser rules, the silent-failure gotchas, and the publish
   checklist, packaged in the open [Agent Skills](https://agentskills.io)
   format (SKILL.md plus progressive-disclosure references).
 
-The skill works standalone: every capability documents the `extension` CLI
-path. It shines when the MCP server is connected, because the skill tells the
-agent to verify against the live browser instead of guessing, and the MCP
-tools make that a one-call operation.
+The skill works standalone: the whole local loop (scaffold, dev, build,
+inspect, publish) documents the `extension` CLI path, and the skill says
+plainly which capabilities are MCP-only so an agent never invents a command
+that does not exist. It shines when the MCP server is connected, because the
+skill tells the agent to verify against the live browser instead of guessing,
+and the MCP tools make that a one-call operation.
 
 In the shipped benchmark, a skill-equipped agent passed **15/15** graded
 assertions; the no-skill baseline passed 10/15. Details and reproduction in
@@ -137,8 +140,9 @@ skills/
       project-structure.md       Layout, entry wiring, special folders, env vars
       cross-browser.md           chromium:/firefox: prefixes, API namespaces
       api-gotchas.md             Service worker lifetime, gestures, messaging
-      debugging.md               --source, --logs, act tools, diagnosis playbook
-      publishing.md              Builds, zips, store checklist, extension.dev publish
+      debugging.md               --source, --logs, act tools, doctor, playbook
+      publishing.md              Builds, zips, store checklist, publish, share, submit
+      store-md.md                STORE.md convention, template, what gets submitted
 ```
 
 The SKILL.md body stays small and always loads when the skill triggers; the

skills/extension-dev/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: extension-dev
 description: Build, debug, and publish cross-browser extensions (Chrome, Edge, Firefox, and any Chromium- or Gecko-based browser such as Brave, Opera, Vivaldi, Yandex, Waterfox, or LibreWolf, plus Safari) with the extension.dev framework. Use this skill whenever the user mentions browser extensions, Chrome extensions, Firefox add-ons, Safari web extensions, WebExtensions, Manifest V3, manifest.json, content scripts, service workers, side panels, popups, options pages, chrome.* or browser.* APIs, or publishing to the Chrome Web Store or Firefox Add-ons, even if they never name extension.dev or Extension.js explicitly. Also use it when debugging why an extension does not load, inject, or update.
-license: MIT
+license: Apache-2.0
 metadata:
   author: Cezar Augusto
   version: 0.5.1
@@ -23,11 +23,22 @@ Two companions do the heavy lifting. Prefer them over guessing:
   to GitHub and before `extension_auth` against the new project), and headless
   release promotion. If its `extension_*` tools are available in the session,
   use them.
-- **`extension` CLI**: nearly every MCP capability has a CLI equivalent
-  (`npx extension@latest <command>`). Use it when the MCP server is not
-  connected. The exceptions are `extension_release_promote` (also reachable
-  as `extension-mcp release promote`, but not via the `extension` CLI) and
-  the session tools `extension_stop`/`extension_list_extensions`.
+- **`extension` CLI**: the local loop has a CLI path
+  (`npx extension@latest <command>`), and only the local loop. The commands
+  are `create`, `dev`, `start`, `preview`, `build`, `logs`, `inspect`,
+  `eval`, `storage`, `reload`, `open`, `doctor`, `publish`, `install` and
+  `uninstall`. Use them when the MCP server is not connected.
+- **Everything else is MCP-only.** Do not invent a CLI command for a tool
+  that has none, because the shell will not tell you it was never there. No
+  `extension` command exists for `extension_auth`,
+  `extension_project_create`, `extension_release_status`,
+  `extension_release_promote`, `extension_submit`, `extension_preview_web`,
+  `extension_shares`, `extension_stop`, `extension_list_extensions`,
+  `extension_templates`, `extension_add_feature`,
+  `extension_manifest_validate`, `extension_analyze`,
+  `extension_dom_snapshot` or `extension_theme_verify`. Outside an MCP
+  session, `extension_release_promote` is also reachable through the MCP
+  package's own bin as `extension-mcp release promote`.
 
 ## Workflow
 
@@ -58,13 +69,25 @@ Two companions do the heavy lifting. Prefer them over guessing:
    `npm run build --zip` throws (core rule 5). When a verification session is
    done, shut it down (MCP: `extension_stop`) so dev servers and browsers do
    not pile up.
-6. **Publish deliberately.** Zip with `--zip`, check the store-readiness rules,
-   then submit (or publish to extension.dev via `extension_publish`). Track
-   listing copy, permission justifications, and per-store reviewer notes in a
-   root `STORE.md` from the moment publishing intent appears; deploy tooling
-   submits the API-accepted fields from it automatically. See
-   [references/publishing.md](references/publishing.md) and
-   [references/store-md.md](references/store-md.md).
+6. **To show someone the build, send a link, not a file.**
+   `extension_preview_web` with `share: true` uploads the build and returns a
+   URL that opens in a web emulator with no install and no sign-in. Pass
+   `share: true` every time unless you are working inside the extension.dev
+   monorepo: the default lane returns a `preview://build` deep link that
+   resolves only against a local preview.extension.dev dev server. A share
+   also serves the build as a zip, so it hands over the built code; say so
+   before sharing, and use `extension_shares` to list or revoke a link
+   afterwards. See [references/publishing.md](references/publishing.md).
+7. **Publish and submit are different verbs.** `extension_publish` pushes a
+   build to the extension.dev platform. `extension_submit` sends a built
+   commit into a store's review queue, which is irreversible; it defaults to
+   a dry run, and only `dryRun: false` dispatches. "Deploy" and "ship"
+   almost always mean publish. Zip with `--zip` and check the store-readiness
+   rules first, and track listing copy, permission justifications, and
+   per-store reviewer notes in a root `STORE.md` from the moment publishing
+   intent appears: the submission reads the API-accepted fields from it
+   automatically. Read [references/publishing.md](references/publishing.md)
+   and [references/store-md.md](references/store-md.md) before either verb.
 
 ## Core rules
 
@@ -161,6 +184,16 @@ feedback. Close the loop instead of theorizing:
 | Done verifying? | MCP `extension_stop` (kills the dev server and its browser) |
 | What is in `chrome.storage`? | MCP `extension_storage` |
 | Does the popup/panel open? | `extension open action` (`--allow-control`) or MCP `extension_open` |
+| An act tool errored and I cannot tell why | `extension doctor` or MCP `extension_doctor`, before any theory |
+| Where does the project stand on extension.dev? | MCP `extension_release_status` (read-only; it is also where a valid build sha comes from) |
+
+Run `extension_doctor` first whenever `extension_storage`, `extension_reload`,
+`extension_eval` or `extension_open` errors unexpectedly. It returns one row
+per leg in dependency order (ready contract, dev-server process, control port,
+control channel, eval token, executor, browser liveness), so it names the
+broken leg instead of leaving you to guess which one it was. Read a `skip` as
+blocked, not as a pass. With no `projectPath` it runs as a pre-flight
+environment check before any project exists.
 
 Full flag and event reference: [references/debugging.md](references/debugging.md).
 

skills/extension-dev/references/debugging.md

@@ -135,6 +135,30 @@ result reports `gesture: false` (plus a warning when the manifest declares
 | `tab.url` undefined | Missing `tabs` permission (silent failure by design) |
 | Storage "not saving" | Async race; listen to `onChanged` instead of read-after-write |
 
+## When the tools themselves misbehave
+
+`extension doctor` (MCP: `extension_doctor`) diagnoses the session end to end
+instead of leaving you to bisect it: ready contract, dev-server process,
+control-port agreement, control channel, eval token, executor, browser
+liveness. It returns one `{check, status, detail, remediation}` row per leg in
+dependency order.
+
+```bash
+extension doctor                      # diagnose the session in this project
+extension doctor --output json        # machine-readable
+```
+
+Run it first whenever `extension_storage`, `extension_reload`,
+`extension_eval` or `extension_open` errors unexpectedly. Three readings that
+save time:
+
+- A `skip` means blocked, not passed. The row names the check that blocked it.
+- A session started without `allowControl` returns `ok: true` with status
+  `read-only`. Its control channel is off by choice; that is not the bug.
+- With no project path it runs as a pre-flight environment check (node, the
+  Extension.js CLI, the template cache), which is useful before any project
+  exists.
+
 ## Other tools
 
 - `extension_manifest_validate` (MCP): cross-browser manifest validation with
@@ -148,3 +172,11 @@ result reports `gesture: false` (plus a warning when the manifest declares
 - `extension_browsers` with `action: "detect"` or `action: "install"` (MCP):
   check what browsers exist before launching; install managed binaries in CI
   or containers.
+- `extension_theme_verify` (MCP): for Chrome *themes*, not extensions. It
+  derives every color current Chrome would paint from a theme manifest and
+  flags fabricated colors, parity gaps, and keys Chrome silently discards
+  (dead legacy, incognito, unknown, out-of-range). Use it instead of reading
+  theme colors by eye; it verifies only and never edits the manifest. The
+  rendered and real-pixel legs need a browser, so they come back as
+  `needsAttended` rather than passed, and a theme is not proven by this tool
+  alone.