Claude Code retrospect skill: end-of-session cleanup (update plans, record decisions, capture learnings as skills)

README.md

Claude Code Continuous Learning Loop

A small feedback loop that nudges Claude Code to capture non-obvious learnings as reusable skills/rules at the end of every session, instead of letting them evaporate.

How it works

Three pieces:

1. Stop hook (continuous-learning.sh) — fires when Claude tries to end its turn. On the first stop in a session it blocks and tells Claude to run /retrospect first. A /tmp marker file tracks that the prompt has been delivered, so the second stop attempt (after retrospect runs, or after Claude decides there's nothing to capture) goes through cleanly. The marker expires after 5 minutes so it doesn't bleed across unrelated sessions.

2. /retrospect slash command (retrospect.md) — what Claude runs when prompted. It walks through:

   • Updating any active plans in .claude/plans/
   • Logging non-trivial decisions
   • Surfacing candidate learnings, asking the user for explicit approval, and writing them to .claude/skills/ or .claude/rules/

   The hard rule baked into the command: never save a skill without explicit user approval in the same session. Silence ≠ consent. This keeps the skill library from filling up with noise.

3. Hook config in settings.json — wires the hook to the Stop event.

The net effect: every session ends with a small "anything worth saving?" pass. Most of the time the answer is no. When it isn't, the learning lands in a place future Claude will actually load.

Setup

Drop the files into your Claude config:

# 1. Slash command (loaded by name when Claude or you type /retrospect)
mkdir -p ~/.claude/commands
cp retrospect.md ~/.claude/commands/retrospect.md

# 2. Hook script
mkdir -p ~/workspace/.claude/scripts
cp continuous-learning.sh ~/workspace/.claude/scripts/continuous-learning.sh
chmod +x ~/workspace/.claude/scripts/continuous-learning.sh

Then add the hook to ~/.claude/settings.json (merge with whatever's already there):

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/workspace/.claude/scripts/continuous-learning.sh"
          }
        ]
      }
    ]
  }
}

Adjust the script path if you don't keep things under ~/workspace/.claude.

Files

• README.md — this file
• retrospect.md — the /retrospect slash command definition
• continuous-learning.sh — the Stop hook script
• settings-hook-snippet.json — drop-in snippet for ~/.claude/settings.json

Tuning notes

