@genclass/mcp 0.2.1: the instructions carry the when, the skill the how; init installs the skill

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "genclass",
       "source": "./packages/mcp/plugin",
       "description": "The GenClass MCP server, a prompt hook that brings new findings to each prompt, and a skill for intermittent and timing-dependent frontend bugs.",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "category": "development"
     }
   ]

.cursor-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "genclass",
       "source": "packages/mcp/plugin",
       "description": "The GenClass MCP server and a skill for intermittent and timing-dependent frontend bugs.",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "category": "development"
     }
   ]

README.md

@@ -88,7 +88,7 @@ steps again with the network answering in different orders (and slower) to find
 exact order that broke, and write a Playwright test that fails until the fix is in. Everything stays on your machine.
 
 ```bash
-claude mcp add genclass -- npx -y @genclass/mcp@0.2.0
+claude mcp add genclass -- npx -y @genclass/mcp@0.2.1
 ```
 
 ```ts

docs/adoption/listings/mcp.md

@@ -96,7 +96,7 @@ official registry); docs.github.com "Extend Copilot Chat with MCP" (VS Code adds
   > different orders to find race conditions, replays one exact order to prove a fix, and writes a Playwright
   > regression test. It needs no account or API key and sends nothing off the machine. Measured so far on one page
   > (a stale-response race): it found the race in 5 of 6 reordered runs and reported nothing on the fixed page.
-  > Install in VS Code: `code --add-mcp '{"name":"genclass","command":"npx","args":["-y","@genclass/mcp@0.2.0"]}'`.
+  > Install in VS Code: `code --add-mcp '{"name":"genclass","command":"npx","args":["-y","@genclass/mcp@0.2.1"]}'`.
   > Thank you.
 
 ## 3. Anthropic directory (claude.ai/directory/manage)
@@ -117,7 +117,7 @@ support.claude.com "Anthropic Software Directory Policy".
   the four acknowledgements. Updates: GitHub push webhook.
 - **What the checks will say.** Local run of `claude plugin validate packages/mcp/plugin --profile directory`
   (Claude Code 2.1.310): passes; one warning, `ICON_MISSING`. The portal also holds pinned launchers for a reviewer:
-  expect "Runs a pinned npx or uvx package" (both `.mcp.json` and the hook run `npx -y @genclass/mcp@0.2.0`), and
+  expect "Runs a pinned npx or uvx package" (both `.mcp.json` and the hook run `npx -y @genclass/mcp@0.2.1`), and
   possibly "MCP server command wasn't read" because the server is not a file inside the plugin folder. An unpinned
   launcher would block; `packages/mcp/test/manifests.test.ts` keeps both pins equal to `package.json`'s version. The
   way to avoid the hold is to ship the built server (`dist/cli.js`, 125 KB, no dependencies) inside the plugin
@@ -159,7 +159,7 @@ Source: glama.ai/mcp/faq; glama.ai/blog/2025-07-08-what-is-glamajson; schema gla
 ```dockerfile
 FROM node:22-alpine
 ENV GENCLASS_STATE_DIR=none
-ENTRYPOINT ["npx", "-y", "@genclass/mcp@0.2.0"]
+ENTRYPOINT ["npx", "-y", "@genclass/mcp@0.2.1"]
 ```
 
 - **Fields.** Display name `GenClass`; description: the 100-character text above. How Glama treats a server in a
@@ -208,7 +208,7 @@ Source: https://mcp.so/submit; chatmcp/mcpso issue 1 "Submit Your MCP Servers he
   > GenClass: https://github.com/genclass-dev/GenClass-lib (server in `packages/mcp`). A local MCP server that shows a
   > coding agent what happened inside a web app's pages in causal order, finds race conditions by re-running a page
   > with responses delivered in different orders, replays one exact order to prove a fix, and writes a Playwright
-  > regression test. Install: `npx -y @genclass/mcp@0.2.0`. Category: developer tools.
+  > regression test. Install: `npx -y @genclass/mcp@0.2.1`. Category: developer tools.
 
 ## 9. cursor.directory
 
@@ -238,10 +238,10 @@ Source: google-gemini/gemini-cli `docs/extensions/releasing.md` and `docs/extens
 
 - **How.** No submission: a daily crawler lists public repositories with the GitHub topic `gemini-cli-extension`
   whose root holds `gemini-extension.json`. Add the topic to `genclass-dev/GenClass-lib` once 0.1.0 is on npm. The
