ckb/.agents/skills/ckb-add-conversation/SKILL.md
Michał Kopeć aaeabf3071 Template 1.22.1: hooks start from the project root
Claude Code runs a hook in the session's current directory, so the
autosave Stop hook's relative script path followed the shell into
subfolders: a session working inside a nested repo saved its transcript
there. autosave_hook.py and start_hook.py now write
`cd "${CLAUDE_PROJECT_DIR:-.}" && ...`; --check flags an entry from
before the fix as outdated and --install replaces it, keeping other
hooks. Smoke test fires both installed hooks from a subfolder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 19:34:30 +01:00

13 KiB


name: ckb-add-conversation description: Save the current Claude Code conversation (or an earlier session of this project) verbatim into raw/saved-conversations// as the original JSONL plus a readable Markdown rendering, and search those saved conversations when asked what was discussed or instructed before. Saved conversations never enter retrieval or the wiki on their own. Use for "save this conversation", "save the chat", "archive this session", "keep a copy of our talk", for "did we discuss X", "what did I tell you about X", "what did I ask you to do about Y last time", "find the conversation where ...", and for naming a session ("rename this conversation to X", "call this session X") and the session-start title line, and for toggling the switches: "save conversations automatically", "turn on/off conversation autosave", "stop saving every conversation", "stop telling me the title", "show me the title again".

Add conversation skill

Purpose

Verbatim copies live in raw/saved-conversations/, outside the cascade: ckb-retrieve never reads them, lint never fingerprints them, and nothing in them reaches wiki/ until the user copies the .md into raw/inbox/ and says "Ingest". Never save because a session "seems important"; the only automatic path is the autosave switch below.

Where transcripts come from

Claude Code writes every session as a JSONL file:

<config>/projects/<encoded-cwd>/<session-id>.jsonl

<config> is $CLAUDE_CONFIG_DIR when set, else ~/.claude. <encoded-cwd> is the KB's absolute path with every character that is not a letter or digit replaced by - (/home/me/My KB → -home-me-My-KB). The file still being written is the current session, so "most recently modified" is the right default. The script does this lookup; the fallback section shows it by hand.

How to run this skill — Save

Step 1 — Confirm the target

If the user said "save this conversation", the target is the current session. If they named an earlier one ("save yesterday's session", "the one about billing"), list candidates and let them pick:

<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --list

Each row shows a session-id prefix, last activity, size, user-turn count and the title. Pass the chosen prefix with --session <prefix>.

Step 2 — Say what will be captured

Before writing, tell the user in one or two sentences that the transcript is verbatim: every message, every tool call, and the first few hundred characters of every tool result, including file contents the agent printed during the session. It will be a tracked file in the repo. If the session touched anything secret-looking (.env, keys, tokens, credentials, personal data), say so and let them decide. Thinking blocks are never rendered into the Markdown but remain in the JSONL copy.

Anything the user wrapped in <private>…</private> is redacted by the script in both files (an unclosed tag redacts to the end of that message). Only the span itself is removed: if the agent repeated a private value in a reply or a tool call, that copy stays, so mention it when you know it happened. After saving, ckb-lint check 15 (lint_report.py --secrets) flags credential shapes in the saved files before they are committed.

Step 3 — Save

<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py            # current session
<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --session <prefix>
<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --title "Short name"   # override the title for this save only