• The 5-minute marker window is long enough to absorb a real retrospect pass and short enough that it won't accidentally suppress the prompt next session.
• If the prompt becomes annoying (e.g. one-shot sessions where there's nothing to learn), the cheapest off-switch is changing "matcher": "" to something more specific, or removing the hook entry entirely.
• The skill itself is opinionated about what to save: non-obvious + reusable + verified. The bar matters — skills are loaded into context, so low-value skills are a tax on every future session.

continuous-learning.sh

#!/bin/bash
# Blocks stop and reminds Claude to run /retrospect first.
# Uses a temp marker so the second stop attempt goes through.

MARKER="/tmp/claude-retrospect-marker"
COOLDOWN_SECONDS=300

# If marker exists and is recent (within cooldown), allow stop
if [ -f "$MARKER" ]; then
  marker_age=$(( $(date +%s) - $(stat -f %m "$MARKER" 2>/dev/null || stat -c %Y "$MARKER" 2>/dev/null) ))
  if [ "$marker_age" -lt "$COOLDOWN_SECONDS" ]; then
    rm -f "$MARKER"
    exit 0
  fi
fi

# Create marker and block
touch "$MARKER"
cat << 'EOF'
{
  "decision": "block",
  "reason": "Before ending, run /retrospect to capture any non-obvious learnings from this session."
}
EOF

retrospect.md

name	retrospect
description	End-of-session cleanup: update plans, record decisions, capture learnings as skills. Use when: (1) session involved debugging or investigation, (2) discovered something not in docs, (3) trial-and-error found a working solution.
version	1.9.1

Retrospect

End-of-session cleanup: update plans, record decisions, and capture learnings.

Instructions

Part 1: Planning Docs

Skip this part for Traba projects (under ~/workspace/ Traba repos like monorepo, worker-app, supervisor-app, firebase, ai-platform, sandbox, slackbot, etc.) — they don't use a plans/ directory.

For other projects, check the repo's top-level plans/ directory for any active plans related to this session.

• If a plan was completed, mark it as complete or delete it
• If a plan is partially done, update progress notes
• If no plans/ directory or no relevant plan exists, skip this step

Part 2: Decision Log

If any non-trivial technical decisions were made during this session:

• Check if a decision log entry already exists in {project}/decisions/
• If not, create one following the format in CLAUDE.md
• Skip if decisions were trivial or already documented

Part 3: Learnings → Skills

Non-obvious, reusable, verified learnings get saved as skills or rules — never memory. Do NOT add anything to the memory system during retrospect. Skills (.claude/skills/) are loaded when relevant (e.g., for specific workflows) — use for reusable technical learnings and gotchas. Rules (.claude/rules/) are always loaded (optionally filtered to file patterns) — use for behavioral guidance and workflow conventions that should apply broadly.

Step 1: Identify learnings

Review the conversation for knowledge worth saving:

• Non-obvious: required investigation, not just a docs lookup
• Reusable: will help with future similar problems
• Verified: actually worked, not theoretical

Also review corrections made to subagent work (Courier commit messages, Cyrano message drafts, etc.). If the user rewrote or corrected a subagent's output, that's a signal the agent definition needs updating — the correction reflects a gap between the agent's conventions and the user's expectations. Surface these as proposed updates to the relevant agent definition (~/.claude/agents/<agent>.md).

Skip if trivial, one-off, or already well-documented elsewhere.

Step 2: Check for memory entries to migrate

Review existing memory entries. If any learning is already captured in memory that should be a skill (e.g., API patterns, debugging gotchas, integration details), flag it for migration: create the skill file and remove the memory entry.

Step 3: Confirm with user — REQUIRED

Never save a skill without an explicit "yes save it" / "go ahead" / equivalent in the same session. Silence, topic changes, and "ok" responses to other questions do NOT count as approval. The user moving on to the next task is NOT implicit consent — surface the proposal again next session if it's still worth saving, or drop it.

List potential learnings and any memory-to-skill migrations, then ask which to save. If the user doesn't explicitly approve, do not create the skill file. Approval must be unambiguous and in response to this proposal, not a different question.

Step 4: Create skill files (only after explicit approval)

For each learning the user explicitly approved, create .claude/skills/[skill-name].md.

Keep skills high-signal. The audience is an LLM that can write boilerplate code trivially. Skills should capture what causes a failure or wrong approach on a first attempt, not how to write the code.

• Pitfalls and gotchas over tutorials and code samples
• One-liner patterns over full code listings (e.g., mailbox "INBOX" of acc not a 30-line script)
• No boilerplate: skip basic API usage, standard error handling, obvious patterns
• Let content dictate structure: don't force Problem/Solution/Verification if a flat list of traps is clearer
• Skills are folders, not just markdown files: add helper scripts, reference data, and libraries next to the entry point. List what files exist and Claude will read them when needed.

Required frontmatter:

---
name: descriptive-kebab-case-name
description: |
  [High-level what this covers. Use when: (1) trigger, (2) trigger.
  Covers: topic, topic.]
version: 1.0.0
---

When updating existing skills, also ask: has the skill drifted toward a tutorial? Trim it back to just the non-obvious parts.

Part 4: Summary

If nothing was updated across all parts, just say "No updates needed."

Otherwise, briefly report what was done:

• Planning docs updated (if any)
• Decision logs created (if any)
• Skills created (if any)

settings-hook-snippet.json

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/workspace/.claude/scripts/continuous-learning.sh"
          }
        ]
      }
    ]
  }
}