-  committed `gemini-extension.json` starts `npx -y @genclass/mcp@0.2.0` (kept equal to the package version by
+  committed `gemini-extension.json` starts `npx -y @genclass/mcp@0.2.1` (kept equal to the package version by
   `manifests.test.ts`).
 - **Install line for the entry.** `gemini extensions install https://github.com/genclass-dev/GenClass-lib`. This
-  clones the whole repository, which is large; `gemini mcp add genclass npx -- -y @genclass/mcp@0.2.0` adds the server
+  clones the whole repository, which is large; `gemini mcp add genclass npx -- -y @genclass/mcp@0.2.1` adds the server
   alone.
 
 ## 12. Smithery (smithery.ai)

docs/runtime/AGENT.md

@@ -40,14 +40,19 @@ results are in section 7 and in [RESULTS.md](RESULTS.md) section 16.
 ## 1. Setup
 
 ```bash
-claude mcp add genclass -- npx -y @genclass/mcp@0.2.0   # or: npx -y @genclass/mcp@0.2.0 init  (writes .mcp.json)
+claude mcp add genclass -- npx -y @genclass/mcp@0.2.1   # or: npx -y @genclass/mcp@0.2.1 init  (writes .mcp.json and .claude/skills/genclass/SKILL.md)
 ```
 
 Or as a Claude Code plugin from this repository's marketplace (`.claude-plugin/marketplace.json`; the plugin is
-`packages/mcp/plugin`: the server, a `UserPromptSubmit` hook and a skill whose description tells Claude when to use
-it): `/plugin marketplace add genclass-dev/GenClass-lib`, then `/plugin install genclass@genclass`. Other clients
+`packages/mcp/plugin`: the server, a `UserPromptSubmit` hook and the `genclass` skill):
+`/plugin marketplace add genclass-dev/GenClass-lib`, then `/plugin install genclass@genclass`. The server's
+`instructions` carry the triggers (the symptom words, the code changes that call for an explore, the scan before a UI
+change is done) and the first call for each, so every client that passes them on gets the "when"; the skill carries
+the procedure (section 4.2) and does not need the plugin: `init` writes it into the project, and
+`npx skills add genclass-dev/GenClass-lib` installs the repository-root copy (`skills/genclass/SKILL.md`, kept
+identical to the plugin's by the version sync) through a skill directory. Other clients
 (Cursor, VS Code, Codex CLI, Gemini CLI, Windsurf, Cline, Goose, Zed, JetBrains, OpenCode): the install blocks in
-[packages/mcp/README.md](../../packages/mcp/README.md#install), or `npx -y @genclass/mcp@0.2.0 config <client>`.
+[packages/mcp/README.md](../../packages/mcp/README.md#install), or `npx -y @genclass/mcp@0.2.1 config <client>`.
 Every launcher is pinned to the release. `packages/mcp/server.json` is the entry for the official MCP Registry
 (published by the release workflow with GitHub OIDC after the npm package); the listings for other directories are
 drafted in [docs/adoption/listings/mcp.md](../adoption/listings/mcp.md).
@@ -192,10 +197,27 @@ after 30 minutes and are not restored after a restart.
 | `genclass_scan` | `{url, phone?, hosted?}`: audits any page (no `connectAgent` needed) by running `@genclass/runtime`'s `scan <url> --json` (the project's own runtime when it has the command, else `npx -y @genclass/runtime@beta`) in the project's folder: headless Chromium through Playwright at desktop and phone sizes, the 23 measured visual checks in observe mode; a score and each problem with its element, selector and suggested CSS fix, plus the JSON report (`structuredContent`). `--local` unless `hosted: true` (the genclass.dev page check, public pages only), so the URL leaves the machine only when the agent asks |
 | `genclass_clear` | forget runs and/or findings (runs findings still need are kept) |
 
-The server's `instructions` (sent at initialize) tell the agent when to reach for these on its own: an intermittent bug
-report; after changing code that fetches, submits, autosaves, polls, debounces or listens to a socket; before calling a
-UI change done (`genclass_scan` on the page, also after CSS or layout changes and on sites the agent does not own); and
-to confirm a bug before fixing it and prove the fix after.
+The server's `instructions` (sent at initialize, under 4,096 characters; the one piece of guidance every MCP client
+passes on, where tool descriptions may be deferred until a tool search) carry the "when" and the first call for each:
+the symptom words in the first 500 characters ("sometimes", "randomly", "only in production", "on slow connections", a
+value that "flips back", stale or old results, lost edits, double submits, sideways scrolling) and `genclass_findings`
+then `genclass_explain`; after changing code that fetches, submits, autosaves, polls, debounces, paginates or listens
+to a socket, `genclass_explore`; before fixing a finding, `genclass_replay`, and again after the fix; before calling a
+UI change done (also after CSS or layout changes and on sites the agent does not own), `genclass_scan`. They name the
+`genclass` skill so a client that has it loads it.
+
+The skill (`packages/mcp/plugin/skills/genclass/SKILL.md`; the plugin installs it, `genclass-mcp init` writes it to
+`.claude/skills/genclass/SKILL.md`, and `skills/genclass/SKILL.md` at the repository root is the identical copy skill
+directories read) carries the "how", which always-loaded context cannot afford: the explore arguments
+(`runs: 6, slow_ms: 600`), the Playwright pairing (`--repeat-each 8 --workers 1`), how to read a report
+("Compared: 6 of 6" against "No verdict" and "0 compared"; "Internal state only" and "Along the way only" are not
+races), what a witness, an explore race and a model detection each are, the reporting rule ("reproduced",
+"not reproduced" or "no race in N orders", never "fixed" unless a replay or explore showed it), and what to do when
+the `genclass_*` tools are missing (the one-line install, or `npx @genclass/runtime@beta scan <url> --json` for the
+visual checks alone). Its frontmatter description repeats the triggers, since that is what a client matches a skill
+on; its body does not. `packages/mcp/test/manifests.test.ts` checks the frontmatter, that every `genclass_*` name in
+the body is a registered tool, the description's length (Claude Code's 1,024), that the root copy is identical, and
+that the instructions stay under 4,096 characters, put the symptom words first and name the skill.
 
 ### 4.3 Agent API
 
