Claude Skill

self-improve

Extract lessons from the current session, or sweep the project's past sessions when asked, and route them to the appropriate knowledge layer (project AGENTS.md, auto memory, existing skills, or new skills). Use when the user asks to "self-improve", "distill this session", "distil

LLM Mart · 0 points · 20 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download tobihagemann-turbo-claude_skills_self-improve-13e177e.zip · 12 KB
tobihagemann/turbo 403 31 forks MIT Updated 1d ago
Part of tobihagemann/turbo — 147 skills

Install

skills CLI npx skills add https://github.com/tobihagemann/turbo/tree/main/claude/skills/self-improve
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tobihagemann-turbo@llmmart
Git git clone https://github.com/tobihagemann/turbo.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole tobihagemann/turbo collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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. Claude Code loads a subdirectory's file on demand when files in that subtree are accessed, so a lesson scoped to one subtree belongs in the nearest enclosing file, with the root reserved for project-wide rules.
  • 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 but do not read them yet — Step 2 needs to run first so you know what to look for.

Skill Ownership Detection

Classify every skill this session touched:

  • Skills that live in the project are user/project skills
  • If ~/.turbo/repo/ exists, list directories in ~/.turbo/repo/claude/skills/; any skill in ~/.claude/skills/ with a matching directory there is a turbo skill
  • For every other skill in ~/.claude/skills/, read ~/.agents/.skill-lock.json. Its top-level skills object is keyed by skill name, and a skill listed there was installed from a source that replaces it wholesale on its next update. Match on the resolved path rather than the name alone, against the entry's skillPath, so a local fork that replaced the installed copy is not mistaken for it. A skill that matches is package-managed. The signal runs one way: absence from the file leaves ownership genuinely open, so carry an unlisted skill into Step 4 as ownership-unresolved

Verification rule (mandatory before routing in Step 4): For every candidate skill that is about to be routed as turbo, confirm with a fresh test -d ~/.turbo/repo/claude/skills/<name> check that the skill actually lives in the turbo repo. Do not rely on remembered listings from earlier in the session, filename hits in grep output, or assumptions based on where a SKILL.md was read from. A miss here mislabels a user/project skill as turbo, triggers the contribution flow unnecessarily, and can introduce session-specific content into a shared skill — so the check is not optional.

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 installed-copy indirection and no contribution flow.

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 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. Skip otherwise.

Propose a cutoff first: take the newest modification time in the memory directory from Step 1, state it, then use AskUserQuestion to confirm sweeping from it or sweeping the whole history. A memory file's timestamp records a write rather than a completed sweep, so it bounds the work without settling what a previous run covered. When the directory is absent or empty, sweep the whole history without asking.

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. The confirmed cutoff as an ISO-8601 timestamp, or that there is none
  3. An instruction to read references/transcript-miner.md and follow its sweep process

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

