/self-improve

name: self-improve
description: "Extract lessons from this session or past sessions and route them to instructions, memory, or skills. Use when the user asks to \"self-improve\", \"extract lessons\", or \"what did we learn\"."

Self-Improve

Review the current conversation, or the project's past sessions when asked, to extract durable lessons and route each one to the right knowledge layer.

Step 1: Detect Context

Available destinations:

• **Project CLAUDE.md / AGENTS.md** — The root `.claude/CLAUDE.md` (may be a symlink to `../AGENTS.md` — resolve it), plus any nested `CLAUDE.md` / `AGENTS.md` files in subdirectories.
• **Auto memory** — The project-specific memory directory named by the active harness. An effective `autoMemoryDirectory` setting overrides its location; otherwise it normally lives at `<Claude config home>/projects/<encoded project root>/memory/`, where the config home is `CLAUDE_CONFIG_DIR` when set and `~/.claude` otherwise. The key replaces every character outside `A-Za-z0-9` with `-`, and long keys may be truncated and hashed, so prefer the exact harness-provided path over recomputing it. List the directory and read `MEMORY.md` if it exists.
• **Skills** — Project skills at `skills/` or `.claude/skills/` (resolve symlinks)

Discover the project CLAUDE.md/AGENTS.md files (the root file and any nested ones in subdirectories) and read them, then read MEMORY.md. When those files point at a knowledge base the repo maintains, read its index too; it is a documentation source for Step 3 rather than a routing destination. List all skill directories with the `description` frontmatter of each SKILL.md, but leave the bodies unread until Step 2.

Read the top-level `checkout` key from `~/.turbo/config.json` when the file exists. When it names a directory holding `claude/skills/`, that directory is the user's Turbo clone or fork. Treat any other value as unset, and say so in the Step 5 routing plan.

Skill Ownership Detection

When `${CLAUDE_SKILL_DIR}/../../.claude-plugin/plugin.json` exists and names the plugin `turbo`, the Turbo plugin's skills folder is `${CLAUDE_SKILL_DIR}/..`. Otherwise this skill runs from an override or a leftover copy, no folder is known to be Turbo's, and only a `turbo:` invocation marks a turbo skill. Classify every skill this session touched by where it was loaded from, never by its name alone:

• Skills that live in the project are user/project skills
• A skill is a turbo skill when it ran as `turbo:<name>`, or when the base directory its load reported, or the path its `SKILL.md` was read from, lies in the Turbo plugin's skills folder. A same-named skill loaded from `~/.claude/skills/` or the project overrides the Turbo skill, and its lessons go to that override
• For every skill in `~/.claude/skills/` not classified as turbo, overrides included, read [references/package-managed-skills.md](references/package-managed-skills.md) once and apply its Classify the Skill section to each
• A skill that no bullet above classifies is ownership-unresolved when the session's record shows the folder it was loaded from, and package-managed otherwise

**Exception:** If the current project IS the turbo repo (i.e., the working directory contains this skill collection), route turbo skill lessons through the **Existing user/project skill** destination in Step 4 — edits go directly to `claude/skills/<name>/` in the project, with no handoff and no contribution flow.

**Verification rule (mandatory before routing in Step 4):** For every candidate skill that is about to be routed as turbo and ran in this session, find the load that ran it in this session's record: a `turbo:` Skill tool invocation, the base directory a load reported, or a `SKILL.md` read. Confirm that the load came from the Turbo plugin's skills folder. For a candidate that did not run, confirm that `<Turbo plugin's skills folder>/<name>/SKILL.md` exists and that no skill of that name exists in `~/.claude/skills/` or the project. Do not rely on a name match, remembered listings from earlier in the session, or filename hits in grep output: a personal or project skill of the same name is an override, not the turbo skill. Classify a candidate that fails this rule again by the bullets above. The rule applies under the exception above too.

Step 2: Gather Session Evidence and Scan for Lessons

Recover Pre-Compaction Evidence

**Skip** when the conversation is visible in full from the user's own first message.

When it starts from a summary of earlier work instead, recover the compacted turns from the on-disk transcript. Spawn a single subagent (`model: "opus"`, no `name`). Wait for it to report before continuing; do not relaunch it if it has not yet reported. The subagent's prompt must include:

1. The absolute path of the project root 2. A distinctive phrase from the visible conversation, for confirming which transcript belongs to this session 3. An instruction to read `${CLAUDE_SKILL_DIR}/references/transcript-miner.md` for transcript location, extraction, and output format

Treat the returned items as raw evidence for the scan below.

Sweep Past Sessions

**Run** when asked to distill sessions beyond the current one: read [references/past-session-sweep.md](references/past-session-sweep.md) and follow it. **Skip** otherwise.

Identify Session Skills

Before scanning for lessons, identify which skills were loaded during this session:

• Scan the conversation for Skill tool invocations, `turbo:`-prefixed ones included, the base directory each skill load reported, and SKILL.md reads from `~/.claude/skills/` or the Turbo plugin's skills folder
• Build a list of session skills, marking each as turbo, user/project, package-managed, or ownership-unresolved (using the detection from Step 1)
• This list informs routing in Step 4: when a lesson clearly arose from a specific skill's workflow, that skill is the natural routing target

Scan for Lessons

Scan the full conversation with th