@@ -205,8 +227,11 @@ start), `clear`. Local processes of the same user only (section 6).
 
 ### 4.4 Command and push
 
-- `genclass-mcp` runs the server on stdio. `genclass-mcp init [--hook]` adds it to `.mcp.json` (merging) and, with
-  `--hook`, a `UserPromptSubmit` hook to `.claude/settings.json`. `genclass-mcp status` prints the bridge's status.
+- `genclass-mcp` runs the server on stdio. `genclass-mcp init [--hook] [--no-skill]` adds it to `.mcp.json`
+  (merging), writes the `genclass` skill to `.claude/skills/genclass/SKILL.md` (the package's copy with a
+  `genclass:init` marker line after the frontmatter; a rerun replaces a file that carries the marker and leaves one
+  that does not, saying which; `--no-skill` leaves it out) and, with `--hook`, a `UserPromptSubmit` hook to
+  `.claude/settings.json`. `genclass-mcp status` prints the bridge's status.
 - **Push.** New findings are sent as Claude Code channel events (`notifications/claude/channel`, the experimental
   `claude/channel` capability; research preview, enabled with
   `claude --dangerously-load-development-channels server:genclass`), at most 3 every 3 s. Without channels, the

gemini-extension.json

@@ -1,13 +1,13 @@
 {
   "name": "genclass",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Find race conditions in your web app by reordering its responses, replay one, prove the fix.",
   "mcpServers": {
     "genclass": {
       "command": "npx",
       "args": [
         "-y",
-        "@genclass/mcp@0.2.0"
+        "@genclass/mcp@0.2.1"
       ]
     }
   }

llms-install.md

@@ -23,7 +23,7 @@ merging it with the servers already there:
   "mcpServers": {
     "genclass": {
       "command": "npx",
-      "args": ["-y", "@genclass/mcp@0.2.0"]
+      "args": ["-y", "@genclass/mcp@0.2.1"]
     }
   }
 }
@@ -73,4 +73,8 @@ Ask for `genclass_findings` after reproducing a bug, `genclass_explore` after ch
 `genclass_replay` to confirm a bug before fixing it and its fix after, and `genclass_scan {url}` to audit a page for
 visual bugs before calling a UI change done (it needs Playwright's Chromium: `npx playwright install chromium`; the
 same audit from a terminal is `npx @genclass/runtime@beta scan <url>`). The server's instructions and each tool's
-description say when to use what. More: https://github.com/genclass-dev/GenClass-lib/tree/main/packages/mcp
+description say when to use what; the procedure (explore arguments, how to read a report, what to say when done) is
+the `genclass` skill: `npx -y @genclass/mcp@0.2.1 init` writes it to `.claude/skills/genclass/SKILL.md` for Claude
+Code (`--no-skill` leaves it out), and `npx skills add genclass-dev/GenClass-lib` installs the repository-root copy
+(`skills/genclass/SKILL.md`) through a skill directory, with no server. More:
+https://github.com/genclass-dev/GenClass-lib/tree/main/packages/mcp

packages/mcp/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.2.1 (2026-10-27)
+
+- **The plugin has an icon** (`plugin/.claude-plugin/icon.png`, the genclass.dev mark, 512 by 512), which the Anthropic directory reads on the first save.
+- **The instructions carry the "when", the skill the "how"** ([docs/runtime/AGENT.md](../../docs/runtime/AGENT.md)
+  section 4.2). The server's `instructions` now open with the symptom words ("sometimes", "randomly", "only in
+  production", "on slow connections", a value that "flips back", stale or old results, lost edits, double submits,
+  sideways scrolling), all within the first 500 characters, keep one line per trigger saying what to call first, and
+  name the `genclass` skill so a client that has it loads it (2,712 characters, under the 4,096 ceiling). The skill
+  (`plugin/skills/genclass/SKILL.md`) no longer restates the triggers in its body: its frontmatter description is the
+  trigger, with the same words early, and the body is the procedure (the explore arguments, the Playwright pairing,
+  how to read "Compared: 6 of 6" against "No verdict" and "0 compared", that "Internal state only" and "Along the way
+  only" are not races, witness against explore race against model detection, the reporting rule) plus a new section
+  for when the `genclass_*` tools are missing (the pinned one-line install, or `npx @genclass/runtime@beta scan <url>
+  --json` for the visual checks alone; GenClass needs Claude Code or another MCP client on the developer's machine,
+  the chat app cannot run it).
+- **`init` writes the skill without the plugin.** `genclass-mcp init` now also writes `.claude/skills/genclass/SKILL.md`
+  into the project (the package's copy, resolved next to the built command, with a `genclass:init` marker line after
+  the frontmatter), so Claude Code loads the procedure on a project set up with `init` or `claude mcp add` alone. A
+  rerun replaces a file that carries the marker and leaves one that does not (yours, or edited), and says which;
+  `--no-skill` leaves the skill out; a `CLAUDE.md` without a `.claude/` folder still gets it under `.claude/skills/`.
+- **A repository-root copy for skill directories.** `skills/genclass/SKILL.md` is a byte-identical copy of the
+  plugin's skill, so `npx skills add genclass-dev/GenClass-lib` (skills.sh and directories that read a repository's
+  root `skills/` folder) finds it; `npm run sync -w @genclass/mcp` refreshes the copy and pins the install line in
+  both.
+- Tests: `test/manifests.test.ts` checks the skill's frontmatter (name, a one-line description of at most 1,024
+  characters with the symptom words early), that every `genclass_*` name in its body is a tool the server registers,
+  that the body has the procedure and the fallback and no em-dash, that the root copy is identical, and that the
+  instructions stay under 4,096 characters, put the symptom words in the first 500 and name the skill;
+  `test/cli.test.ts` covers the skill written by `init`, the rerun on a marked and an unmarked file, and `--no-skill`.
+
 ## 0.2.0 (2026-10-25)
 
 The `0.1.0` on npm (published 2026-10-25) is an earlier build: eight tools, no `genclass_scan`, no `GENCLASS_REPORT`.