Identify Session Skills

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

  • Scan the conversation for Skill tool invocations and SKILL.md reads from ~/.claude/skills/
  • 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 this priority:

  1. Corrections — Where the user interrupted, said "no", "actually", "stop", "not like that", redirected, or manually fixed something Claude did wrong. Highest-value lessons.
  2. Repeated guidance — Instructions the user gave more than once. Across separate sessions this counts even where each instance reads as ordinary steering on its own.
  3. Skill-shaped knowledge — Domain expertise that was needed repeatedly, tool/API integration details that had to be looked up, decision frameworks that emerged for evaluating options, content templates or writing conventions that were refined, and multi-step workflows where ordering mattered (as reusable domain knowledge, not the workflow itself — see #4).
  4. New workflows — Did this session establish a novel multi-step procedure, coordination pattern, or automation that worked? A successful workflow that would need to be repeated is a prime skill candidate — even if it ran fine this time. Distinct from #3: this captures the procedure itself as a repeatable artifact, not knowledge about how to do it. Flag it.
  5. Preferences — Formatting, naming, style, or tool choices the user expressed.
  6. Failure modes — Approaches that failed, with what worked instead. For tool or script call failures, trace back to the information source that led to the error and route the fix there (e.g., clarify a reference file, update skill instructions, add missing documentation).
  7. Domain knowledge — Facts or conventions Claude needed but did not have.
  8. Improvement opportunities — Out-of-scope improvements noticed during work: code that could be refactored, missing tests, performance issues, readability concerns, or feature ideas that were intentionally skipped to stay focused. Skipped findings count here: when code simplification or code review identified a genuine improvement or issue but it was skipped for this session, route it as a project improvement so it isn't lost.
  9. Trusted reviewer feedback — Human PR review comments that reveal project conventions, patterns, or corrections. Trusted reviewers are repo collaborators with admin or maintain roles (determine via gh api repos/{owner}/{repo}/collaborators --jq '.[] | select(.role_name == "admin" or .role_name == "maintain") | .login'). Their feedback takes precedence over other reviewers and AI bots when there are contradictions.

After scanning, read all skill SKILL.md files (they are small). This gives Step 4 full context for routing.

Step 3: Filter

Keep only lessons that are:

  • Stable — likely to remain true across future sessions
  • Non-obvious — Claude would not already know this
  • Actionable — can be expressed as a rule or instruction
  • Not already documented — absent from the files read in Steps 1 and 2, from each skill's references/ and other supporting files, and from the project's own knowledge stores. Search all of those for each candidate's keywords rather than assuming. A lesson documented only in an unrelated subtree's CLAUDE.md/AGENTS.md still counts as undocumented for the subtree it actually applies to.
  • Still a concern — the issue is not already fixed by changes made in this session. If a bug was found and fixed, or a missing feature was added, future sessions will see the corrected code — they don't need a reminder about the old problem. Exception: successful workflows and procedures are not "resolved" — they're skill candidates precisely because they worked and will need to be repeated. When sweeping past sessions, judge this against the current state of the code and docs rather than against this session's changes.

Discard anything session-specific, speculative, one-off, or already resolved by code changes in this session (but not successful workflows — see exception above). If no lessons survive filtering, tell the user and stop.

Step 4: Route Each Lesson

Assign each surviving lesson to exactly one destination.

Skill-first rule (mandatory): Before consulting the table below, check whether the lesson corrects, refines, or adds a guardrail to any existing skill's behavior — turbo or user/project. This includes lessons about skipping steps, wrong defaults, missing edge cases, or any "don't do X when running /skill-name" correction. If yes, route to that skill. Do not route skill corrections to auto memory or CLAUDE.md — they belong in the skill they correct. This rule is not a preference; it is a hard constraint that takes precedence over the table rows below.

Package-managed skills (mandatory): A skill Step 1 classified as package-managed from the lock file routes its lesson straight to Auto memory, recording the skill it applies to, with no question put to the user: the lock file has already settled ownership. A skill under ~/.claude/skills/ that Step 1 left ownership-unresolved may still be one a package manager replaces wholesale on its next update, discarding any edit made here. Before routing a lesson to such a skill, say plainly that an edit to it survives only while the user maintains it themselves. Then use AskUserQuestion to ask which is the case, with the options phrased as that effect: edits to this skill stick, or the next update overwrites them. Route the lesson to Auto memory when a package manager maintains the skill, recording the skill it applies to so the knowledge survives the next update. For those skills this rule outranks the skill-first rule, the routing table rows, and the tiebreakers below.

Destination Criteria
Project improvements Actionable improvement to existing code: refactoring, performance, reliability, readability, testing, or DX. Not for documentation fixes — factual errors in CLAUDE.md belong in the Project CLAUDE.md / AGENTS.md row. Route to .turbo/improvements.md via the /note-improvement skill.
Auto memory Discovered knowledge with no skill home: API quirks, debugging workarounds, compiler gotchas, tool pitfalls, user preferences. Must not overlap with any existing skill's domain — if it does, route to the skill instead (see skill-first rule above). A lesson the package-managed skills rule sends here stays here, whatever domain it overlaps.
Project CLAUDE.md / AGENTS.md Intentional project decisions: conventions, architecture, stack choices, build setup, module boundaries. Also factual corrections to CLAUDE.md content (wrong commands, outdated paths, incorrect conventions) — fix these directly, do not defer to Project improvements. When the lesson applies only to one subtree, route it to the nearest enclosing CLAUDE.md/AGENTS.md; reserve the root file for project-wide decisions.
Existing user/project skill Lesson would improve a skill's instructions, supporting files, or reference materials, add a missing edge case, correct its workflow, or refine its trigger conditions. Route to any skill whose domain covers the lesson — not just the skill worked on in this session. Changes go to the skill file directly. No contribution flow.
New skill A cohesive body of knowledge emerged that deserves its own on-demand context. The test: would this knowledge be too large for a CLAUDE.md section, and should it only be loaded when relevant? See the skill categories table below.
Existing turbo skill Same criteria as Existing user/project skill above, but for turbo skills. Before routing here, run test -d ~/.turbo/repo/claude/skills/<name>; if the directory does not exist, route to the Existing user/project skill destination instead, subject to the package-managed skills rule above. Changes go to the installed copy at ~/.claude/skills/, and are flagged for contribution (see Step 6).
No destination Does not clearly fit any destination. Drop it. Routing a weak lesson is worse than losing it.

Skill categories:

Category What it encodes Example
Domain expertise Best practices, patterns, API preferences SwiftUI expert, Core Data guide
Tool/Service integration API references, operations, ID formats Paddle, Stripe, Keycloak
Decision framework Judgment criteria, confidence levels, triage Evaluate findings, performance audit
Content template Writing conventions, tone, structure Drafting, blog post, changelog
Knowledge/Research Information discovery, schema definitions Knowledge base, research process
Orchestrated workflow Stateful multi-step procedures Process ticket, process income

Splitting heuristic: When a session creates scripts or multi-step procedures, split the lesson: a brief pointer goes to CLAUDE.md (script names, purpose), and the full workflow goes to a skill. Don't collapse them into a single CLAUDE.md entry.

Tiebreakers (in priority order):

  1. Skill correction → skill (hard rule). Any lesson that corrects, constrains, or refines a skill's behavior MUST route to that skill. Never to auto memory, never to CLAUDE.md. This is the highest-priority routing rule, ahead of every tiebreaker below and yielding only to the package-managed skills rule above.
  2. Turbo skill vs. CLAUDE.md → always the turbo skill. Broader impact (benefits all turbo users), better scoped, loaded only when relevant.
  3. Skill vs. CLAUDE.md → always the skill. Skills are more discoverable, better scoped, and loaded only when relevant.
  4. Skill vs. auto memory → always the skill. If a lesson falls within the domain of an existing skill, it goes to the skill. Auto memory is for knowledge that has no skill home, and for the domain of a skill a package manager maintains.
  5. CLAUDE.md vs. auto memory — intentional decisions go to CLAUDE.md. Discovered knowledge (gotchas, workarounds, quirks) goes to auto memory.
  6. Lesson vs. improvement — if the item is knowledge to remember, it's a lesson. If it's work to do later, it's an improvement. They don't compete — the same session can produce both.

Step 5: Present Routing Plan

Output a table as text before making any changes:

| # | Lesson | Destination | Action |
|---|--------|-------------|--------|
| 1 | Always use X for... | Project AGENTS.md | Append to ## Conventions |
| 2 | The /create-pr skill should... | ~/.claude/skills/create-pr | Update Step 2 |
| 3 | Multi-step deploy workflow | New project skill | Create new skill |
| 4 | User prefers short commit msgs | Auto memory | Update <resolved memory target> |

For each lesson, show: concise summary, exact target file/skill, and whether it's an append, update-in-place, or new creation. For Auto memory, name the resolved project-memory target so the approval covers the durable write at that path.

Then use AskUserQuestion with these options: Approve or Reject.

Step 6: Execute

Apply approved changes in order:

  1. Improvements — For items routed to project improvements, run the /note-improvement skill with the summary, location, and rationale for each.

  2. Updates to auto memory — Read the target, find the right section, append or update in place, following the memory system conventions from the system prompt.

  3. Updates to CLAUDE.md / AGENTS.md — Read the target file selected in Step 4 (the root file or a nested subtree file), find the right section, append or update in place. Match the tone and format already present.

  4. Updates to user/project skills — Run the /create-skill skill to apply changes to any file inside the skill directory (SKILL.md, references, scripts, assets).

  5. New skills — Run the /create-skill skill for each new skill. Provide the trigger conditions and relevant context from the session.

  6. Updates to turbo skills — For each lesson routed to a turbo skill:

    1. Read ~/.turbo/repo/claude/SKILL-CONVENTIONS.md so turbo-specific conventions are in context before any editing.
    2. Run the /create-skill skill to update the installed copy at ~/.claude/skills/<name>/.

    Once every turbo skill edit is in place and reviewed, use AskUserQuestion to ask "These turbo skill improvements could benefit other users. Propose them upstream?" When the user confirms, run the /contribute-turbo skill once for all of them.

Then use the TaskList tool and proceed to any remaining task.

Writing Guidelines

  • Match the tone and format of the target file
  • Use imperative mood and short declarative sentences
  • Group related insights under a descriptive heading
  • Omit rationale unless the rule would seem arbitrary without it
  • Never include temporary state, in-progress work, or task-specific details
  • Keep lessons generic—avoid overly concrete examples; state the rule, not the instance
  • For AGENTS.md: write as agent documentation — project rules any AI agent on this repo should follow
  • For auto memory: write as personal project notes — concise, operational, organized by topic
  • For skills: follow the conventions in the existing skill collection
  • For files that live in the repo (CLAUDE.md / AGENTS.md and project skills): name only mechanisms that live in the repo too; describe an installed skill's behavior generically
Files (turbo)
  • references
    • transcript-miner.md 11.4 KB 
      # Transcript Miner Guidelines

Recover session evidence that context compaction dropped, from the transcript Claude Code persists on disk. Read and report; change nothing.

## Mining Process

### 1. Locate the Transcript

Claude Code writes every session to `<Claude config home>/projects/<encoded-cwd>/<session-id>.jsonl`, where the config home is `CLAUDE_CONFIG_DIR` when set and `~/.claude` otherwise. The key replaces every character outside `A-Za-z0-9` with `-`; long keys may be truncated and hashed. A session started in a subdirectory uses its own key. Use a harness-provided project directory only when it has this transcript-storage shape; a custom auto-memory directory is independent. Otherwise match the normal encoded project root as a prefix:

```bash
ROOT="<project root>"
CLAUDE_HOME="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
if [[ "$CLAUDE_HOME" == "~/"* ]]; then CLAUDE_HOME="$HOME/${CLAUDE_HOME:2}"; fi
ls -t "$CLAUDE_HOME/projects/$(printf '%s' "$ROOT" | sed 's|[^A-Za-z0-9]|-|g')"*/*.jsonl | head -5
```

The current session is the most recently modified file. Confirm it by grepping for the distinctive phrase you were given, using a short fragment that sits on one line and contains no quote characters: the stored text is JSON-escaped. When the phrase is absent, try the next file down, since concurrent sessions in the same project share the directory. When no prefix match exists, enumerate the most recently modified project directories and verify candidates from their recorded `cwd`; this covers truncated keys and encoding collisions without guessing the internal hash.

If the directory or a matching transcript cannot be found, report that in one line and stop.

### 2. Extract the User Side

Each line is a record with `type`, `timestamp`, `sessionId`, and `isSidechain`. Conversation records are typed `user` and `assistant` and carry `message.content`, either a string or a list of parts typed `text`, `tool_use`, or `tool_result`. The remaining types hold harness state.

Two filters matter. Records with `isSidechain: true` are subagent conversations where the user never speaks. Many user records hold harness-injected text that reads like user speech: slash command wrappers, bash I/O, system reminders, cross-session notifications, and skill-loading preambles. Those wrappers still carry the arguments the user typed after a slash command, so salvage the arguments instead of dropping the record whole.

A message the user types while a tool call is in flight never becomes a `user` record. It persists as an `attachment` record whose `attachment.type` is `queued_command`, holding the text in `attachment.prompt` in the same string-or-parts shape. Take the ones whose `attachment.origin.kind` is `human`, which excludes the harness notifications queued the same way. The record sits at the point of delivery and carries the timestamp of the moment the user typed it.

An answer given through `AskUserQuestion` produces no text part either. The `user` record carrying it holds a `toolUseResult.answers` object mapping each question to the answer, and a `toolUseResult.annotations` object holding free text the user typed. When they typed instead of selecting an option, `answers` holds a placeholder and the words live only in `annotations`, so read both. Each answer is either an option label the user selected or the free text they typed, so both are their own words. Read these objects rather than the `tool_result` part rendering the same content as prose: its opening wording varies across harness versions, and its closing harness instruction would otherwise land in the quoted evidence.

Print the real user turns:

```bash
python3 - "<transcript path>" <<'PY'
import json, re, sys

NOISE = ("<command-message>", "<command-name>", "<local-command-stdout>",
         "<local-command-caveat>", "<bash-input>", "<bash-stdout>", "<bash-stderr>",
         "<system-reminder>", "<task-notification>", "Base directory for this skill:",
         "Called the ", "Caveat: The messages below were generated",
         "(Re-invocation of", "Skill /", "Another Claude session sent")

ARGS = re.compile(r"<command-args>(.*?)</command-args>|\nARGUMENTS:\s*(.*)\Z", re.S)

# Stored in answers when the user typed free text instead of selecting an
# option; the text itself lands in annotations, so answers alone loses it.
NOTES_ONLY = "(notes only)"


def typed_text(text):
    """Return what the user actually typed, or None for pure harness noise."""
    if not text.startswith(NOISE):
        return text
    salvaged = [g.strip() for m in ARGS.finditer(text) for g in m.groups() if g]
    return "\n".join(salvaged) or None


def elide(text):
    """Keep the opening and the operative ending of an unusually long turn."""
    if len(text) <= 6000:
        return text
    return text[:4000] + "\n[...]\n" + text[-2000:]


def flatten(content):
    """Join the text of a payload that is either a string or a list of parts."""
    if isinstance(content, str):
        parts = [content]
    else:
        parts = [p.get("text", "") for p in content or []
                 if isinstance(p, dict) and p.get("type") == "text"]
    return "\n".join(p for p in parts if p).strip()


def answered(rec):
    """Join a record's AskUserQuestion answers as "<question>"="<answer>" pairs."""
    result = rec.get("toolUseResult")
    answers = result.get("answers") if isinstance(result, dict) else None
    if not isinstance(answers, dict):
        return ""
    notes = result.get("annotations")
    notes = notes if isinstance(notes, dict) else {}
    pairs = []
    for question, answer in answers.items():
        note = notes.get(question)
        note = note.get("notes") if isinstance(note, dict) else None
        if note and answer == NOTES_ONLY:
            answer = note
        elif note:
            answer = f"{answer} / {note}"
        pairs.append(f'"{question}"="{answer}"')
    return "\n".join(pairs)


seen = ()
for line in open(sys.argv[1], encoding="utf-8"):
    try:
        rec = json.loads(line)
    except ValueError:
        continue
    if rec.get("isSidechain"):
        continue
    kind = rec.get("type")
    if kind == "user":
        content = rec.get("message", {}).get("content")
        text = "\n".join(t for t in (flatten(content), answered(rec)) if t)
    elif kind == "attachment":
        att = rec.get("attachment") or {}
        if att.get("type") != "queued_command":
            continue
        if (att.get("origin") or {}).get("kind") != "human":
            continue
        text = flatten(att.get("prompt"))
    else:
        continue
    if not text:
        continue
    typed = typed_text(text)
    if not typed:
        continue
    stamp = rec.get("timestamp", "")
    if (stamp, typed) != seen:
        seen = (stamp, typed)
        print(f"--- {stamp}\n{elide(typed)}\n")
PY
```

A session driven entirely by skill pipelines can yield no typed user turns at all. Then the evidence lives on the assistant side: rerun the extraction with the `user` branch's type check changed to `assistant`, keeping the same flattening.

### 3. Identify Evidence

Read the extracted turns in order and collect:

- **Corrections** — the user interrupted, said no, redirected, or fixed something by hand
- **Repeated guidance** — the same instruction given more than once
- **Preferences** — formatting, naming, style, or tool choices the user expressed
- **Failure modes** — an approach that failed, with what replaced it
- **Other** — anything else that stays true beyond this session

A correction is ambiguous without the thing it corrected. For each one, locate its record with `grep -n "<timestamp>" "<transcript path>"` and read the preceding records with a line-range slice such as `sed -n '<start>,<end>p'` to see what prompted it, then state that in one line. Two hits mean a queued message: slice back from the earlier one, where the user was still watching the work that prompted it.

Keep items that would still hold in a future session. Drop one-off instructions that only steer the task at hand.

## Sweep Process

Follow this instead of the Mining Process when mining the project's whole history rather than one session.

### 1. List Every Transcript

Keep every Mining Process filter except the distinctive-phrase match, and add one the sweep needs on its own: the prefix glob also matches sibling projects whose encoded name extends the root's, so filter on the `cwd` the records carry. Take the matches oldest first:

```bash
python3 - "<project root>" <<'PY'
import glob, json, os, sys

root = os.path.realpath(os.path.expanduser(sys.argv[1]))
config_home = os.path.expanduser(os.environ.get("CLAUDE_CONFIG_DIR") or "~/.claude")
paths = glob.glob(os.path.join(config_home, "projects", "*", "*.jsonl"))
for path in sorted(paths, key=os.path.getmtime):
    seen = set()
    with open(path, encoding="utf-8") as fh:
        for line in fh:
            try:
                cwd = json.loads(line).get("cwd")
            except ValueError:
                continue
            if not cwd or cwd in seen:
                continue
            seen.add(cwd)
            resolved = os.path.realpath(os.path.expanduser(cwd))
            if resolved == root or resolved.startswith(root + os.sep):
                print(path)
                break
PY
```

Drop the most recently modified match: that is the live session, already covered by the scan that dispatched you. When no file matches, or none remains after that drop, report it in one line and stop.

Drop what a previous run already distilled: files older than the cutoff you were given, and the turns preceding the last `/self-improve` invocation in any file that holds one. That invocation is a `<command-name>/self-improve</command-name>` record, which the extraction below discards as a harness wrapper, so find it in the raw file and slice from there, resolving each transcript to the path the next step reads:

```bash
LINE=$(grep -n 'command-name>/self-improve<' "<transcript>" | tail -1 | cut -d: -f1)
INPUT="<transcript>"
if [ -n "$LINE" ]; then
  INPUT="<scratch>/<session-id>.jsonl"
  tail -n +$((LINE + 1)) "<transcript>" > "$INPUT"
fi
```

Match that record shape rather than the bare string `/self-improve`, which also matches the installed skill path and ordinary prose.

### 2. Extract Each One

Run the Mining Process extraction script unchanged over each resolved input path rather than writing a fresh one. Without its `NOISE` filter the output is mostly injected skill preambles and the typed turns are buried.

Loop over those paths in a single Bash call, printing each transcript's own path as a header before its extraction and appending both to one scratch file outside the repo. Read that file rather than the extraction output, in oldest-first slices when it is large, carrying the candidate items from each slice forward into the next.

### 3. Identify Evidence Across Sessions

Collect per the Mining Process categories, tracing the context of a correction only for items that survive as candidates. Note where the same guidance appears in more than one session: repetition across sessions is the signal that separates a documentation gap from one-off steering.

Report per the Output Format below, adding a `**Sessions**` line to each entry naming the transcripts it came from.

## Output Format

```
## Recovered Evidence

### <category>: <one-line claim>
- **Quote**: "<verbatim user words>"
- **Context**: <what prompted it>
- **When**: <timestamp>
- **Sessions**: <transcript paths — sweep only>
```

Order the entries by the category order above. When nothing durable survives, say so in one line.
  • SKILL.md 19.2 KB 
    ---
name: self-improve
description: "Extract lessons from the current session, or sweep the project's past sessions when asked, and route them to the appropriate knowledge layer (project AGENTS.md, auto memory, existing skills, or new skills). Use when the user asks to \"self-improve\", \"distill this session\", \"distill past sessions\", \"sweep past sessions\", \"extract lessons from all sessions\", \"save learnings\", \"update CLAUDE.md with what we learned\", \"capture session insights\", \"remember this for next time\", \"extract lessons\", \"update skills from session\", 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. Claude Code loads a subdirectory's file on demand when files in that subtree are accessed, so a lesson scoped to one subtree belongs in the nearest enclosing file, with the root reserved for project-wide rules.
- **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 but do not read them yet — Step 2 needs to run first so you know what to look for.

### Skill Ownership Detection

Classify every skill this session touched:

- Skills that live in the project are user/project skills
- If `~/.turbo/repo/` exists, list directories in `~/.turbo/repo/claude/skills/`; any skill in `~/.claude/skills/` with a matching directory there is a turbo skill
- For every other skill in `~/.claude/skills/`, read `~/.agents/.skill-lock.json`. Its top-level `skills` object is keyed by skill name, and a skill listed there was installed from a source that replaces it wholesale on its next update. Match on the resolved path rather than the name alone, against the entry's `skillPath`, so a local fork that replaced the installed copy is not mistaken for it. A skill that matches is package-managed. The signal runs one way: absence from the file leaves ownership genuinely open, so carry an unlisted skill into Step 4 as ownership-unresolved

**Verification rule (mandatory before routing in Step 4):** For every candidate skill that is about to be routed as turbo, confirm with a fresh `test -d ~/.turbo/repo/claude/skills/<name>` check that the skill actually lives in the turbo repo. Do not rely on remembered listings from earlier in the session, filename hits in grep output, or assumptions based on where a SKILL.md was read from. A miss here mislabels a user/project skill as turbo, triggers the contribution flow unnecessarily, and can introduce session-specific content into a shared skill — so the check is not optional.

**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 installed-copy indirection and no contribution flow.

## 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 [references/transcript-miner.md](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. **Skip** otherwise.

Propose a cutoff first: take the newest modification time in the memory directory from Step 1, state it, then use `AskUserQuestion` to confirm sweeping from it or sweeping the whole history. A memory file's timestamp records a write rather than a completed sweep, so it bounds the work without settling what a previous run covered. When the directory is absent or empty, sweep the whole history without asking.

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. The confirmed cutoff as an ISO-8601 timestamp, or that there is none
3. An instruction to read [references/transcript-miner.md](references/transcript-miner.md) and follow its sweep process

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

### Identify Session Skills

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

- Scan the conversation for Skill tool invocations and SKILL.md reads from `~/.claude/skills/`
- 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 this priority:

1. **Corrections** — Where the user interrupted, said "no", "actually", "stop", "not like that", redirected, or manually fixed something Claude did wrong. Highest-value lessons.
2. **Repeated guidance** — Instructions the user gave more than once. Across separate sessions this counts even where each instance reads as ordinary steering on its own.
3. **Skill-shaped knowledge** — Domain expertise that was needed repeatedly, tool/API integration details that had to be looked up, decision frameworks that emerged for evaluating options, content templates or writing conventions that were refined, and multi-step workflows where ordering mattered (as reusable domain knowledge, not the workflow itself — see #4).
4. **New workflows** — Did this session establish a novel multi-step procedure, coordination pattern, or automation that worked? A successful workflow that would need to be repeated is a prime skill candidate — even if it ran fine this time. Distinct from #3: this captures the procedure itself as a repeatable artifact, not knowledge about how to do it. Flag it.
5. **Preferences** — Formatting, naming, style, or tool choices the user expressed.
6. **Failure modes** — Approaches that failed, with what worked instead. For tool or script call failures, trace back to the information source that led to the error and route the fix there (e.g., clarify a reference file, update skill instructions, add missing documentation).
7. **Domain knowledge** — Facts or conventions Claude needed but did not have.
8. **Improvement opportunities** — Out-of-scope improvements noticed during work: code that could be refactored, missing tests, performance issues, readability concerns, or feature ideas that were intentionally skipped to stay focused. **Skipped findings count here**: when code simplification or code review identified a genuine improvement or issue but it was skipped for this session, route it as a project improvement so it isn't lost.
9. **Trusted reviewer feedback** — Human PR review comments that reveal project conventions, patterns, or corrections. Trusted reviewers are repo collaborators with `admin` or `maintain` roles (determine via `gh api repos/{owner}/{repo}/collaborators --jq '.[] | select(.role_name == "admin" or .role_name == "maintain") | .login'`). Their feedback takes precedence over other reviewers and AI bots when there are contradictions.

After scanning, read all skill SKILL.md files (they are small). This gives Step 4 full context for routing.

## Step 3: Filter

Keep only lessons that are:
- **Stable** — likely to remain true across future sessions
- **Non-obvious** — Claude would not already know this
- **Actionable** — can be expressed as a rule or instruction
- **Not already documented** — absent from the files read in Steps 1 and 2, from each skill's `references/` and other supporting files, and from the project's own knowledge stores. Search all of those for each candidate's keywords rather than assuming. A lesson documented only in an unrelated subtree's CLAUDE.md/AGENTS.md still counts as undocumented for the subtree it actually applies to.
- **Still a concern** — the issue is not already fixed by changes made in this session. If a bug was found and fixed, or a missing feature was added, future sessions will see the corrected code — they don't need a reminder about the old problem. **Exception: successful workflows and procedures are not "resolved" — they're skill candidates precisely because they worked and will need to be repeated.** When sweeping past sessions, judge this against the current state of the code and docs rather than against this session's changes.

Discard anything session-specific, speculative, one-off, or already resolved by code changes in this session (but not successful workflows — see exception above). If no lessons survive filtering, tell the user and stop.

## Step 4: Route Each Lesson

Assign each surviving lesson to exactly one destination.

**Skill-first rule (mandatory):** Before consulting the table below, check whether the lesson corrects, refines, or adds a guardrail to any existing skill's behavior — turbo or user/project. This includes lessons about skipping steps, wrong defaults, missing edge cases, or any "don't do X when running /skill-name" correction. If yes, route to that skill. Do not route skill corrections to auto memory or CLAUDE.md — they belong in the skill they correct. This rule is not a preference; it is a hard constraint that takes precedence over the table rows below.

**Package-managed skills (mandatory):** A skill Step 1 classified as package-managed from the lock file routes its lesson straight to **Auto memory**, recording the skill it applies to, with no question put to the user: the lock file has already settled ownership. A skill under `~/.claude/skills/` that Step 1 left ownership-unresolved may still be one a package manager replaces wholesale on its next update, discarding any edit made here. Before routing a lesson to such a skill, say plainly that an edit to it survives only while the user maintains it themselves. Then use `AskUserQuestion` to ask which is the case, with the options phrased as that effect: edits to this skill stick, or the next update overwrites them. Route the lesson to **Auto memory** when a package manager maintains the skill, recording the skill it applies to so the knowledge survives the next update. For those skills this rule outranks the skill-first rule, the routing table rows, and the tiebreakers below.

| Destination | Criteria |
|---|---|
| **Project improvements** | Actionable improvement to existing **code**: refactoring, performance, reliability, readability, testing, or DX. Not for documentation fixes — factual errors in CLAUDE.md belong in the **Project CLAUDE.md / AGENTS.md** row. Route to `.turbo/improvements.md` via the `/note-improvement` skill. |
| **Auto memory** | Discovered knowledge with no skill home: API quirks, debugging workarounds, compiler gotchas, tool pitfalls, user preferences. Must not overlap with any existing skill's domain — if it does, route to the skill instead (see skill-first rule above). A lesson the package-managed skills rule sends here stays here, whatever domain it overlaps. |
| **Project CLAUDE.md / AGENTS.md** | Intentional project decisions: conventions, architecture, stack choices, build setup, module boundaries. Also factual corrections to CLAUDE.md content (wrong commands, outdated paths, incorrect conventions) — fix these directly, do not defer to Project improvements. When the lesson applies only to one subtree, route it to the nearest enclosing CLAUDE.md/AGENTS.md; reserve the root file for project-wide decisions. |
| **Existing user/project skill** | Lesson would improve a skill's instructions, supporting files, or reference materials, add a missing edge case, correct its workflow, or refine its trigger conditions. Route to any skill whose *domain* covers the lesson — not just the skill worked on in this session. Changes go to the skill file directly. No contribution flow. |
| **New skill** | A cohesive body of knowledge emerged that deserves its own on-demand context. The test: would this knowledge be too large for a CLAUDE.md section, and should it only be loaded when relevant? See the skill categories table below. |
| **Existing turbo skill** | Same criteria as **Existing user/project skill** above, but for turbo skills. **Before routing here, run `test -d ~/.turbo/repo/claude/skills/<name>`; if the directory does not exist, route to the Existing user/project skill destination instead, subject to the package-managed skills rule above.** Changes go to the installed copy at `~/.claude/skills/`, and are flagged for contribution (see Step 6). |
| **No destination** | Does not clearly fit any destination. Drop it. Routing a weak lesson is worse than losing it. |

**Skill categories:**

| Category | What it encodes | Example |
|---|---|---|
| Domain expertise | Best practices, patterns, API preferences | SwiftUI expert, Core Data guide |
| Tool/Service integration | API references, operations, ID formats | Paddle, Stripe, Keycloak |
| Decision framework | Judgment criteria, confidence levels, triage | Evaluate findings, performance audit |
| Content template | Writing conventions, tone, structure | Drafting, blog post, changelog |
| Knowledge/Research | Information discovery, schema definitions | Knowledge base, research process |
| Orchestrated workflow | Stateful multi-step procedures | Process ticket, process income |

**Splitting heuristic:** When a session creates scripts or multi-step procedures, split the lesson: a brief pointer goes to CLAUDE.md (script names, purpose), and the full workflow goes to a skill. Don't collapse them into a single CLAUDE.md entry.

**Tiebreakers (in priority order):**
1. **Skill correction → skill (hard rule).** Any lesson that corrects, constrains, or refines a skill's behavior MUST route to that skill. Never to auto memory, never to CLAUDE.md. This is the highest-priority routing rule, ahead of every tiebreaker below and yielding only to the package-managed skills rule above.
2. **Turbo skill vs. CLAUDE.md → always the turbo skill.** Broader impact (benefits all turbo users), better scoped, loaded only when relevant.
3. **Skill vs. CLAUDE.md → always the skill.** Skills are more discoverable, better scoped, and loaded only when relevant.
4. **Skill vs. auto memory → always the skill.** If a lesson falls within the domain of an existing skill, it goes to the skill. Auto memory is for knowledge that has no skill home, and for the domain of a skill a package manager maintains.
5. **CLAUDE.md vs. auto memory** — intentional decisions go to CLAUDE.md. Discovered knowledge (gotchas, workarounds, quirks) goes to auto memory.
6. **Lesson vs. improvement** — if the item is *knowledge to remember*, it's a lesson. If it's *work to do later*, it's an improvement. They don't compete — the same session can produce both.

## Step 5: Present Routing Plan

Output a table as text before making any changes:

```
| # | Lesson | Destination | Action |
|---|--------|-------------|--------|
| 1 | Always use X for... | Project AGENTS.md | Append to ## Conventions |
| 2 | The /create-pr skill should... | ~/.claude/skills/create-pr | Update Step 2 |
| 3 | Multi-step deploy workflow | New project skill | Create new skill |
| 4 | User prefers short commit msgs | Auto memory | Update <resolved memory target> |
```

For each lesson, show: concise summary, exact target file/skill, and whether it's an append, update-in-place, or new creation. For Auto memory, name the resolved project-memory target so the approval covers the durable write at that path.

Then use `AskUserQuestion` with these options: **Approve** or **Reject**.

## Step 6: Execute

Apply approved changes in order:

1. **Improvements** — For items routed to project improvements, run the `/note-improvement` skill with the summary, location, and rationale for each.
2. **Updates to auto memory** — Read the target, find the right section, append or update in place, following the memory system conventions from the system prompt.
3. **Updates to CLAUDE.md / AGENTS.md** — Read the target file selected in Step 4 (the root file or a nested subtree file), find the right section, append or update in place. Match the tone and format already present.
4. **Updates to user/project skills** — Run the `/create-skill` skill to apply changes to any file inside the skill directory (SKILL.md, references, scripts, assets).
5. **New skills** — Run the `/create-skill` skill for each new skill. Provide the trigger conditions and relevant context from the session.
6. **Updates to turbo skills** — For each lesson routed to a turbo skill:
   1. Read `~/.turbo/repo/claude/SKILL-CONVENTIONS.md` so turbo-specific conventions are in context before any editing.
   2. Run the `/create-skill` skill to update the installed copy at `~/.claude/skills/<name>/`.

   Once every turbo skill edit is in place and reviewed, use `AskUserQuestion` to ask "These turbo skill improvements could benefit other users. Propose them upstream?" When the user confirms, run the `/contribute-turbo` skill once for all of them.

Then use the TaskList tool and proceed to any remaining task.

## Writing Guidelines

- Match the tone and format of the target file
- Use imperative mood and short declarative sentences
- Group related insights under a descriptive heading
- Omit rationale unless the rule would seem arbitrary without it
- Never include temporary state, in-progress work, or task-specific details
- Keep lessons generic—avoid overly concrete examples; state the rule, not the instance
- For AGENTS.md: write as agent documentation — project rules any AI agent on this repo should follow
- For auto memory: write as personal project notes — concise, operational, organized by topic
- For skills: follow the conventions in the existing skill collection
- For files that live in the repo (CLAUDE.md / AGENTS.md and project skills): name only mechanisms that live in the repo too; describe an installed skill's behavior generically

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude