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/*'

Harnesses that don't execute !`…` context commands show these lines as text; in that case run the three find commands yourself before Step 1.

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, are NOT already a just recipe or churn (status/diff/log/test/build/ls/…), are NOT a compound/loop line (;, &&, ||, until/while/for — those are --process material), and carry a stable argument: either no placeholder at all, or one standalone placeholder that resolved to the same concrete value in ≥2 sessions (a placeholder embedded in a flag — --title=<str> — can never prove stability, so those shapes are always dropped). Each carries a concrete _FIRST example, _SESSIONS count, _NOVEL_TOKENS, and _STABLE_ARGS (up to three repeated values, sorted, or literal). A low count is the honest answer, not a broken collector.
• 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.

Under pi, the collector falls back to the transcript named by PI_SESSION_FILE and reports TRANSCRIPT_FORMAT=pi. pi records no permission denials, so its RULE_HINTS_FROM_TOOLING carries RULE_HINTS_RECORDED=false: a zero there means "not recorded", not "none".

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. AskUserQuestion keeps the turn open, so no Stop hook fires between the question and the answer. Where AskUserQuestion is unavailable (a harness without the tool), ask in plain text and end the turn.

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