Session Distill

session-distill

Distill session insights into reusable project knowledge.

When to Use This Skill

May also be reached via the end-of-session flow: the plugin's Stop hook (hooks/session-end-nudge.sh) offers session-plugin:session-end once per session on user wind-down, and the orchestrator runs this skill when a durable learning qualifies.

Core Principle: Update Over Add

Before proposing any artifact, evaluate: Does it update an existing one? Does an existing one already cover this? Is this genuinely new and reusable? See REFERENCE.md for detailed evaluation criteria.

Context

• Git repo detected: !find . -maxdepth 1 -name '.git' -type d
• Justfile: !find . -maxdepth 1 \( -name 'justfile' -o -name 'Justfile' \) -print -quit
• Rules directory: !find . -path '*/.claude/rules/*' -name '*.md' -type f -not -path '*/.claude/worktrees/*'

Parameters

Tool Call Efficiency

Minimize LLM round-trips: batch file reads in a single response, combine evaluation and redundancy checking in one pass, complete one category before starting the next.

Execution

Execute this session distillation workflow:

Step 1: Run the distill collector, then read conversation for rules

Run the read-only collector — the distill-side analogue of session-survey.sh. It mines this session's transcript (and the cross-session window) for the mechanical signals, so you don't re-read the whole conversation for commands/edits or re-run just --dump from memory:

bash "${CLAUDE_SKILL_DIR}/../../scripts/distill-survey.sh" \
  --session-id "${CLAUDE_SESSION_ID}" --window-sessions 10

Consume the digest:

• RECIPE_CANDIDATES — normalized commands that recurred across separate sessions or are commit-bracketed this session, and are NOT already a just recipe or churn (status/diff/log/test/build/ls/…). Each carries a concrete _FIRST example, _SESSIONS count, and _NOVEL_TOKENS.
• HOT_FILES — the files this session edited/wrote most (exact paths) — where rule/doc updates likely land.
• COMMIT_INTERVALS + COMMAND_DIGEST — the mechanical grouping you use to name a process or sequence. The script never infers a sequence itself (sequence-naming is judgment); it hands you completed-work intervals.
• RULE_HINTS_FROM_TOOLING — repeated permission/auth denials, the only mechanical rule signal.

When TRANSCRIPT_AVAILABLE=false / STATUS=SKIP (fresh clone, remote sandbox, mid-conversation flush, or no --session-id), fall back to reading the conversation history directly for commands and edits.

Durable rules live in conversation reasoning, not tool_use mining. For the rules category always read the conversation's decisions, corrections, and constraints yourself — the collector deliberately does not pre-compute rules beyond the narrow RULE_HINTS_FROM_TOOLING denial signal.

Step 2: Evaluate and check redundancy (single pass per category)

When --all: complete rules -> skills -> recipes/process. Do not interleave.

