Launch the skill set: jam-fix, jam-proof, jam-annotate, jam-to-e2e (2.0.0)

.claude-plugin/plugin.json

@@ -1,13 +1,27 @@
 {
   "name": "jam",
-  "version": "1.23.2",
-  "description": "Jam's MCP is the fast lane between Jam recordings and your dev tools. Drop a Jam link into your coding agent and the whole recording – video, console, network, logs – arrives pre-packaged.",
-  "author": { "name": "Jam", "email": "support@jam.dev" },
+  "version": "2.0.0",
+  "description": "Jam recordings (video, console, network, logs) as context for your coding agent. Fix the bug in a Jam, prove a fix with a recorded Jam, mark up a screenshot, or turn a Jam into an end-to-end test.",
+  "author": {
+    "name": "Jam",
+    "email": "support@jam.dev"
+  },
   "homepage": "https://jam.dev",
   "repository": "https://github.com/jamdotdev/skills",
   "license": "MIT",
-  "keywords": ["jam", "bug-reports", "debugging", "mcp", "session-replay", "observability"],
+  "privacyPolicyUrl": "https://jam.dev/legal/privacy-policy",
+  "keywords": [
+    "jam",
+    "bug-reports",
+    "debugging",
+    "mcp",
+    "session-replay",
+    "observability"
+  ],
   "mcpServers": {
-    "Jam": { "type": "http", "url": "https://mcp.jam.dev/mcp" }
+    "Jam": {
+      "type": "http",
+      "url": "https://mcp.jam.dev/mcp"
+    }
   }
 }

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "jam",
-  "version": "1.23.2",
-  "description": "Investigate Jam bug reports using recordings, console logs, network requests, and user events.",
+  "version": "2.0.0",
+  "description": "Jam recordings (video, console, network, logs) as context for your coding agent. Fix the bug in a Jam, prove a fix with a recorded Jam, mark up a screenshot, or turn a Jam into an end-to-end test.",
   "author": {
     "name": "Jam",
     "email": "support@jam.dev"
@@ -21,8 +21,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Jam",
-    "shortDescription": "Investigate Jam bug reports",
-    "longDescription": "Investigate Jam bug reports using recordings, console logs, network requests, and user events.",
+    "shortDescription": "Fix, prove and test from Jam recordings",
+    "longDescription": "Jam recordings (video, console, network, logs) as context for your coding agent. Fix the bug in a Jam, prove a fix with a recorded Jam, mark up a screenshot, or turn a Jam into an end-to-end test.",
     "developerName": "Jam",
     "category": "Developer Tools",
     "capabilities": [
@@ -31,7 +31,7 @@
       "Write"
     ],
     "websiteURL": "https://jam.dev",
-    "defaultPrompt": "Investigate this Jam link and explain the likely root cause.",
+    "defaultPrompt": "Use $jam-fix to find the root cause of the bug in this Jam link.",
     "logo": "./assets/logo.png",
     "composerIcon": "./assets/logo.png",
     "privacyPolicyURL": "https://jam.dev/legal/privacy-policy",

.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "jam",
   "displayName": "Jam",
-  "version": "1.23.2",
-  "description": "Jam's MCP is the fast lane between Jam recordings and your dev tools. Drop a Jam link into Cursor and the whole recording – video, console, network, logs – arrives pre-packaged.",
+  "version": "2.0.0",
+  "description": "Jam recordings (video, console, network, logs) as context for Cursor. Fix the bug in a Jam, prove a fix with a recorded Jam, mark up a screenshot, or turn a Jam into an end-to-end test.",
   "author": {
     "name": "Jam",
     "email": "support@jam.dev"

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,25 @@
+name: Skill bug
+description: A skill did the wrong thing, or names a command or tool that doesn't exist.
+labels: [bug]
+body:
+  - type: dropdown
+    id: skill
+    attributes:
+      label: Skill
+      options: [jam-fix, jam-proof, jam-annotate, jam-to-e2e, plugin or MCP setup, other]
+    validations:
+      required: true
+  - type: input
+    id: agent
+    attributes:
+      label: Agent and version
+      placeholder: Claude Code 2.1, Cursor 2.4, Codex 0.50...
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what you expected
+      description: Paste the prompt you gave and the step where the agent went wrong. Redact tokens and customer data.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Jam product support
+    url: mailto:support@jam.dev
+    about: Questions about Jam itself, your account or billing.

.github/ISSUE_TEMPLATE/skill-request.yml

@@ -0,0 +1,18 @@
+name: Skill idea
+description: A job coding agents should do with a Jam, about QA, pull requests or proof of work.
+labels: [skill-request]
+body:
+  - type: textarea
+    id: job
+    attributes:
+      label: The job
+      description: 'What goes in and what comes out. For example, "PR diff in, five things a tester must check by hand out."'
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: What agents get wrong today
+      description: What happens when you ask an agent to do this without a skill?
+    validations:
+      required: true

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install check dependencies
+        run: npm ci
+
+      - name: Regression tests
+        run: npm test
+
+      - name: Repo checks
+        run: node scripts/check.mjs
+
+      - name: Plugin manifest
+        run: npx -y @anthropic-ai/claude-code@latest plugin validate . --strict
+
+      - name: skills.sh sees every skill
+        run: |
+          npx -y skills@latest add . --list </dev/null > skills.txt 2>&1
+          node scripts/check.mjs --skills-list skills.txt || { cat skills.txt; exit 1; }

.github/workflows/publish-mcp.yml

@@ -2,25 +2,25 @@ name: Publish to MCP Registry
 
 on:
   push:
-    tags: ["v*"]
+    tags: ["mcp-v*"]
   workflow_dispatch:
 
 jobs:
   publish:
     runs-on: ubuntu-latest
-    # MCP_PRIVATE_KEY is an environment secret; the environment only allows v* tags.
+    # MCP_PRIVATE_KEY is an environment secret; the environment only allows mcp-v* tags.
     environment: mcp-registry-publish
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Check server.json version matches tag
-        if: startsWith(github.ref, 'refs/tags/v')
+        if: startsWith(github.ref, 'refs/tags/mcp-v')
         run: |
-          TAG="${GITHUB_REF#refs/tags/v}"
+          TAG="${GITHUB_REF#refs/tags/mcp-v}"
           V="$(jq -r .version server.json)"
-          test "$TAG" = "$V" || { echo "tag v$TAG != server.json $V"; exit 1; }
+          test "$TAG" = "$V" || { echo "tag mcp-v$TAG != server.json $V"; exit 1; }
 
       - name: Install mcp-publisher
         run: curl -sL https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_linux_amd64.tar.gz | tar xz mcp-publisher

.gitignore

@@ -3,3 +3,4 @@ tasks/
 *.pem
 mcp-registry-auth
 .mcpregistry_*
+node_modules/

AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository. Humans: see [CONTRIBUTING.md](./CONTRIBUTING.md), which holds the rules every skill follows.
+
+## Layout
+
+- `skills/<name>/SKILL.md`: the skills. Each folder also has `agents/openai.yaml`.
+- `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `gemini-extension.json`: plugin manifests. `mcp.json` is the shared MCP server entry.
+- `server.json`: the MCP Registry entry `dev.jam/jam`. Its `version` is the Jam MCP server's, not the plugin's. Pushing an `mcp-v*` tag publishes it, and a published version is permanent. Never push a tag unless asked.
+- `rules/`: a Cursor rule that guards the Jam MCP delete tools.
+- `scripts/package-chatgpt.mjs`: the ChatGPT directory package. A skill that reads a Jam over MCP alone goes into its `SKILLS` list.
+- `docs/plugin.md`: plugin sign-in, what the MCP server can do, permissions. The tool list itself lives at jam.dev/mcp; do not copy it here.
+- `scripts/check.mjs`: repo checks, run by CI.
+
+## Invariants
+
+Run `node scripts/check.mjs` after any change. It prints each rule it finds broken, with the file.
+
+Also:
+
+- When you add, rename or remove a skill, update its README card, the CHANGELOG, and any skill that names it.
+- `jam-proof` and `jam-annotate` are also bundled in the Jam CLI. This repo is the source; tell the user the bundle needs a resync when you change them.
+- Only name `jam` CLI commands and MCP tools that ship today. Check with `jam agent-context`.
+- Skills are public. No internal paths, repo names, staging hosts or customer data.

CHANGELOG.md

@@ -2,9 +2,30 @@
 
 ## Unreleased
 
+## 2.0.0
+
+The plugin is now versioned on its own and no longer tracks the Jam MCP server version.
+
+- Renamed `investigate-bug` to `jam-fix`, because "fix this Jam" is what people ask for. It diagnoses first, changes code only when asked, and posts findings on the Jam when requested. Its description carries trigger phrases instead of slash-command syntax, and it covers the `jam` CLI when MCP is not connected.
+- Added `jam-proof`: record a change working and return a Jam link for the pull request. Moved from the Jam CLI bundle; this repo is now its source.
+- Added `jam-annotate`: mark up a screenshot with boxes, arrows, notes, redactions and blurs, and file it as a Jam. Moved from the Jam CLI bundle; this repo is now its source.
+- Added `jam-to-e2e`: turn a Jam into steps and an end-to-end test in the project's own runner and language, with first-class guidance for Playwright and tester-army/e2e. A flow Jam becomes a passing test that guards it; a bug Jam becomes a failing test for the fix to turn green.
+- Removed `jam-cli`. Each `jam-*` skill now carries its own install and sign-in steps, and `jam agent-context` prints the full command surface. The old skill named `jam get intents` and `jam get events` for user events; 1.29.0 ships `jam get user-events` and no `intents`.
+- Every skill now ends with a "Send feedback to Jam" section: the agent reports a wrong, stale or confusing Jam tool, command, doc or skill (or one that worked unusually well) with `jam feedback` or the `submitFeedback` MCP tool, without asking first, at most once per session. `docs/plugin.md` and the Cursor rule now match the server: no approval step, bodies up to 2,000 words.
+- Added `agents/openai.yaml` to every skill for the Codex skill picker.
+- Added `scripts/package-chatgpt.mjs`, which builds the ChatGPT directory package from `jam-fix` and `jam-to-e2e` with listing copy that names only those two.
+- Rewrote the README around the skills, with `npx skills add jamdotdev/skills` first. Moved sign-in, the MCP tool list and permissions to `docs/plugin.md`, and the release steps to `CONTRIBUTING.md`.
+- Added `CONTRIBUTING.md`, `AGENTS.md`, issue templates, and a CI workflow that checks skill frontmatter, README cards, manifest versions, Markdown links, the Claude Code plugin manifest, and that the skills CLI lists every skill.
+- Added `privacyPolicyUrl` to the Claude Code plugin manifest.
+- Cut the copies of the MCP tool guide. `docs/plugin.md` now summarizes what the server can do and links to jam.dev/mcp, the Cursor rule keeps only the confirm-before-delete rule and points at `jam-fix`, and `jam-fix` leaves filter and paging details to the tool descriptions.
+- Moved `jam-proof`'s cursor overlay and visible-Chrome details to `references/browser.md`.
 - Renamed the repository to `jamdotdev/skills`. Install commands and manifest URLs now point there; the `jam-plugins` marketplace name is unchanged.
 - Pointed the MCP website and docs links at `jam.dev/mcp`, and the CLI links at `jam.dev/cli`.
-- Added `server.json` for the official MCP Registry (`dev.jam/jam`) and a tag-triggered publish workflow.
+- Added `server.json` for the official MCP Registry (`dev.jam/jam`) and a publish workflow triggered by `mcp-v*` tags. Its version follows the Jam MCP server, not the plugin.
+- Validate skill frontmatter with a YAML parser and require exact discovery entries, so malformed skills cannot pass CI by appearing in a warning.
+- Keep local annotation requests local and require posting intent for Jam comments, mentions, pull requests and tickets.
+- Give CLI investigations both client and server failures, and require an explicit browser or window target for proof recordings.
+- Use the project's browser mode for regression tests and isolated checkouts for new before-and-after recordings.
 
 ## 1.23.2
 
@@ -14,7 +35,7 @@
 
 ## 1.5.0
 
-- Synced with deployed Jam MCP 1.23.2 at [619c85f885c3](https://github.com/jamdotdev/apiofjam/commit/619c85f885c3782f77a49ef0bc68c4d87222d097), verified through production server initialization and its 35-tool inventory.
+- Synced with deployed Jam MCP 1.23.2, verified through production server initialization and its 35-tool inventory.
 - Added `searchJams` guidance and marked `listJams` deprecated. Added `submitFeedback` with exact-text approval, privacy limits, and at most one submission per session.
 - Corrected event filter examples to arrays and documented cursor pagination, total counts, and network response-body limits.
 - Documented video thumbnail links and CLI proof capture guidance.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+Thanks for helping. This repo holds small agent skills about Jams (screen recordings with the console, network and user actions attached), QA, pull requests and proof of work. Read the rules below before you open a pull request; most review comments come from them.
+
+## The rules
+
+1. **One job per skill.** A skill does one thing well. Two jobs are two skills.
+2. **The name tells the truth.** A skill named `jam-*` needs a Jam account. A skill without `jam` in its name works fully without Jam, and mentions Jam at most once, in a line labeled "With Jam" next to the alternatives.
+3. **No pitch.** No sales copy inside a `SKILL.md`. Jam lives in the README.
+4. **Do what agents can't, or give them structure they lack.** Visuals for humans (proof video, marked-up screenshots, diagrams) and evidence structure (claim, how it was verified, evidence, gaps). Not things agents already do well, such as reading a HAR file.
+5. **Claim only what ships.** Every command, flag and tool a skill names must exist in the released Jam CLI or MCP server today. Check with `jam agent-context` or the [MCP docs](https://jam.dev/mcp).
+6. **Use the project's tools.** A skill uses the project's existing test runner, browser driver or setup, and falls back to Playwright when there is none.
+
+## Anatomy of a skill
+
+```
+skills/<name>/
+  SKILL.md              required
+  agents/openai.yaml    required: Codex picker metadata
+  references/           optional: depth the agent loads on demand
+  scripts/              optional: scripts the skill runs
+```
+
+- **Name:** 2 or 3 words, kebab-case, verb first (`prove-change`) or `x-to-y` (`jam-to-e2e`). No single words, no `verify-*`. The folder name equals the `name` in the frontmatter.
+- **Description:** what it does, then when to use it, with the phrases a user would type ("Use when the user pastes a jam.dev link..."). The agent decides to load the skill from this line alone. 1024 characters at most.
+- **Length:** keep `SKILL.md` under about 200 lines. Move detail to `references/` and link it from the step that needs it.
+- **Style:** imperative, concrete, no filler. Show the command, not a description of the command. Say what to do when a step fails.
+- **Feedback:** every `jam-*` skill ends with the same `## Send feedback to Jam` section. Copy it from an existing skill; CI fails if it differs.
+- **Secrets:** never ask the agent to write a token to a file. Use environment variables.
+- **Descriptions use the user's words, not ours.** Write what people type: "jam link", "bug recording", "screen recording", "repro video", "proof for the PR". Say what a Jam is the first time a description names it; the model may never have heard of Jam.
+- **Jam terms, in prose only:** `Jam` is always capitalized and never a verb (record a Jam, share a Jam). The hierarchy is workspace > folder > Jam; a person with a seat is a member. Write `Sharepage`, `Recording Link`, `Jam MCP`, `Jam CLI`, and `Model Context Protocol (MCP)` on first mention in a page. You capture a screenshot and record a video.
+- **Claims:** no "only", "first", "best" or guarantees. State what the skill does and its limits.
+
+## Test a skill locally
+
+```bash
+npm ci                                 # install the locked YAML validator
+node scripts/check.mjs                  # the same checks CI runs
+npm test                                # validation and package regressions
+npx skills add . --list                 # what skills.sh will see
+claude --plugin-dir .                   # load the plugin in Claude Code
+```
+
+Then run the skill on a real task in at least one agent and say which one in the pull request. For a `jam-*` skill, include the Jam link it produced.
+
+## Pull requests
+
+- One skill per pull request. Maintainers may ship a coordinated release of several in one.
+- Add a line under **Unreleased** in [CHANGELOG.md](./CHANGELOG.md).
+- A new skill also needs a card in [README.md](./README.md). CI fails without one.
+
+## Releasing (maintainers)
+
+Two things ship from this repo, each with its own version.
+
+**The plugin.** Its version is the same in `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json` and `gemini-extension.json`; CI checks this.
+
+1. Bump the version in those four files and move **Unreleased** in the changelog under the new version.
+2. Merge to `master` and push a `v<version>` tag.
+
+**The MCP Registry entry.** `server.json` describes the remote Jam MCP server at `mcp.jam.dev`, so its `version` is the server's, not the plugin's. When the server releases:
+
+1. Set `version` in `server.json` to the server's version and merge to `master`.
+2. Push an `mcp-v<version>` tag. `.github/workflows/publish-mcp.yml` publishes `server.json` to the registry as `dev.jam/jam`. A registry version can't be changed after it is published.
+
+### ChatGPT directory package
+
+The ChatGPT directory takes the skills that read a Jam over MCP alone: `jam-fix` and `jam-to-e2e`, without their `references/`. The CLI install steps (in `jam-proof`, `jam-annotate` and the `references/cli.md` files) download and run code, which fails ChatGPT's external-code review, so a skill meant for ChatGPT keeps its install steps in `references/` and is added to `SKILLS` in `scripts/package-chatgpt.mjs`. Build the package from `master` after the merge: the packaged skills link to `references/` on GitHub.
+
+```bash
+node scripts/package-chatgpt.mjs ../jam-chatgpt-<version>.zip
+```
+
+The script copies those two skills with the plugin identity, connection and assets, and rewrites the listing description so it names only what the package contains.
+
+Update the existing app entry with this package. Do not create a new app through **Upload New**; that loses the saved identity and connection settings.