⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.6.0

session-story

@nalaj⭐ 22 stars

Generate a self-contained HTML "session story" that links each prompt in a vibe coding session to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative. Use when the user asks for a session recap, changelog, review artifact, "what did Claude change", or wants to share a summary of a Claude Code session with a teammate or stakeholder.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 22 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Session Story

Generate a self-contained HTML "session story" that links each prompt in a vibe coding session to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative.

Session Story is a zero-dependency Node.js extraction and rendering pipeline for Claude Code. It parses the session transcript into typed JSON IR, cross-indexes prompts to the edits they caused, and deterministically compiles that into one HTML file with inline CSS and JS.

  • Open it and review — a GitHub-style diff, a turn-by-turn timeline, a plain-language narrative, and a report of what happened (commands, tests, errors, decisions, outcome), switchable in one page
  • Reconstruct intent, not just diffs — every edit is linked back to the prompt and turn that produced it, in order
  • Honest about blind spots — an interrupted tool call or a change made by a shell command is called out in the page header instead of silently omitted
  • One file, ready to share — no server, no build step, works straight from file://

Git tells you what changed. This tells you what happened.

Start page · Live example. The example is built from a synthetic demo session; the same page is checked in at examples/story.html.

Quick start

1. Install

The installer needs Node.js 22.20+ (check with node -v). For all your projects:

npx -y skills add nalaj/session-story --skill session-story --agent claude-code --global --copy --yes

For the current repository only, drop --global:

npx -y skills add nalaj/session-story --skill session-story --agent claude-code --copy --yes