Rules (.claude/rules/*.md): from the conversation reasoning (plus any RULE_HINTS_FROM_TOOLING signal), Glob rule files and Read only the subset the learning touches — the HOT_FILES paths and the rules adjacent to them — then evaluate each insight in one pass (update/skip/remove/merge/add). Do not glob-read every rule when the collector already narrowed the surface.

Skills: Glob relevant skill files (target specific plugins from Step 1), Read in one response, evaluate in one pass.

Recipes / process: the collector already ran just --dump, so RECIPE_CANDIDATES are already novel (not existing recipes). Route each per the destination table — a recurring single command → a just recipe; a multi-step workflow → a script or a project-local skill (see --process).

Step 3: Present proposals

Categorize as: [UPDATE], [SKIP], [NEW], [REDUNDANT], or [PROMOTE] with file paths and reasons.

[PROMOTE] is the additive, cross-repo category — distinct from the others, which all write this repo's .claude/. Use it when the insight is reusable beyond this repo and belongs in a marketplace plugin: either a pattern the session invented that has no home skill yet (→ propose a new skill), or a capability an existing named skill is missing (→ propose an edit to it). A [PROMOTE] does not require anything to have gone wrong — a smooth session that produced a strong reusable technique is exactly its trigger. Each [PROMOTE] names a target <plugin>/skills/<skill> (new or existing) and is applied as a PR against the plugin repo, never an edit to the current repo (see Cross-Repo Promotion).

Step 4: Apply changes

If --dry-run: skip this step.

In auto mode: apply proposals directly without per-category AskUserQuestion. All targets are reversible via git restore — rule files, skill files, and justfile recipes are tracked in git, so a wrong edit can be undone with one command. This matches auto mode's "prefer action over planning" directive. Retain AskUserQuestion for destructive operations ([REDUNDANT] proposals that remove a rule or recipe).

In manual / interactive mode: use AskUserQuestion to confirm each category before applying. The user can multi-select which [UPDATE] / [NEW] proposals to accept.

In plan mode: neither default applies — the harness disallows non-readonly tool calls (including AskUserQuestion-then-apply) except writes to the active plan file. Write the proposal set to the active plan file as a single coherent block (Context + per-category [UPDATE] / [NEW] / [REDUNDANT] sections + a brief verification section), then call ExitPlanMode to surface for user approval. Do not apply directly. After the user approves the plan, fall back to the auto-mode or manual-mode flow above depending on which is active.

For [PROMOTE] proposals, do not edit the current repo. Apply them via the cross-repo PR hand-off below — gate it behind AskUserQuestion in every mode (opening a PR against another repo is outward-facing), and never push to that repo's default branch.

Step 5: Report summary

Output concise summary of changes made, including any [PROMOTE] PRs opened (with their URLs) so the promotion is traceable.

Routing a learning to a destination

Each surviving insight goes to exactly one home. Pick most-specific first — a new artifact type was deliberately not added (no .claude/runbooks/); a project-local process reuses the .claude/skills/ convention CLAUDE.md documents as a first-class, auto-loaded home.

The --process category covers the two multi-step rows: a deterministic workflow becomes scripts/*.sh + a recipe (offload to a deterministic substrate); a judgment-bearing one becomes a project-local skill. Name the sequence yourself from COMMIT_INTERVALS / COMMAND_DIGEST — the collector gives you the grouping, not the name.

Cross-Repo Promotion ([PROMOTE])

The other categories keep knowledge in this repo. [PROMOTE] is how a session-invented pattern reaches the shared plugin marketplace so every repo benefits — the additive complement to feedback-plugin's error loop (which only fires on friction). A near-zero-friction session can still produce several [PROMOTE] candidates.

Routing: which plugin/skill should own it

Pick the target by the pattern's domain, most specific first:

Then decide new skill vs. edit existing: glob the owner plugin's skills/, read the closest few, and prefer extending an existing skill (a new section + cross-link) over a new skill unless the pattern is genuinely its own topic (Update Over Add still applies — across repos now).

The PR hand-off (isolated clone — never edit cwd, never push to default)

The plugin source lives in its own repo. Open a PR there; the human reviews and merges. Match the repo's conventions: skills are auto-discovered (add skills/<name>/SKILL.md with dated frontmatter + user-invocable/allowed-tools), update the plugin README's skill catalog, keep !-context commands free of pipes/ redirects, use a conventional commit (feat(<plugin>): for a new skill, docs(<plugin>): for an edit — release-please versions from it), and apply the <plugin> routing label (create it if missing).

Do the whole promote in a throwaway clone, never in a long-lived local checkout of the plugins repo. That checkout is frequently contended by a concurrent Claude session: a coworker's operation can autostash your in-flight edit and move HEAD between two of your calls, so the next git add/commit reports "nothing to commit, working tree clean" and the edit is silently gone (issue #2113). A fresh clone shares no .git with that checkout, so no coworker can move HEAD under it. git worktree add is not equivalent — it registers in the shared checkout's .git and was itself observed failing (already used by worktree) once HEAD had moved.

WORK=$(mktemp -d); test -n "$WORK" || exit 1
git clone --depth 1 --single-branch --branch main https://github.com/laurigates/claude-plugins.git "$WORK/claude-plugins"
git -C "$WORK/claude-plugins" switch -c <type>/<short-slug>
# ... Write/Edit the SKILL.md + README under "$WORK/claude-plugins" (absolute paths) ...
git -C "$WORK/claude-plugins" add <paths>
git -C "$WORK/claude-plugins" commit -m "<conventional message>"
git -C "$WORK/claude-plugins" log --oneline origin/main..HEAD
git -C "$WORK/claude-plugins" push -u origin <branch>
gh pr create -R laurigates/claude-plugins --base main --head <branch> --title "<conventional title>" --body-file /tmp/promote-body.md -l <plugin>
rm -rf "$WORK"

Remove the throwaway (rm -rf "$WORK") only after the PR URL is in hand — it is the only copy of the work until the push lands.

Cross-references for the shared-checkout hazard this avoids: repos/.claude/rules/shared-checkout-branch-isolation.md (the git log --oneline origin/main..HEAD verification above — a branch must contain only your own commits before you push), repos/.claude/rules/concurrent-session-pr-check.md (before recreating work that "vanished", check whether a peer session already opened a PR for it — never pop a shared stash), and git-plugin:git-coworker-check (run it before any operation that genuinely must touch a shared checkout).

The PR body should cite the session as evidence (what the pattern is, why it's reusable, where it was used) — the additive analogue of the friction loop's evidence summary.

Agentic Optimizations