From 239f97ad83dc87670d76ad5b8c3a9cb3f2e62752 Mon Sep 17 00:00:00 2001 From: Tomasz Cichocinski Date: Mon, 26 Oct 2026 13:36:13 +0100 Subject: [PATCH 1/2] README follows Jam's docs writing rules --- CHANGELOG.md | 1 + README.md | 34 ++++++++++++++++++++-------------- 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e37160c..a5be612 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Unreleased - `jam`, `jam-to-tasks`, `jam-to-ticket` and `jam-proof-table` handle screenshot, replay and silent Jams, and Jams that raise several problems: the router reads the transcript and a silent Jam's description, a task cites its field when there is no timestamp, a screenshot counts as proof, and an existing ticket covers only its own problem. +- The README follows Jam's docs writing rules: no semicolons, bold only for UI labels, Jam MCP named with Model Context Protocol on first mention, and the requirements as a list. - Added `jam`: type `/jam` and what you want, and it routes to the matching Jam skill. It also catches a bare jam.dev link or a vague ask, reads the Jam, and routes by what it holds; a clear ask still goes straight to its own skill. - The README lists skills as one bulleted list instead of a table plus a section per skill. `scripts/check.mjs` checks for the list entry. - The skills no longer download and run an installer. If `jam` is missing, they ask you to install it from jam.dev/cli. Addresses the remote-code-execution audit finding on `jam-proof` and `jam-annotate`. diff --git a/README.md b/README.md index 18260bd..bee8fe3 100644 --- a/README.md +++ b/README.md @@ -28,30 +28,36 @@ Then paste a Jam link and say what you want: - "make a ticket for this jam" - "record a jam showing it works" -A Jam is a screen recording with the console logs, network requests and user actions already attached, on one link. Bug reports, feedback walkthroughs and demos already live there. These skills let your agent read them, and record its own Jam when it's done, so you check the result by watching it. +A Jam is a screen recording or screenshot with the console logs, network requests and user actions attached, on one link. A bug report, a feedback walkthrough and a demo each fit in one. These skills let your agent read a Jam, and record its own when it's done, so you check the result by watching it. Works with Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, OpenCode and [every agent skills.sh supports](https://skills.sh). Add `--skill jam-fix` to install one skill. ## Skills -- [jam](./skills/jam/SKILL.md): "Take a look at this jam." Paste a bare link or a vague ask and it **reads the Jam**, then hands it to the skill that fits: a narrated walkthrough to `jam-to-tasks`, a bug to `jam-fix`. A clear ask goes straight to its own skill. `/jam` works too. -- [jam-fix](./skills/jam-fix/SKILL.md): "Fix this jam.dev link." Reads the recording's **console errors**, **failed requests**, **user steps**, **frames** and **transcript**, then writes the **root cause with evidence**. Changes code only when you ask. -- [jam-proof](./skills/jam-proof/SKILL.md): "Record a Jam showing it works." Records the change working and hands back a **Jam link for the pull request**, with **console** and **network** attached. Headless Chrome by default: it records the page, not your screen. -- [jam-annotate](./skills/jam-annotate/SKILL.md): "Mark what's broken and file it." Turns a screenshot into a Jam that points at the problem: **boxes**, **arrows**, **notes**, **redactions** and **blurs**, with the retina math done right. -- [jam-to-e2e](./skills/jam-to-e2e/SKILL.md): "Write an e2e test for this Jam." Turns a Jam into a test in **your own runner and language**, with first-class guidance for **Playwright** and [tester-army/e2e](https://github.com/tester-army/e2e). A Jam of a flow becomes a test that **guards it**. A Jam of a bug becomes a **failing test**, so the fix has something to turn green. -- [jam-to-tasks](./skills/jam-to-tasks/SKILL.md): "Do what I said in this jam." Reads a narrated walkthrough to the end and lists **every change asked for**, each with its **timestamp**, **frame** and **quote**, then works the list: done, deferred with a reason, or asked about. -- [jam-to-ticket](./skills/jam-to-ticket/SKILL.md): "Make a ticket for this jam." Files a Jam into **Linear**, **GitHub Issues** or **Jira** with steps, expected result, the key frame and errors, after checking it is **not ticketed already**. -- [jam-proof-table](./skills/jam-proof-table/SKILL.md): "Give me the jams for each fix." Ends a batch of work with **one table**: each claim, its status, and the Jam that shows it. Names and files those Jams so they can be **found later**. -- [video-to-jam](./skills/video-to-jam/SKILL.md): "Split this recording by bug." Turns an MP4, a Loom download or a long call into **one Jam per issue**, cut where the speaker moves on, titled and filed in a folder. +- [jam](./skills/jam/SKILL.md): "Take a look at this jam." Paste a bare link or a vague ask and it reads the Jam, then hands it to the skill that fits: a list of changes to `jam-to-tasks`, a bug to `jam-fix`. A clear ask goes straight to its own skill. `/jam` works too. +- [jam-fix](./skills/jam-fix/SKILL.md): "Fix this jam.dev link." Reads the recording's console errors, failed requests, user steps, frames and transcript, then writes the root cause with evidence. Changes code only when you ask. +- [jam-proof](./skills/jam-proof/SKILL.md): "Record a Jam showing it works." Records the change working and hands back a Jam link for the pull request, with console and network attached. Headless Chrome by default: it records the page, not your screen. +- [jam-annotate](./skills/jam-annotate/SKILL.md): "Mark what's broken and file it." Turns a screenshot into a Jam that points at the problem: boxes, arrows, notes, redactions and blurs, with the retina math done right. +- [jam-to-e2e](./skills/jam-to-e2e/SKILL.md): "Write an e2e test for this Jam." Turns a Jam into a test in your own runner and language, with first-class guidance for Playwright and [tester-army/e2e](https://github.com/tester-army/e2e). A Jam of a flow becomes a test that guards it. A Jam of a bug becomes a failing test, so the fix has something to turn green. +- [jam-to-tasks](./skills/jam-to-tasks/SKILL.md): "Do what I said in this jam." Reads a narrated walkthrough to the end and lists every change asked for, each with its timestamp, frame and quote, then works the list: done, deferred with a reason, or asked about. +- [jam-to-ticket](./skills/jam-to-ticket/SKILL.md): "Make a ticket for this jam." Files a Jam into Linear, GitHub Issues or Jira with steps, expected result, the key frame and errors, after checking that no ticket exists for it yet. +- [jam-proof-table](./skills/jam-proof-table/SKILL.md): "Give me the jams for each fix." Ends a batch of work with one table: each claim, its status, and the Jam that shows it. Names and files those Jams so they can be found later. +- [video-to-jam](./skills/video-to-jam/SKILL.md): "Split this recording by bug." Turns an MP4, a Loom download or a long call into one Jam per issue, cut where the speaker moves on, titled and filed in a folder. ## Requirements -Every skill needs a free [Jam](https://jam.dev?utm_source=github&utm_medium=readme&utm_campaign=skills) account. `jam-fix` and `jam-to-e2e` read a Jam through the Jam MCP server or the [Jam CLI](https://jam.dev/cli); `jam-proof` and `jam-annotate` create Jams, which needs the CLI. `jam-to-tasks`, `jam-to-ticket`, `jam-proof-table` and `video-to-jam` use the CLI; `video-to-jam` also needs ffmpeg and a local transcriber such as Whisper. Install the CLI from [jam.dev/cli](https://jam.dev/cli); a skill signs in when it needs it. In CI or a cloud agent, set `JAM_TOKEN` to a [personal access token](https://jam.dev/docs/personal-access-tokens). Window and display capture in `jam-proof` need macOS or Linux (X11); its default, recording a headless browser, needs only Chrome. +Every skill needs a free [Jam](https://jam.dev?utm_source=github&utm_medium=readme&utm_campaign=skills) account. Beyond that: + +- `jam`, `jam-fix` and `jam-to-e2e` read a Jam through Jam MCP, Jam's Model Context Protocol (MCP) server, or the [Jam CLI](https://jam.dev/cli). +- The other skills need the Jam CLI. Install it from [jam.dev/cli](https://jam.dev/cli). A skill signs in when it needs to. +- `video-to-jam` also needs ffmpeg and a local transcriber such as Whisper. +- In CI or a cloud agent, set `JAM_TOKEN` to a [personal access token](https://jam.dev/docs/personal-access-tokens). +- `jam-proof` records a headless Chrome by default, which needs only Chrome. Window and display capture need macOS or Linux (X11). ## Install as a plugin -The plugin installs every skill, connects the [Jam MCP server](./docs/plugin.md) and updates itself. Use the plugin or `npx skills add`, not both, or the agent sees every skill twice. +The plugin installs every skill, connects [Jam MCP](./docs/plugin.md) and updates itself. Use the plugin or `npx skills add`, not both, or the agent sees every skill twice.
Claude Code @@ -111,11 +117,11 @@ Run `/mcp auth Jam` once to sign in. To test a checkout, run `gemini extensions
-Sign-in, tokens, what the MCP server can do, and permissions: [docs/plugin.md](./docs/plugin.md). +Sign-in, tokens, what Jam MCP can do, and permissions: [docs/plugin.md](./docs/plugin.md). ## Contribute -Bug in a skill, or a skill you want? [Open an issue](https://github.com/jamdotdev/skills/issues/new/choose). Pull requests are welcome; [CONTRIBUTING.md](./CONTRIBUTING.md) is short. +Bug in a skill, or a skill you want? [Open an issue](https://github.com/jamdotdev/skills/issues/new/choose). Pull requests are welcome, and [CONTRIBUTING.md](./CONTRIBUTING.md) is short. --- From f8438df8458025faa2977d24cfb89cd5a9bb3623 Mon Sep 17 00:00:00 2001 From: Tomasz Cichocinski Date: Mon, 26 Oct 2026 13:37:42 +0100 Subject: [PATCH 2/2] README reads for people: skills grouped by what you give and get, one plain line each --- CHANGELOG.md | 2 +- README.md | 38 +++++++++++++++++++++----------------- 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a5be612..3fb4616 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ ## Unreleased - `jam`, `jam-to-tasks`, `jam-to-ticket` and `jam-proof-table` handle screenshot, replay and silent Jams, and Jams that raise several problems: the router reads the transcript and a silent Jam's description, a task cites its field when there is no timestamp, a screenshot counts as proof, and an existing ticket covers only its own problem. -- The README follows Jam's docs writing rules: no semicolons, bold only for UI labels, Jam MCP named with Model Context Protocol on first mention, and the requirements as a list. +- The README groups the skills by what you hand the agent and what you get back, with one plain line each, and lists the requirements one per line. It follows Jam's docs writing rules: no semicolons, and bold only for UI labels. - Added `jam`: type `/jam` and what you want, and it routes to the matching Jam skill. It also catches a bare jam.dev link or a vague ask, reads the Jam, and routes by what it holds; a clear ask still goes straight to its own skill. - The README lists skills as one bulleted list instead of a table plus a section per skill. `scripts/check.mjs` checks for the list entry. - The skills no longer download and run an installer. If `jam` is missing, they ask you to install it from jam.dev/cli. Addresses the remote-code-execution audit finding on `jam-proof` and `jam-annotate`. diff --git a/README.md b/README.md index bee8fe3..87c5e74 100644 --- a/README.md +++ b/README.md @@ -28,32 +28,36 @@ Then paste a Jam link and say what you want: - "make a ticket for this jam" - "record a jam showing it works" -A Jam is a screen recording or screenshot with the console logs, network requests and user actions attached, on one link. A bug report, a feedback walkthrough and a demo each fit in one. These skills let your agent read a Jam, and record its own when it's done, so you check the result by watching it. +A Jam is a screen recording or screenshot with the console logs, network requests and user actions attached, on one link. You'd record one for a bug report, a feedback walkthrough or a demo. These skills let your agent read a Jam, and record its own when it's done, so you check the result by watching it. Works with Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, OpenCode and [every agent skills.sh supports](https://skills.sh). Add `--skill jam-fix` to install one skill. ## Skills -- [jam](./skills/jam/SKILL.md): "Take a look at this jam." Paste a bare link or a vague ask and it reads the Jam, then hands it to the skill that fits: a list of changes to `jam-to-tasks`, a bug to `jam-fix`. A clear ask goes straight to its own skill. `/jam` works too. -- [jam-fix](./skills/jam-fix/SKILL.md): "Fix this jam.dev link." Reads the recording's console errors, failed requests, user steps, frames and transcript, then writes the root cause with evidence. Changes code only when you ask. -- [jam-proof](./skills/jam-proof/SKILL.md): "Record a Jam showing it works." Records the change working and hands back a Jam link for the pull request, with console and network attached. Headless Chrome by default: it records the page, not your screen. -- [jam-annotate](./skills/jam-annotate/SKILL.md): "Mark what's broken and file it." Turns a screenshot into a Jam that points at the problem: boxes, arrows, notes, redactions and blurs, with the retina math done right. -- [jam-to-e2e](./skills/jam-to-e2e/SKILL.md): "Write an e2e test for this Jam." Turns a Jam into a test in your own runner and language, with first-class guidance for Playwright and [tester-army/e2e](https://github.com/tester-army/e2e). A Jam of a flow becomes a test that guards it. A Jam of a bug becomes a failing test, so the fix has something to turn green. -- [jam-to-tasks](./skills/jam-to-tasks/SKILL.md): "Do what I said in this jam." Reads a narrated walkthrough to the end and lists every change asked for, each with its timestamp, frame and quote, then works the list: done, deferred with a reason, or asked about. -- [jam-to-ticket](./skills/jam-to-ticket/SKILL.md): "Make a ticket for this jam." Files a Jam into Linear, GitHub Issues or Jira with steps, expected result, the key frame and errors, after checking that no ticket exists for it yet. -- [jam-proof-table](./skills/jam-proof-table/SKILL.md): "Give me the jams for each fix." Ends a batch of work with one table: each claim, its status, and the Jam that shows it. Names and files those Jams so they can be found later. -- [video-to-jam](./skills/video-to-jam/SKILL.md): "Split this recording by bug." Turns an MP4, a Loom download or a long call into one Jam per issue, cut where the speaker moves on, titled and filed in a folder. +You don't need to remember these names. Paste a Jam link, say what you want, and your agent picks the skill. +### Give your agent a Jam -## Requirements +- [jam](./skills/jam/SKILL.md): "Take a look at this jam." For a link with no instructions. It reads the Jam and picks the skill below that fits. +- [jam-fix](./skills/jam-fix/SKILL.md): "Fix this jam." Finds the root cause from the errors, failed requests and steps in the recording, and shows the evidence. It changes code only when you ask. +- [jam-to-tasks](./skills/jam-to-tasks/SKILL.md): "Do what I said in this jam." Turns your feedback into a numbered to-do list, each item tied to the moment you said it, then works through it. +- [jam-to-e2e](./skills/jam-to-e2e/SKILL.md): "Write a test for this jam." Writes an end-to-end test with your project's own test setup. A Jam of a bug becomes a test that fails until the fix lands. +- [jam-to-ticket](./skills/jam-to-ticket/SKILL.md): "Make a ticket for this jam." Files it in Linear, GitHub Issues or Jira with the steps, a frame from the recording and the errors, unless a ticket already exists. +- [video-to-jam](./skills/video-to-jam/SKILL.md): "Split this recording by bug." Turns an MP4, a Loom download or a long call into one Jam per issue. + +### Get a Jam back -Every skill needs a free [Jam](https://jam.dev?utm_source=github&utm_medium=readme&utm_campaign=skills) account. Beyond that: +- [jam-proof](./skills/jam-proof/SKILL.md): "Record a jam showing it works." Records the change working and gives you a Jam link for the pull request. +- [jam-annotate](./skills/jam-annotate/SKILL.md): "Mark what's broken and share it." Draws boxes, arrows and notes on a screenshot, blurs anything private, and shares it as a Jam. +- [jam-proof-table](./skills/jam-proof-table/SKILL.md): "Give me the jams for each fix." After a batch of work, one table: each claim, whether it works, and the Jam that shows it. + +## Requirements -- `jam`, `jam-fix` and `jam-to-e2e` read a Jam through Jam MCP, Jam's Model Context Protocol (MCP) server, or the [Jam CLI](https://jam.dev/cli). -- The other skills need the Jam CLI. Install it from [jam.dev/cli](https://jam.dev/cli). A skill signs in when it needs to. -- `video-to-jam` also needs ffmpeg and a local transcriber such as Whisper. -- In CI or a cloud agent, set `JAM_TOKEN` to a [personal access token](https://jam.dev/docs/personal-access-tokens). -- `jam-proof` records a headless Chrome by default, which needs only Chrome. Window and display capture need macOS or Linux (X11). +- A free [Jam](https://jam.dev?utm_source=github&utm_medium=readme&utm_campaign=skills) account. +- The [Jam CLI](https://jam.dev/cli). A skill signs in when it needs to. `jam`, `jam-fix` and `jam-to-e2e` can read a Jam through Jam MCP instead, the Model Context Protocol (MCP) server the plugin connects. +- For `video-to-jam`: ffmpeg and a local transcriber such as Whisper. +- In CI or a cloud agent: a [personal access token](https://jam.dev/docs/personal-access-tokens) in `JAM_TOKEN`. +- For `jam-proof`: recording a web page needs only Chrome. Recording a window or the whole screen needs macOS or Linux (X11). ## Install as a plugin