This uses the open skills CLI. It copies only the session-story/ folder (the skill's instructions) into your agent's skills directory. When the skill runs, it fetches the matching version of the session-story CLI from npm through npx. The installer needs Node.js 22.20+ (the skills CLI's own requirement); the CLI runs on Node.js 18.18+ with zero npm runtime dependencies. To update, run the same command again. To remove it: npx skills remove session-story.

On older Node, this fetches Node 22 for the install only and changes nothing else (tested on macOS; for a lasting fix, upgrade Node, e.g. nvm install 22):

npx -y -p node@22 -p skills -- skills add nalaj/session-story --skill session-story --agent claude-code --global --copy --yes

As a Claude Code plugin. This repository is also a plugin marketplace. Inside Claude Code, run:

/plugin marketplace add nalaj/session-story
/plugin install session-story@session-story

On Claude Code 2.1.275 or later, one line does both: /plugin install session-story --marketplace nalaj/session-story. Claude Code installs only the session-story/ folder; the skill fetches the CLI with npx when it runs. As a plugin, the skill's command is /session-story:session-story. To update, run /plugin marketplace update session-story.

Or run the CLI yourself with npx session-story, or from a clone with node cli/bin/story.mjs.

2. Generate a story

Inside Claude Code, once installed:

/session-story

Or just ask: "make a story of this session for my teammate".

Claude extracts the current session, writes one-sentence summaries per turn, and opens the rendered page. See session-story/SKILL.md for the exact flow.

Older sessions work too. The story is built from the transcript Claude Code keeps on disk, not from the model's context, so a session from days ago is as good as the current one. Ask "make a session story for session <session-id>", or from the command line:

npx session-story extract --session <session-id> -o story.json

Session ids are the transcript file names in ~/.claude/projects/<slug>/ (the slug is the project path with / replaced by -), and /resume lists them too. Pass the full id, and --cwd <dir> when you are not in the project directory. Claude Code deletes transcripts after cleanupPeriodDays (30 by default), and edits made through the shell are recovered against today's git tree, so for an old session they can be misattributed if the files changed since.

3. Review, hand off, or share

Open the generated HTML file. Switch views depending on the audience — see below.

Need text instead of a page? export turns the same story into markdown: a pull request description by default, or with --template handoff a status to paste into a fresh Claude Code session (where things stand, turn by turn, git). It prints to stdout, so it pipes straight into pbcopy or gh pr create --body-file -.

Every session keeps its own page

Stories land in a .session-stories/ library in the project, one file per session, named by date, session id, and a slug of the title:

.session-stories/
  index.html                                   # the gallery
  index.json                                   # the manifest it is built from
  sessions.js                                  # the sidecar the switcher reads
  2026-09-14-eb076ea5-add-a-session-browser.html
  2026-09-12-a91c3f02-fix-the-diff-lens.html

index.html lists every session — date, title, outcome, summary, turns, files, lines added and removed, input and output tokens, and cost when Claude Code recorded it — with a filter box and time period filters (today, last 7 or 30 days, this or last calendar month, all time); the totals line adds up whichever sessions are shown. Every story page gets an "All sessions" link and a session switcher in its nav. Re-rendering a session overwrites its own file rather than piling up copies.

None of that costs the single-file property. The switcher is fed by sessions.js, loaded with <script src> (which works over file://, unlike fetch); a story mailed on its own simply has no sidecar, so the link and switcher stay hidden and the page is exactly as self-contained as before. Pass --library <dir> to put the library elsewhere, or -o <file> / --no-library for a single standalone page and nothing else.

Choose the right view

| View | Best for | Shows

// HOW IT'S BUILT

// FILES

6 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • session-story/SKILL.md10 KB0402dde815c1upstream ↗
    ---
    name: session-story
    description: Generate a self-contained HTML "session story" that links each prompt in a vibe coding session to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative. Use when the user asks for a session recap, changelog, review artifact, "what did Claude change", or wants to share a summary of a Claude Code session with a teammate or stakeholder.
    license: MIT
    metadata:
      version: "0.6.0"
      author: nalaj
      repository: https://github.com/nalaj/session-story
    ---
    
    # Session Story
    
    Turn the current (or a named) Claude Code session transcript into one
    shareable HTML file: git tells you what changed, this tells you what
    happened.
    
    The commands below run the `session-story` CLI from npm through `npx`
    (Node.js 18.18 or newer). The version is pinned to match this skill. Run
    every command from the user's project directory, so the session is found
    by the project's cwd.
    
    ## When to use
    
    The user asks for a session recap, a changelog of what Claude did, a
    review artifact for a teammate, or literally "make a story of this
    session" / "/session-story".
    
    ## Steps
    
    1. **Extract.** Run the CLI to pull the session transcript (and any
       subagent transcripts) into a Story IR JSON file:
       ```bash
       npx -y [email protected] extract -o <scratch>/story.json --brief
       ```
       Use `--session <id>` for a specific session or omit it (defaults to
       `--latest`) for the current one. Pass `--cwd <dir>` if the project
       differs from the current working directory. Sessions split by `/clear`
       are joined into one story automatically (`--no-chain` opts out), so the
       brief may carry turns from before the clear — `session.chain` lists the
       session ids included, oldest first. The `--brief` flag also
       prints a projection to stdout — **read only this projection, never the
       full story.json's hunks.** It carries, per turn: `prompt`,
       `edits[].{rel, kind, stats}`, `commands[].{command, category, ok,
       exit_code}`, `replies` (Claude's text replies, the last one longest), `errors[].{tool, target, message}`, and `plan.{approved,
       excerpt}` when a plan was proposed. An edit carrying `combined_into: N`
       is a file this turn changed through the shell whose diff git could only
       keep as the session's net change, shown on turn N — the turn did change
       code, so summarize it as a change, with zero stats rather than no edit.
       At the top level the brief carries
       `report.git` (branch and commit range, already extracted) and
       `report.dependencies` (manifest/install/config changes, already
       extracted), plus `hints` — a rough `outcome` guess from the last
       test/lint/build command and `failed_validations` excerpts to help you
       write resolutions. The brief also carries `metrics` (execution, code,
       validation, reads, usage — deterministic counts with `null` for anything
       the transcript did not record), `environment` (agent version and model
       ids) and, per turn, `duration_ms`, `tool_calls`, `output_tokens`,
       `share` (the turn's fraction of the session's output tokens, input
       tokens and duration, subagents included), `skills` (the skills the turn
       loaded) and `cache_breaks` (API calls that re-sent over 100k input
       tokens without the prompt cache). `metrics.execution.active_ms` is the
       session's time without idle gaps over five minutes; `metrics.usage`
       adds `cache_read_share` and `cache_breaks`. Use them to inform
       `report.outcome` and `outcome_note`; never restate or recompute them,
       and never write a number the brief shows as `null`. When one turn
       clearly dominated, you may say so in words ("most of the session went
       into the redesign"), never as a number or a cost. The same goes for
       skills and cache breaks: a turn summary may say "brainstormed the
       design first" or "re-read the whole context after a compaction", but
       the page already shows the names and counts.
    
    2. **Summarize and write the report.** Using the brief projection from
       step 1, write directly into `<scratch>/story.json` with the Edit tool
       (touch nothing else in the file):
       - `session.title`: a short, plain-language name for the session — at
         most 60 characters, no trailing period. Name what the session *did*
         ("Session library for stories", "Fix flaky auth test"); never paste
         or truncate the first prompt. This is the page heading. The brief's
         `session.ai_title` is the harness's own name for the session — good
         source material, but rewrite it when it is vague or off.
       - `session.summary`: one or two sentences, at most 240 characters —
         the description under the heading, also shown in the Report lens and
         the library index. Lead with the outcome ("X now does Y"), name what
         was left out if anything, and don't restate the intent; the longer
         framing belongs in `report.plan`.
       - `turns[N].summary`: one sentence of intent per turn, in the same
         order as the brief output.
       - `turns[N].answer`: for every turn whose brief `replies` is not empty,
         a short summary (1-3 sentences, at most 400 characters) of what
         Claude answered or reported back to that prompt — the findings, the
         result, or the question it asked — written from `replies`. Review and
         Story show it as Claude's output and fold the original replies away,
         so it must stand on its own. Report only what the replies say; leave
         it out for turns with no replies.
       - `report.plan`: 2-4 sentences on what the session set out to do.
         Use any `turns[N].plan.excerpt` as source material when present.
       - `report.decisions`: notable technical decisions worth calling out
         (e.g. "used the existing service instead of a new endpoint"). Empty
         array if none stand out.
       - `report.outcome`: one of `completed`, `partial`, `failed`, `blocked`
         — your judgement call, informed by `hints.outcome` and whether any
         `errors[]` or failed commands were left unresolved.
       - `report.outcome_note`: optional one-liner, most useful when the
         outcome isn't `completed` (what it's blocked on, what's left).
       - `errors[N].resolution` (nested under each turn): fill in only for
         errors that mattered to the outcome — how it was fixed, or why it
         was left as-is. Leave `null` for noise (e.g. a `grep` that found
         nothing).
    
    3. **Validate.**
       ```bash
       npx -y [email protected] validate <scratch>/story.json --strict
       ```
       If this reports missing summaries or report fields, go back to step 2.
    
    4. **Render.**
       ```bash
       npx -y [email protected] render <scratch>/story.json --open
       ```
       This writes a self-contained HTML file (no server, no dependencies)
       with four switchable views — Review (timeline + a summary of Claude’s
       output, the original replies folded + diff,
       for you), Diff
       (file tree, GitHub-style, for a teammate), Story (narrative cards with Claude's
       output, for a stakeholder), Report (plan, commands, tests, errors, decisions,
       dependencies, git state, outcome, and the session metrics with token
       usage) — and opens it.
    
       The page lands in the project's `.session-stories/` library as
       `<date>-<session-id>-<slug>.html`, so each session keeps its own file
       instead of overwriting the last one, and a regenerated
       `.session-stories/index.html` lists every session with a search box,
       time period filters, and token and cost totals. Each
       page also gets a session switcher in its nav. Re-rendering the same
       session overwrites its file and refreshes its index entry. Pass
       `--library <dir>` for another folder, or `-o <file>` / `--no-library`
       for a single standalone page with no library around it. On the index
       page, each card's hide button takes a session out of the list and the
       switcher in that browser; the page stays on disk, and "Hidden (N)"
       brings it back. A session that is still running shows as Live and
       can't be hidden. Only when the user asks you to delete sessions for
       real, run `npx -y [email protected] delete <session-id>...` (or `--all`). It
       deletes their pages and rewrites the index; an id prefix of 4 or more
       characters is enough. It refuses a running session unless `--force`
       is passed, and `--all` keeps running sessions.
    
    5. Report both paths — the story page and `.session-stories/index.html` —
       and the header numbers (turns, files, lines added/removed, outcome) to
       the user. If the story has token usage, report output tokens, the cost
       when recorded, and which turn used the most output tokens (the Report
       tab's "Where it went" ranks them).
    
    6. **Optional: markdown.** If the user asks for a PR description or a
       handoff for a fresh session, run
       ```bash
       npx -y [email protected] export <scratch>/story.json [--template handoff]
       ```
       and give them the output (or pipe it to `pbcopy`). Every line comes
       from story.json; paste it as is and add no claims of your own. Files
       outside the project are left out unless `--all-files` is passed.
    
    ## Limits
    
    - Claude Code sessions only (v1). Codex/Cursor/OpenCode are out of scope.
    - `Edit`, `Write`, and `NotebookEdit` calls are read from the transcript.
      Changes made through `Bash` (`sed -i`, a heredoc script, a formatter)
      carry no diff there, so they are recovered from git instead: the tree is
      compared from the commit the session started on through to the working
      tree, and each change is credited to the turn whose commands account for
      it. Those edits are labelled on the page, and come with git's limits — a
      file edited again after the session shows both changes, and a commit made
      during the session by someone else looks like the session's own. Pass
      `--no-git` to `extract` to skip the git pass entirely (this also skips
      `report.git`; `report.dependencies` is still extracted).
    - `report.plan`, `report.decisions`, `report.outcome`, `report.outcome_note`,
      and `errors[].resolution` are Claude's judgement calls, not something the
      extractor can verify — write them honestly from what the brief shows,
      including when the outcome isn't a clean success.
    - A story page copied out of `.session-stories/` loses only the "All
      sessions" link and the switcher (they stay hidden when the sibling
      `sessions.js` is missing); everything else still works from `file://`.
    - Requires Node.js 18.18+ and no other dependencies.
    
  • session-story/.claude-plugin/icon.png11 KBd9cac66f1c25upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • session-story/.claude-plugin/plugin.json582 Bc0d294a36580upstream ↗
    {
      "name": "session-story",
      "version": "0.6.0",
      "description": "Generate a self-contained HTML session story that links each prompt to the file edits it caused, with a review timeline, a GitHub-style diff view, and a plain-language narrative.",
      "author": {
        "name": "Nenad Alajbegovic",
        "url": "https://github.com/nalaj"
      },
      "homepage": "https://nalaj.github.io/session-story/",
      "repository": "https://github.com/nalaj/session-story",
      "license": "MIT",
      "keywords": ["claude-code", "agent-skill", "session-replay", "code-review", "diff"],
      "skills": ["./"]
    }
    
  • session-story/LICENSE1.0 KB7ed49f544da3upstream ↗
    MIT License
    
    Copyright (c) 2026 Nenad Alajbegovic
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
  • session-story/schemas/story.schema.json44 KBc1849ce57448upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/nalaj-session-story-session-story.md

// REPO STATS

22 stars