| name | distill-session-knowledge |
| description | Periodic distillation: scan the last 5 days of high-quality Claude transcripts in the current project, dedup facts seen across sessions and against existing docs, and propose surgical edits to the right reference docs. Wider-than-daily window avoids 00:00 boundary loss. This skill should be used when the user says "distill recent", "distill session", "distill last week", or asks "what should we learn from recent work".
|
| disable-model-invocation | true |
| allowed-tools | ["Bash(fd:*)","Bash(jq:*)","Bash(uv run *scripts/distill.py:*)","Bash(rg:*)","Bash(wc:*)","Bash(date:*)","Bash(mkdir:*)","Bash(cat:*)","Bash(git diff:*)","Bash(git status:*)","Read","Edit","Write","AskUserQuestion"] |
Distill Session Knowledge
Scan the last 5 days of substantive Claude conversations in the current
project and land durable facts (pitfalls, costs, calibrated results) into
the project's reference docs. The 5-day window straddles 00:00 so facts
discovered around midnight don't fall through; dedup catches facts repeated
across sessions and facts already documented by a prior run.
Goal
At least one merged or cleanly-proposed edit to one of the project's
existing reference docs (whatever convention this project uses —
discovered in step 4, not assumed), scoped strictly to facts that will
still be true next month and not already documented.
Steps
1. Inventory recent transcripts
Read the project's distill state first — use the Read tool on
.claude/state/distill.json so the full state (both last_distilled_at
and convention) lands in context. Step 4 reuses the convention field
without re-reading. If the file doesn't exist, this is a first run.
Then compute the window floor and list candidates. Pick one value
for $FLOOR based on the state Read above, then substitute it into a
single bash run:
$FLOOR = '<last_distilled_at> -5 hours' when state exists (5h
overlap tolerance — date -d accepts the arithmetic inline).$FLOOR = '5 days ago' on first run.
since=$(date -I -d "$FLOOR")
fd -e jsonl --changed-within "$since 00:00:00" . ~/.claude/projects
The 5h backstep guards against context loss when transcripts straddle the
previous run's exit; step 5's dedup catches the resulting overlap. If the
user explicitly asks for a different window ("distill last week"), set
since directly and skip the state read.
Note the count. Most files will be one-prompt automated probes — that's
normal; cut them in step 3.
Success criteria: file list scoped to the current project's encoded cwd
slug under ~/.claude/projects/.
2. Distill (with window slicing)
Run the bundled filter, passing the same $since date as the inclusive
lower bound:
uv run scripts/distill.py "$since"
The script keeps only messages whose timestamp is >= $since. A session
that started before the window but continued into it contributes only its
in-window events; its n_user, started, and ended reflect the
in-window slice. Sessions with zero in-window user prompts are dropped.
Output: /tmp/distilled/<cwd-slug>.jsonl. Each record has
{session, cwd, branch, started, ended, session_started, session_ended, is_carryover, n_user, n_asst, n_user_total, user[], asst[]} — with
<system-reminder>, <command-*>, <task-notification>,
<local-command-caveat>, and cache-keepalive ticks already stripped.
3. Cut to high-quality
Filter the project's file to sessions where n_user >= 3:
jq -r 'select(.n_user >= 3) | "\(.n_user)/\(.n_user_total)\t\(.is_carryover)\t\(.session)\t\(.started)..\(.ended)"' /tmp/distilled/<cwd-slug>.jsonl
The n_user / n_user_total ratio shows in-window prompts vs the whole-session
total. The is_carryover flag (true when the session started before the
window) tells you the engineering arc may extend earlier — useful context
for step 4 but not a reason to exclude the session.
If zero remain, tell the user "no substantive sessions in the last N days"
and stop. Do not invent material from low-quality sessions.
4. Inventory project docs, then categorize
Before reading transcripts, discover what reference-doc shape this
project actually has. Read CLAUDE.md for layout hints, then list
whichever of references/, docs/, notes/, specs/ exist at the
project root. For each doc found, read just the heading + intro paragraph
(not the whole file) and note its role in one phrase. The result is a
project-specific routing table — the categories the project already uses
to organize durable knowledge:
| Doc | Role (paraphrased from heading/intro) |
|---|
(e.g.) references/pitfalls.md | tool / syntax gotchas |
(e.g.) references/task-costs.md | measured runtime/memory/I/O |
(e.g.) specs/feature-X.md | calibrated outcomes for feature X |
Bootstrap branch — empty project: if zero reference docs exist
anywhere AND .claude/state/distill.json has no convention field,
pause and ask one AskUserQuestion before drafting: "no reference-doc
convention yet — where should durable facts live?" Offer 2–3 concrete
options (e.g. references/*.md per-role files, a single NOTES.md,
"don't write durable docs"). Step 7 persists the answer into the state
file's convention field; later runs read it back without asking. This
is the rare coin-flip case where pre-asking is correct: the answer
changes the file path itself, not just wording. Do not fabricate a
tree without asking.
Now for each surviving session, pull user[] and asst[]. Read prompts
for intent; scan assistant first-lines for the engineering arc. For each
candidate fact, ask: which row of the routing table does this serve?
- Matches a role → candidate, with that doc as the draft target.
- Matches no role → set aside. Don't manufacture a new doc just to
land the fact; surface these as "facts with no obvious home" at the end
and let the user decide whether to create a new doc.
- Pattern / preference / one-off (workflow tendencies, terse-style
notes, "fix this", "rename that") → skip; those belong in
skills/hooks/CLAUDE.md, not reference docs.
Rule: if a fact embeds an ephemeral path, session ID, run ID, or
"today's commit X", strip those references before considering durability.
If nothing remains after stripping, it isn't a fact.
Within-window dedup: with a multi-day window the same fact often
surfaces in several sessions (a discovery on day 1 gets re-confirmed on
day 3, etc.). Collapse such duplicates into one canonical candidate before
proceeding — keep the cleanest phrasing. Recurrence across sessions is a
secondary durability signal (worth noting in the routing table for the
user), but is NOT a gate: a single session is sufficient to land an ADD or
an UPDATE provided the fact survives the durability filter and (for
UPDATE) the verifiability check in step 6. Do not draft N near-identical
edits.
5. Read target format, dedup against existing docs
Each surviving candidate already has a draft target from step 4. For each,
read the target file's adjacent section before drafting. The existing
rhythm dictates the addition's shape — a
doc built around tables takes a row, a doc built around formula blocks
takes a formula block, a doc built around prose takes a paragraph. Picking
the wrong shape produces an addition that visibly doesn't belong, and the
user has to redirect.
Cross-doc classification (three-way, not two-way): before drafting,
grep the candidate target (and neighbouring doc files) for the candidate
fact's discriminating terms — symbol name, error message, function/recipe
name, or numeric threshold. Pick discriminators specific enough to
distinguish the fact from neighbours; a single broad term ("filter") will
false-positive everywhere. Then read the surrounding section and classify:
| Outcome | Meaning | Action in step 6 |
|---|
| none | No hit on the discriminator | ADD a new entry |
| match | Hit, and the existing entry agrees with the candidate (same number, same conclusion, same formula) | drop — already covered |
| contradict | Hit on the same subject, but the existing entry's number / conclusion / formula differs from what the transcripts now say | UPDATE — see step 6 |
Silent dedup against stale docs is the worst failure mode: every distill
run reinforces the staleness by dropping the corrections. Always classify
before dropping.
6. Draft inline, edit, show diff
Pick the strongest 1–3 candidates. Two sources feed this:
- Routed candidates (step 4 matched a routing-table role; step 5
classified as
none or contradict) — draft against the existing doc.
- Orphan groups (set aside in step 4 with no matching role) — if ≥2
share a missing role, treat the group as one CREATE candidate.
Single orphans don't qualify; surface them in step 7 as an open
question.
Draft each edit in the matching format observed in step 5, make the
Edits, then show git diff plus a short routing table:
| File | Edit type | Section | Durability / recurrence rationale |
|---|
Edit types:
- ADD — new entry in an existing doc. Default for
none-class
candidates from step 5; land if the fact survives the durability filter.
- UPDATE — replace a stale value or claim in an existing doc. Required
for
contradict-class candidates. Verifiability-gated, not
recurrence-gated: before auto-drafting, independently verify the
contradiction against the codebase right now — ls/fd for file
existence, rg/ast-grep for symbol or recipe definitions, a quick
command run for fast checks. If verification confirms the doc's claim
is no longer true, auto-draft the UPDATE; a single session is sufficient
when the contradiction is verifiable. Surface for verify (no auto-Edit)
only when the contradiction is about a continuous measurement (perf
number, metric value) that can't be cheaply re-checked from the repo.
When drafting an UPDATE, prefer minimal replacement (the specific number,
phrase, or formula that changed) over rewriting the surrounding section.
Keep the heading, surrounding bullets, and "Promoted from" line untouched
unless they are themselves contradicted.
- CREATE — propose a new reference doc when ≥2 orphans share a
missing role. Use the convention recorded in
.claude/state/distill.json (path + format) — or, on bootstrap, the
path the user just chose in step 4. Seed the new doc with the
triggering orphans in the shape later runs should extend (table-of-
rows, bulleted entries, etc.), not free-form prose. Do not create a
doc to land a single fact; the per-doc bitrot cost is too high.
Do not gate step 6 on a pre-selection question. Multi-choice questions
asked before the user sees a drafted diff are strictly worse than the agent
defaulting and the user redirecting from the diff: the user can't react to
phrasing they haven't seen, and the question collapses a continuous
judgment into 2–4 buckets. For low-blast-radius additive doc edits,
reverting an Edit is one tool call — cheaper than the question round-trip.
Ask only when the choice is genuinely a coin-flip AND changes the drafted
text substantively. In that case, draft both versions and use
AskUserQuestion's preview field to show them side-by-side.
Never include in the body: ephemeral paths (temp/, /tmp/), session
IDs, run IDs, specific commit hashes, dates inside the row, "today's"
wording. If stripping these leaves nothing, the candidate wasn't durable.
7. Audit, persist state, finalize
After Edits, the project's Stop hook runs audit-edits.py automatically.
For each FIXES entry: judge whether it's a true issue (DOC-contradiction,
incident-leak, scope creep) or a false positive; apply or dismiss explicitly.
Persist state for the next run — read-modify-write so any pre-existing
convention field survives untouched:
mkdir -p .claude/state
{ cat .claude/state/distill.json 2>/dev/null || echo '{}'; } \
| jq --arg ts "$(date -Iseconds)" '.last_distilled_at = $ts' \
> .claude/state/distill.json.tmp \
&& mv .claude/state/distill.json.tmp .claude/state/distill.json
If step 4 hit the bootstrap branch, also merge the user's answer into
.convention (keys: path, format) in the same write so subsequent
runs read it back rather than re-asking. Surface the final git diff
plus any single-orphan facts ("no obvious home for: X, Y") as a closing
question. Do not commit unless asked.
Rules
- No fabrication — every fact must trace back to actual prompt or
assistant output in the transcript. If you can't quote it, drop it.
- Preferences are not facts — terse confirmation style, codex habits,
etc. live in CLAUDE.md or hooks, not distilled docs.
- One bad edit > zero edits is the wrong tradeoff here. Skipping a
borderline fact is always correct; landing a wrong one pollutes the
reference doc.