The script writes, under raw/saved-conversations/<today>/:

  • <slug>_<sid8>.jsonl — byte-for-byte copy of the transcript
  • <slug>_<sid8>.md — readable rendering: a metadata table (session id, author from the repo's git identity, start and last-message times, working directory, branch, Claude Code version, turn counts, sha256 of the JSONL), then the exchange in order. User and assistant text verbatim; tool calls as one-line > **Tool:** notes; tool results truncated; harness <system-reminder> blocks stripped; thinking omitted.

and updates raw/saved-conversations/index.md (one row per session, newest first; re-saving a session that continued replaces its files and its row).

The title, and so the slug, is the first of: --title; the title stored for the session by --set-title (see below); Claude Code's own title for the session (/rename, else its AI title); the first user line. Re-saving a session under a changed title replaces the earlier pair of files for that session in the same day folder, so a rename never leaves orphans. --author "Name <email>" overrides the git identity. --dry-run shows the paths without writing.

Step 4 — Report and log

Report the two paths, the title and the turn counts the script printed. Then append a line to today's workload/ summary naming the saved file. Nothing under wiki/ changed, so wiki/log.md is not touched — Rule B covers the wiki only.

If the user wants the conversation's content in the wiki, say so plainly: copy the .md into raw/inbox/ and say "Ingest". Do not copy it for them unless they ask.

Without Python

Resolve <python> as AGENTS.md §3 describes. If no interpreter runs, copy the JSONL by hand and skip the Markdown rendering:

CFG="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
PROJ="$CFG/projects/$(pwd | sed 's/[^A-Za-z0-9]/-/g')"
SRC=$(ls -t "$PROJ"/*.jsonl | head -1)                      # current session
DEST="raw/saved-conversations/$(date +%F)"; mkdir -p "$DEST"
cp "$SRC" "$DEST/conversation_$(basename "$SRC" .jsonl | cut -c1-8).jsonl"

Add a row to raw/saved-conversations/index.md by hand (create the file with the header the script would write, see INDEX_HEADER in the script). Tell the user once that the readable .md can be produced later by re-running the script with --from <that jsonl> once Python is available.

Naming a session

Rule E names a new session itself: a short title derived from the first message (or the one the user put there), stored per machine so the Stop hook and every later save pick it up:

<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --set-title "Billing cut-over plan"
<python> .agents/skills/ckb-add-conversation/scripts/save_conversation.py --set-title "..." --session <prefix>   # an earlier session

It writes tmp/conversation-titles/<session-id>.title (gitignored, like the hook that reads it) and exits without saving. The same command serves "rename this conversation to X" mid-session; if a copy of the session was already saved today, save again so the files and index row follow the new name. The title also heads the session's block in the workload note.

The user is never asked. The first reply opens with one line — Conversation title: <title> — say "rename this conversation to …" to change it. — controlled by conversations.announce_title (default true; absent means true). "Stop telling me the title" / "show me the title again" flips it the same way as autosave below — change only that key. The title is still derived and stored with it off; only the reminder line goes.

The autosave switch

ckb.yaml carries:

conversations:
  autosave: false         # true: save every session's transcript at session end without asking
  announce_title: true    # true: the first reply of every session states the chosen title and how to rename it

With autosave: true, Rule E saves the conversation at session end without asking and reports the path in one line; the workload note names the file as usual. With false or no block at all, the agent asks once, as described above. The switch is repo-level and committed, so everyone working in this KB gets the same behaviour.

Toggling it on request ("save conversations automatically", "turn off autosave"): read ckb.yaml, change only the autosave value, write the file back with everything else byte-for-byte intact (template:, kb_modules: and routines: belong to other skills). Add the conversations: block if it is missing. Confirm the new value in one line, then run the per-machine check described below and ask about the hook. When turning it on, say once that every session will become a tracked file in the repo, including whatever file contents and command output the agent prints — the caveat in Save Step 2 no longer gets a chance to be said per session.

The per-machine half. The agent-side rule saves at session end only when the agent reaches that step; a session killed mid-turn is not saved. A Claude Code Stop hook closes that gap: it runs save_conversation.py --from-hook after every turn, and the script updates the same files in place. The hook reads the transcript path from the hook's stdin JSON, so the right session is saved even when several run in parallel.

Hooks are machine configuration, not template: they live in .claude/settings.local.json, which is gitignored. So the switch in ckb.yaml travels with the repo, and every machine that opens the repo has to be brought in line separately. scripts/autosave_hook.py does that:

<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --check     # exit 0 = consistent, 1 = action needed
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --install   # merge the hook into settings.local.json
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --remove    # take it out, leave the rest intact

--install takes --python <cmd> so the hook command uses the interpreter that actually works on this machine (resolve <python> as AGENTS.md §3 describes and pass it). It merges into an existing file and refuses to touch one that is not valid JSON. The command starts with cd "${CLAUDE_PROJECT_DIR:-.}", because Claude Code runs a hook in the session's current directory: without it, a session whose shell had moved into a subfolder (a nested repo, say) saved its transcript there. --check reports an entry installed before 1.22.1 as outdated, and --install replaces it in place.

Never change machine configuration silently. Two moments call for the check, and both end in a question, not an action:

  1. Session start (Rule E, via session_start.py) — when autosave: true, --check runs. On exit 1 tell the user in one line what is out of line and ask whether to install (or remove) the hook on this machine. Apply only on a yes. If they decline, do not ask again this session; autosave then relies on the session-end rule alone, which is worth saying once.
  2. Toggling the switch — right after flipping autosave in ckb.yaml, run --check and ask the same question, so the switch and this machine agree from the first session. Turning autosave off and leaving the hook installed would keep saving every session, which is exactly what the user just asked to stop.

Without Python the hook cannot run either, so there is nothing to install: say so once and rely on the session-end rule.

How to run this skill — Recall

Triggers: "did we discuss X", "have we talked about X before", "what did I tell you about X", "what instructions did I give about Y", "what did I ask you to do last time", "find the conversation where ...".

  1. Read raw/saved-conversations/index.md. If it is missing or empty, say no conversations have been saved and stop — do not fall back to workload/ or the wiki as if they were transcripts (they are summaries, offer them as such).
  2. Search the .md renderings, not the JSONL:
    grep -ril "<term>" raw/saved-conversations/*/*.md
    grep -n -i -B2 -A6 "<term>" raw/saved-conversations/<date>/<file>.md
    
    Try two or three phrasings; people rarely reuse their exact words.
  3. For an "instruction I gave" question, prefer ## User blocks over ## Assistant ones — the user's own words are the instruction, the assistant's restatement is not.
  4. Answer with the exact exchange quoted, attributed as — `raw/saved-conversations/<date>/<file>.md`, under "User — <timestamp>", and the date. If nothing matches, say that no saved conversation mentions it, and name the date range the saved conversations cover so the user knows whether the gap is "never discussed" or "not saved".
  5. Never promote a recalled instruction into wiki/ on the strength of the transcript alone. If it deserves to be durable, offer ckb-decide (for a decision) or ingest (for knowledge) as the next step.

Edge cases

  • No transcript directory (exit code 2): the KB is being driven by something other than Claude Code, or CLAUDE_CONFIG_DIR points elsewhere. Report the path the script looked in and ask the user for the transcript file; then use --from <file>.
  • Ambiguous --session prefix: the script lists the matches; pass a longer prefix.
  • Same session saved twice in one day: files and index row are replaced, the script prints updated (or unchanged when nothing grew). A session saved again on a later day gets a new dated folder; both stay.
  • Subagent turns are rendered with a (subagent) marker on the heading.
  • Very long tool results are cut at 400 characters in the Markdown; the JSONL has them in full.
  • ckb-reset treats raw/saved-conversations/ as tier 3 source material: asked about, never deleted silently.