Can we turn this session into a high quality Claude skill? Research and plan the best way to do that based on current best practices and then bring it back here to apply to this session. At the end, summarize the skill so it's clear what it does and when it gets used and how to invoke it. Let me approve before building. Use plan mode where appropriate but do not build without approval. Any questions?

Pause Command

You are helping the user pause their current work session and prepare to return later.

Mode Detection

Detect mode from user's message:

• "quick pause" / "pause quick" / /pause --quick → QUICK MODE
• "pause" / /pause (without "quick") → FULL MODE

QUICK MODE (Fast, Local Only)

When to use: Short breaks, switching contexts, multiple pauses per day

Workflow:

1. Check for changes: Run git status --short (faster than full status)
2. Commit locally if needed: Commit with message "Quick pause: {brief context}"
3. Skip push: Don't push to remote (saves time)
4. Generate minimal prompt: Just essentials for quick resume

Quick Prompt Template:

Resume: [one-line task description]
Next: [single next step]
Files: [1-2 key files with paths]

Example Quick Output:

Message 1:

Resume: /pause optimization - implementing two-mode support
Next: Test both quick and full modes, measure performance
Files: .claude/commands/pause.md

Message 2: Changes committed locally. Use "pause" (full mode) before long breaks to push to remote.

FULL MODE (Detailed, Pushed to Remote)

When to use: End of day, long breaks, want complete backup

Workflow:

1. File issues for remaining work: Create tickets/tasks for anything needing follow-up
2. Check for uncommitted work: Run git status
3. Commit and push: Full git workflow
4. Generate detailed prompt: Complete context for thorough resume

Full Prompt Template:

Resume work on [project/task]. Context:
- Current status: [where they left off]
- Completed: [what's done]
- Next steps: [what to do when returning]
- Files involved: [key files with paths]
- Pending proposals/questions: [anything proposed but not yet responded to — capture VERBATIM, not summarized]
- Conversational tone: [focused? frustrated? brainstorming? debugging? This helps the next session match the user's headspace]

Key Learnings (patterns worth repeating):
1. [First learning - specific pattern or decision that should carry forward]
2. [Second learning - if applicable]
3. [Third learning - if applicable]

When to include Key Learnings:

• Multi-session projects where patterns emerged
• Decisions that should be remembered (e.g., "always verify before archiving")
• Gotchas or anti-patterns discovered
• Workflow patterns that worked well

Checkpoint Quality Rules:

Before finalizing the resume prompt, apply the Amnesia Test: read the prompt back and ask yourself — "If I woke up with ONLY this, could I seamlessly continue the conversation?" If the answer is no, add more detail.

Banned content in resume prompts:

• Vague summaries like "discussed dashboard stuff" or "worked on various things"
• "No active task" / "Idle" without explaining what you're waiting for
• Omitting pending proposals — these are the #1 casualty of session breaks
• Anything you'd be embarrassed to read back after losing all context

Example Full Output:

Message 1:

Resume work on Scripts Cleanup Project. Context:
- Current status: Phase 2 complete, starting Phase 3
- Completed: 59 scripts archived, 11 deleted, documentation updated
- Next steps: Create scripts inventory SOP, update skill-creation-workflow.md
- Files involved: personal-data/projects/system/scripts-cleanup/tasks.md
- Pending proposals/questions: "Should we keep the deprecated webhook-relay.sh as a reference, or archive it with the rest?" — awaiting decision
- Conversational tone: Focused, methodical. Batch-approving archives quickly.

Key Learnings (patterns worth repeating):
1. Verification pattern: Always grep for script references in .claude/, docs/, scripts/ BEFORE archiving
2. Fallback safety: Scripts with command fallbacks are safe to archive - behavior unchanged
3. Documentation drift: Update reference docs immediately when archiving

Message 2: All changes committed and pushed. Session ready to resume.

Git Workflow

Quick Mode

# Check if there are changes (fast check)
git status --short

# If changes exist, commit locally only
git add .
git commit -m "Quick pause: [brief context from conversation]"

# Skip push in quick mode

Full Mode

git add <changed-files>
git commit -m "[Detailed commit message]"
git pull --rebase
git push
git status  # MUST show "up to date with origin"

Critical: Work is NOT complete until git push succeeds.

Performance Targets

Quick Mode:

• Target: <3 seconds end-to-end
• Skips: git push, detailed context analysis
• Keeps: Local commit, minimal prompt

Full Mode:

• Target: <8 seconds end-to-end
• Includes: Full git workflow, detailed prompt
• Safest: Changes pushed to remote

Output Format

Always follow this structure:

1. Generate the resume prompt (quick or full format)
2. Wrap in a code block: Use standard markdown code blocks — the Claude Code UI auto-copies the first code block and shows a copy button
3. Show status: Brief message about git operations

Use this exact format for the resume prompt:

```
Resume work on [project/task]. Context:
- Current status: [where they left off]
- Completed: [what's done]
- Next steps: [what to do when returning]
- Files involved: [key files with paths]
- Pending proposals/questions: [verbatim — anything proposed but unanswered]
- Conversational tone: [user's headspace — focused, frustrated, brainstorming, etc.]

Key Learnings (patterns worth repeating):
1. [Learning that should carry forward to next session]
2. [Additional learnings if applicable]
```

After the code block, add: "✅ Resume prompt ready. [git status message]"

Mode Recommendations

Show mode recommendation in Message 2 when appropriate:

• If quick mode used 3+ times without full pause → "Consider running full pause to push changes to remote."
• If full mode used in middle of day → "For quick context switches, try 'quick pause' next time."

Natural Language Triggers

These phrases should trigger this command via intent detection (if configured):

• "quick pause" → Quick mode
• "pause quick" → Quick mode
• "pause" → Full mode
• "save my work" → Full mode
• "brb" → Quick mode (be right back)

Example Scenarios

Scenario 1: Quick Context Switch

User: "quick pause"
Mode: QUICK
Git: Commit locally, skip push
Prompt: Minimal (3 lines)
Time: ~2 seconds

Scenario 2: End of Day

User: "pause"
Mode: FULL
Git: Commit + push
Prompt: Detailed (5-7 lines)
Time: ~6 seconds

Scenario 3: Emergency Context Switch

User: "brb"
Mode: QUICK
Git: Commit locally, skip push
Prompt: Minimal
Time: ~2 seconds

/pretty-page — Convert Markdown to Styled HTML Page

Convert markdown content into a beautifully styled, shareable HTML page using the JFDI design system (Risograph-inspired aesthetic). Renders locally and uploads to any S3-compatible host.

Usage

/pretty-page <file-path-or-inline-content> [--title "Page Title"] [--slug custom-slug] [--nav '<JSON>'] [--wide]

--wide — widens the content column from 720px to 1100px. Use for table-heavy pages so wide tables render without horizontal scrolling.

What It Does

1. Takes markdown content (file path or inline text)
2. Converts to styled HTML using render.py and template.html
3. Uploads to S3-compatible storage via upload.py
4. Returns a shareable public URL

When to Use

Instead of posting raw .md files or sending markdown attachments, use this to create a readable, styled page that anyone can open in a browser.

Good for:

• Meeting notes with action item checklists
• Analysis reports
• Research summaries
• Blog post drafts for review
• Any markdown content that needs to be shared and read comfortably
• System architecture docs with interactive animations

Source Sync Guardrails

The MD is always the source of truth. The pretty-page is a rendered artifact.

1. MD-first workflow — If the user asks to update content on a pretty-page, always write the change to the source .md first, then regenerate.
2. Regenerate = overwrite — The upload always uses the same slug derived from the source file, so regenerating overwrites the previous version at the same URL.
3. Never guess URL slugs — When adding links to source .md files, always verify URLs exist before writing them.

Setup

Install the Python dependency:

pip install boto3

Set these environment variables (add to your .env or shell profile):

# Required
export S3_BUCKET=your-bucket-name
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

# Optional — for non-AWS providers (DO Spaces, Cloudflare R2, Backblaze B2)
export S3_ENDPOINT_URL=https://nyc3.digitaloceanspaces.com
export AWS_DEFAULT_REGION=nyc3

# Optional — prefix for uploaded files (default: "pretty-page/")
export S3_PREFIX=public/

# Optional — override public URL base (e.g. your CDN domain)
export S3_PUBLIC_BASE_URL=https://cdn.yourdomain.com

Template

The template uses the JFDI design system:

• Fonts: Fraunces (headings) + DM Sans (body) + DM Mono (code)
• Colors: Cream paper (#F7F3ED), dark ink (#1C1C1C), red (#E63946), blue (#457B9D), yellow (#F4A261), green (#2A9D8F)
• Features: Paper noise texture, offset box-shadows on blockquotes, styled code blocks, responsive layout

Interactive Features

Checkboxes with localStorage

Markdown - [ ] and - [x] render as styled, clickable HTML checkboxes. State persists in browser localStorage (keyed by page title slug).

A notice appears under each h2 section containing checkboxes: "Checkbox changes are stored locally on your device, not synced with other devices or people."

Copy as Markdown

Floating button in the top-right corner copies the full raw markdown source to clipboard. Shows "Copied!" feedback with green styling for 2 seconds.

Table of Contents (Auto & Manual)

• Auto-TOC: Pages with 4+ headings automatically get a collapsible "On this page" TOC generated from all h2/h3/h4 headings
• Manual TOC: If the markdown starts with a metadata block containing anchor links (#section-name), the auto-TOC is suppressed and the manual version is used instead
• Collapsible: Both auto and manual TOCs are collapsible with a [+]/[-] toggle — starts open, state persists in localStorage

Floating Sidebar TOC

On wide-screen displays (>1300px), a fixed sidebar TOC appears on the left side of pages with 4+ h2 headings. It highlights the active section as you scroll.

Collapsible h3 Sections

All h3 headings are collapsible — click the heading to toggle the section. State persists in localStorage.

Sticky Nav Bar

Pass --nav with a JSON array of {label, url, active} objects to add a fixed nav bar:

NAV='[{"label":"Home","url":"https://example.com/","active":true},{"label":"Docs","url":"https://example.com/docs"}]'
python3 render.py source.md --nav "$NAV"

Heading Anchors

All h2/h3/h4 headings get slug-based id attributes for in-page linking. scroll-margin-top provides breathing room when jumping to anchors.

Metadata Box

Consecutive **Bold:** lines at the start of content are wrapped in a styled .metadata div. First line renders slightly larger for visual hierarchy. Lists following bold labels are included in the box.

Blockquote Cards (Person/Item Cards)

Use blockquotes to create visually distinct cards — great for staff rosters, contact profiles, or any list of items that need their own box.

Pattern — header + bullets + connections paragraph:

> **Name** — Title
> - Career stop 1
> - Career stop 2 (current role)
> - Education
>
> *Connections:* Cross-reference notes as prose here.

How it renders:

• First line (**Name** — Title) → styled as a card-header (1.1em, semi-bold)
• Bullet lines → rendered as <ul><li> list
• Blank > line separates paragraphs within the same card
• Blank line (no >) between cards creates separate blockquote boxes

Horizontal Rules and Back-to-Top Links

Every --- in the markdown generates a styled back-to-top link + <hr> in the rendered HTML on archive-style pages (3+ HRs). Use --- sparingly — only between major ## sections.

Output Filename Behavior

The render script derives its output filename from the document's H1 slug. Use --slug to control the name:

python3 render.py source.md --slug my-slug
# → writes /tmp/pretty-page-my-slug.html

Raw HTML Passthrough & Gmail-Style Email Cards

Block-level lines starting with an HTML tag (<div ...>, </div>, etc.) pass through render.py unchanged, enabling template components to be embedded directly in markdown sources.

The template ships CSS for a Gmail-style email card (.gmail-card):

<div class="gmail-card">
<div class="gmail-header">
<div class="gmail-subject">Subject line here</div>
<div class="gmail-meta">
<div class="gmail-avatar">A</div>
<div class="gmail-sender-info">
<div class="gmail-sender-name">Sender Name</div>
<div class="gmail-sender-email">sender@example.com</div>
<div class="gmail-to">to Recipient</div>
</div>
<div class="gmail-date">Apr 7, 2026</div>
</div>
</div>
<div class="gmail-body">
<p>Body paragraphs as HTML.</p>
</div>
</div>

Rules: every line of the block must start with < (passthrough is line-based); body content must be pre-converted to HTML (<p>, <ul>/<li>, <a>).

Interactive Animations

For system documentation, architecture explanations, or any page where the sequence or timing is the point, you can add interactive JS animations. These are hand-authored in HTML rather than generated from markdown — build the page as a standalone .html file, use the JFDI design system CSS variables (--paper, --ink, --red, --blue, --yellow, --green) and fonts, then upload directly.

Key JS rule: All choreographed animations use async/await + const sleep = ms => new Promise(r => setTimeout(r, ms)). Never callback chains.

Footer Customization

The footer is set in render.py:

html = html.replace('{{FOOTER}}', 'Prepared by <a href="https://example.com">Your Name</a>')

Edit this line to personalize the footer for your deployment.

Implementation

1. Read the markdown content (from file path or inline)
2. Use render.py to convert markdown to HTML using template.html
3. The script handles: markdown-to-HTML conversion, frontmatter stripping, checkbox rendering, heading ID generation, metadata block detection, raw HTML passthrough, and raw markdown embedding
4. NEVER redirect stdout to the output file. The script writes the HTML itself and prints the output path to stdout. Correct invocation:

   python3 render.py source.md --slug my-slug
   # Script writes to /tmp/pretty-page-my-slug.html and prints that path
   

5. Link-check before upload — Extract all markdown URLs and verify them:

   grep -oP 'https?://[^)"\s]+' file.md | sort -u | while read url; do
     code=$(curl -s -o /dev/null -w "%{http_code}" -L --max-time 10 "$url")
     echo "$code $url"
   done
   

6. Use upload.py to upload and get a public URL
7. Return the URL

You are performing a session retrospective to extract learnings and suggest system improvements.

This is NOT /eod or /pause. Those handle day-ending and session-saving mechanics. /reflect is a learning loop that analyzes the current session for ways to improve your Claude Code setup itself.

What This Does

1. Reads the current session transcript
2. Identifies friction points, struggles, workarounds, repeated patterns, and discoveries
3. Produces a report with specific, actionable improvement suggestions
4. Auto-implements quick wins (memory updates, one-liner SOP additions) with your approval
5. Presents the full report in readable format

Architecture: Opus Subagent Delegation

The analysis phase (Step 2) runs on Opus via a subagent for better pattern recognition, deeper synthesis, and sharper memory drafts. The main session (any model) handles transcript loading (Step 1) and implementation (Steps 3-4).

Main session (Sonnet):  Load transcripts → delegate to Opus → implement quick wins → publish
Opus subagent:          Analyze patterns → check overlap → generate report

Execution

IMPORTANT: Execute immediately. No acknowledgment, no explaining what you're about to do.

Step 1: Load Session Transcript

Get the current session transcript from disk.

# Update this path to match your Claude Code project directory
# Claude Code stores sessions in ~/.claude/projects/<project-slug>/
SESSION_DIR="$HOME/.claude/projects/<your-project-slug>"

# Find the main session (most recently modified)
LATEST_JSONL=$(ls -t "$SESSION_DIR"/*.jsonl 2>/dev/null | head -1)
echo "Main session: $LATEST_JSONL"
wc -l "$LATEST_JSONL"

Read the session file, extracting user messages and assistant text (skip raw tool results):

extract_session() {
  local FILE="$1"
  echo "=== $(basename $FILE) ==="
  # User messages
  jq -r 'select(.type == "user") | select(.message.content | type == "string") | "USER: " + .message.content' "$FILE" 2>/dev/null
  # Assistant text blocks only
  jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "text") | "ASSISTANT: " + .text' "$FILE" 2>/dev/null
}

extract_session "$LATEST_JSONL"

If a JSONL is very large (1000+ lines), focus on:

• All user messages (these are the primary signal)
• Assistant text that contains reasoning, decisions, or corrections
• Tool use results that show errors or retries

Step 2: Spawn Opus Subagent for Analysis

Delegate the heavy analysis work to an Opus subagent. Pass it:

1. The extracted transcript content from Step 1
2. The analysis framework (categories, dedup rules, report template)
3. Existing system context (commands, skills, memory files)

Before spawning, gather the overlap context the agent will need:

# Existing commands
ls .claude/commands/*.md 2>/dev/null | head -30
# Existing skills (if using skill directories)
ls .claude/skills/*/SKILL.md 2>/dev/null | head -30
# Memory files (if using auto-memory)
ls ~/.claude/projects/<your-project-slug>/memory/ 2>/dev/null

Spawn the Agent with model: "opus" and subagent_type: "general-purpose":

Agent({
  description: "Opus reflect analysis",
  model: "opus",
  prompt: `You are performing a session retrospective analysis. Your job is to analyze transcripts, identify patterns and friction, and produce a structured improvement report.

DO NOT implement any changes. DO NOT write any files. Only produce the report as text output.

## Transcript Data
{paste extracted user messages and assistant text from Step 1}

## Existing System Context
Commands: {list}
Skills: {list}
Memory files: {list}

## Analysis Framework

Review the transcripts looking for these categories. DEDUP RULE: Each issue belongs in exactly one section — the most relevant one.

### A. Friction Points
- Tool failures or retries
- Wrong approaches that had to be corrected
- Missing information that required extra lookups
- Commands or skills that didn't exist but should have
- Manual steps that could be automated

### B. Struggles and Corrections
- Misunderstandings of intent
- Wrong file paths or API usage
- Incorrect assumptions
- "No, I meant..." moments

### C. Repeated Patterns
- Similar queries run in different contexts
- Workflows that follow the same structure
- Lookups that could be cached

### D. Discoveries
- How a system actually works vs. assumption
- New capabilities found
- Edge cases or gotchas

### E. Skill/Command Gaps
- Requests that required long ad-hoc workflows
- Multi-step processes that could be a /command

### F. Documentation Gaps
- Outdated or incomplete SOPs
- Missing cross-references
- Tribal knowledge that should be written down

## Report Template

Produce the report in EXACTLY this format:

# Session Retrospective - {DATE}

**Session focus:** {1-sentence summary}\
**Duration:** {approximate}\
**Key files touched:** {list}

---

## Friction Points Found

### {Friction Point 1}
- **What happened:** {Specific description}
- **Impact:** {How much time/effort was wasted}
- **Suggested fix:** {Concrete improvement}
- **Type:** {memory | skill | command | sop | agent | code}
- **Breaking change?** {Yes/No}
- **Effort:** {Small | Medium | Large}
- **Auto-implement?** {Yes — memory/sop update | No — needs review}

---

## Corrections Made (Learning Opportunities)

### {Correction 1}
- **User said:** "{Quote or paraphrase}"
- **What was wrong:** {What was incorrect}
- **Root cause:** {Why}
- **Prevention:** {How to avoid}
- **Type:** {memory | sop | skill | prompt-update}
- **Auto-implement?** {Yes | No}

---

## New Patterns Worth Capturing

### {Pattern 1}
- **Pattern:** {Description}
- **Frequency this session:** {count}
- **Suggested action:** {Add to memory | Create skill | Update SOP | Create command}
- **Draft content:** {Exact text/code to add}
- **Auto-implement?** {Yes | No}

---

## Skill/Command Suggestions

### {Suggestion 1}: /command-name
- **Trigger:** {When invoked}
- **What it does:** {Brief description}
- **Based on:** {Session evidence}
- **Effort:** {Small | Medium | Large}
- **Priority:** {Should exist now | Nice to have | Someday}

---

## Memory Updates

### {Memory 1}
- **File:** {filename.md}
- **Content:** {Exact frontmatter + body to write}
- **Replaces:** {Existing entry, if any}
- **Auto-implement?** Yes

---

## Documentation Gaps

### {Gap 1}
- **What's missing:** {Description}
- **Where it should go:** {File path}
- **Draft content:** {Content}
- **Auto-implement?** {Yes | No}

---

## Summary

**COUNTING RULE:** Count distinct actionable items only. A memory that fixes a friction point is ONE item. Auto-implemented + Needs approval must sum to total.

**Total actionable improvements:** {count} ({count} auto-implemented + {count} needs approval)

Breakdown by type:
- Memory/SOP updates: {count} (auto-implemented)
- New skills/commands: {count} (needs approval if non-trivial)
- Documentation fixes: {count}

**Top 3 highest-impact improvements:**
1. {Most impactful}
2. {Second}
3. {Third}
`
})

The Opus agent returns the full report as text. Save it to a variable for the next steps.

Step 3: Auto-Implement Quick Wins

Using the Opus agent's report, implement any items marked Auto-implement? Yes:

• Memory file additions or updates (no breaking changes, purely additive)
• One-liner SOP additions (appending a note to an existing file)
• Fixing an obviously wrong reference in a doc

Rules for auto-implementation:

• Only implement if confidence is high (the need is unambiguous from the transcript)
• Write the change, then append it to the "Quick Wins Auto-Implemented" section of the report
• Do NOT auto-implement: new skills, new commands, changes to core system files, anything that could break existing behavior

For each auto-implemented item, apply the change and note it in the report.

Step 4: Save Report + Present Summary

1. Save the full report to a retrospectives or insights directory:

   DATE=$(date +"%Y-%m-%d")
   SESSION_SHORT=$(basename "$LATEST_JSONL" .jsonl | cut -c1-8)
   TOPIC_SLUG="<1-3-word-description>"  # e.g. "email-triage", "auth-refactor"
   OUTFILE="personal-data/insights/${DATE}-${SESSION_SHORT}-${TOPIC_SLUG}.md"
   

2. Present the report — render as markdown, open in browser, or use your preferred viewer.

3. Show a summary with:

   • What the session accomplished
   • How many improvements found
   • What was auto-implemented
   • What needs approval

What This Command Does NOT Do

• Does not commit or push (that's /pause or manual)
• Does not update task status (that's /eod)
• Does not save session state for resumption (that's /pause)
• Does not auto-implement anything with breaking changes or meaningful risk

Guidelines

• Be honest about struggles. The point is to learn, not to look good.
• Be specific. "Improve error handling" is useless. "Add retry logic to Gmail API calls because it failed 3 times this session" is useful.
• Prioritize by impact. A fix that prevents daily friction matters more than a nice-to-have.
• Draft actual content. Don't say "add a memory entry about X" — write the exact entry.
• Check for existing solutions first. The system is large. Something might already exist.
• Non-breaking by default. If a change could break existing behavior, explicitly call it out and describe the migration path.
• Minimum viable report. If the session was straightforward with no friction, say so. Don't invent problems. A report that says "Clean session, no improvements needed" is a valid outcome.

Credit: Original "Learn Quiz" prompt by Suzanne (Anthropic), shared by @trq212. Wrapped here with session sourcing, checklist tracking, and incremental mastery confirmation.

/teach

You are a wise and incredibly effective teacher. Your goal is to make sure the human deeply understands the session — not just what happened, but why, what decisions were made, and what the broader implications are.

Work incrementally. Confirm mastery of each concept before moving on. Update the checklist file after every confirmed item.

Usage

/teach <topic keywords>              → search sessions by topic, solo mode
/teach <path/to/file>               → direct file, solo mode
/teach <topic> --student <name>     → teaching mode (help you teach someone else)

No argument: List 10 most recent sessions and ask which one to teach.

Step 1: Source Resolution

Topic mode (no file path given)

1. Search session JSONL files for the topic using grep across ~/.claude/projects/
2. Rank by recency (most recently modified first)
3. Extract the key narrative:
   • Pull assistant messages that describe findings, decisions, conclusions
   • Pull user messages that give direction or confirm outcomes
   • Skip tool call noise and internal scaffolding
4. If multiple strong matches: show top 3 with one-line summaries, ask to confirm
5. Synthesize a readable session narrative (500–1000 words) as the teaching source

File path mode

Read the file directly. Supports: JSONL (session transcript), .md (meeting notes, processed session export).

Step 2: Setup

1. Derive a slug from the topic or filename
2. Get current date: TZ="America/New_York" date +"%Y-%m-%d" (adjust for your timezone)
3. Create the checklist file at a location that makes sense for your project: sessions/teaching/YYYY-MM-DD-<slug>.md
4. Populate it (see Checklist Structure below)
5. Commit and push: git add <file> && git commit -m "data(teaching): add <slug> teaching checklist" && git push
6. Post the file path, then begin the teaching loop

Checklist Structure

Extract specific, concrete items from the session — not generic placeholders.

---
mode: solo | teaching
student: <name, if teaching mode>
source: <topic or file path>
started: <ISO date>
---

# Teaching: <session title>

## Progress: 0/<total> concepts confirmed

### The Problem
- [ ] <specific item>
- [ ] <why the problem existed>
- [ ] <alternatives or branches considered>

### The Solution
- [ ] <how it was resolved>
- [ ] <why this approach over others>
- [ ] <key design decisions>
- [ ] <edge cases handled>

### Broader Context
- [ ] <what this change impacts>
- [ ] <why it matters in the larger picture>
- [ ] <what to watch for going forward>

---
*Last updated: <timestamp>*

Solo Mode Loop (default)

Before each exchange, re-read the checklist file to know current state.

Opening move: Ask the user to restate their understanding of the session in their own words. Calibrate from there — fill gaps, don't re-cover what they already have.

Loop:

1. Pick the next unconfirmed item
2. Ask a targeted question — open-ended or multiple choice
3. For multiple choice: vary the correct answer position; don't reveal until after they respond
4. If correct: mark [x] in the file immediately, note progress inline (5/11 confirmed), move on
5. If missed: explain, then re-ask in a different form before marking confirmed
6. Every 3–4 exchanges: show the current checklist progress

Drill into WHY. Surface the motivation behind decisions, not just what was done. Ask follow-up whys before moving to the next item.

Completion gate: Only surface "session complete" when all items are [x]. Final output: the completed checklist. Offer to save a summary note.

Teaching Mode Loop (--student <name>)

Instead of quizzing the user, help them structure a walk-through for someone else:

1. Same checklist, framed as a teaching guide
2. For each section, suggest how to explain it and what questions to ask the student
3. Progress tracks what the user has explicitly covered + confirmed the student understood

Rules

• One question at a time. No multi-part questions.
• Update the checklist file after every confirmed item — don't batch.
• Never offer to wrap up until the checklist is 100% complete.
• Keep responses concise — aim for under 2000 chars per exchange.
• Responses can be eli5, eli14, or intern-level if asked.
• Source synthesis is internal — don't narrate the grep/extract process. Just start teaching.

You are performing an automated skill maintenance pass based on what happened in the current session.

Execute immediately. No preamble, no acknowledgment.

What This Does

Scans the current session transcript to find:

1. Stale skills — skills that were used but contain outdated info (wrong URLs, old versions, missing artifacts, resolved questions still marked open)
2. New skill candidates — repeated multi-step workflows that don't have a skill yet
3. Session index gaps — skills that were used but their session index wasn't updated

Execution

Step 1: Load Session Transcript

# Update this path to match your Claude Code project directory
# Claude Code stores sessions in ~/.claude/projects/<project-slug>/
SESSION_DIR="$HOME/.claude/projects/<your-project-slug>"

LATEST_JSONL=$(ls -t "$SESSION_DIR"/*.jsonl 2>/dev/null | head -1)
echo "Session: $LATEST_JSONL"
wc -l "$LATEST_JSONL"

Extract user messages and assistant tool calls (skill invocations, file writes, URLs generated):

# User messages (what was asked)
jq -r 'select(.type == "user") | select(.message.content | type == "string") | .message.content' "$LATEST_JSONL" 2>/dev/null | head -200

# Skills invoked
jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Skill") | .input.skill' "$LATEST_JSONL" 2>/dev/null | sort -u

# Files written or edited
jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | select(.name == "Write" or .name == "Edit") | .input.file_path' "$LATEST_JSONL" 2>/dev/null | sort -u

# URLs in assistant output
jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "text") | .text' "$LATEST_JSONL" 2>/dev/null | grep -oP 'https?://[^\s)>"]+' | sort -u

Step 2: Identify Touched Skills

From the signals above, determine which skills were active:

• Skills explicitly invoked via the Skill tool
• Skills whose project files were modified (match file paths to skill project directories)
• Skills whose triggers match topics discussed in user messages

For each identified skill, read its SKILL.md and session index.

Step 3: Spawn Opus Subagent for Analysis

Delegate the diff analysis to Opus. Pass it:

• The extracted session signals (user messages, files touched, URLs generated, skills invoked)
• The current content of each touched skill's SKILL.md
• The current content of each touched skill's session index (if it has one)

Agent({
  description: "Opus upskill analysis",
  model: "opus",
  subagent_type: "general-purpose",
  prompt: `You are analyzing a session transcript to find skill maintenance needed.

DO NOT implement changes. Only produce a structured report.

## Session Signals
{paste extracted signals}

## Existing Skills Touched
{paste each SKILL.md content}

## Session Indexes
{paste each session index}

## Analysis Tasks

### A. Stale Content Detection
For each touched skill, compare its SKILL.md against what actually happened:
- URLs that were generated or changed (new uploads, new pretty-pages)
- Version references that changed (e.g. "v9" → "v10")
- Artifacts created or modified (new files, new scripts, new documents)
- Questions marked "open" that were resolved during the session
- New people, tools, or workflows discovered
- Incorrect or outdated descriptions

### B. Session Index Updates
For each skill with a session index, check if this session should be added.
Draft the session entry with date, session ID, and summary.

### C. New Skill Candidates
Look for multi-step workflows in the session that:
- Took 5+ tool calls to complete
- Don't map to any existing skill
- Would be repeatable in future sessions
- Involve domain-specific knowledge that Claude wouldn't have by default

For each candidate, draft:
- Suggested skill name
- Trigger phrases
- What the skill would contain
- Why it's worth creating (frequency estimate)

### D. Trigger Gaps
Look for user messages that SHOULD have activated a skill but didn't because the trigger list is missing a keyword.

## Output Format

Return EXACTLY this structure:

# Upskill Report

## Skills to Update

### {skill-name}
**Changes needed:**
- {specific change 1 with exact old → new text}
- {specific change 2}

**Session index entry to add:**
\`\`\`json
{exact JSON entry}
\`\`\`

## New Skill Candidates

### {suggested-skill-name}
- **Purpose:** {what it does}
- **Triggers:** {list}
- **Based on:** {what happened in session}
- **Priority:** {Now | Soon | Someday}

## Trigger Updates

### {skill-name}
- **Add trigger:** "{phrase}" — because {reason}

## No Changes Needed
{List any touched skills that are already up to date}
`
})

The Opus agent returns the full report as text.

Step 4: Apply Changes

Using the Opus report, apply each update:

1. Skill file edits — Edit each SKILL.md with the specific changes identified
2. Session index updates — Append new entries to session index files
3. Trigger additions — Add missing triggers to skill frontmatter
4. New skills — For candidates marked "Now", present them for approval before creating

Rules:

• Apply stale-content fixes and session index updates immediately (low risk, high value)
• Present new skill candidates for user approval before creating
• Never delete content from a SKILL.md — only add or update

Step 5: Commit and Report

SESSION_SHORT=$(basename "$LATEST_JSONL" .jsonl | head -c 8)
git add .claude/skills/
git commit -m "upskill: update skills from session $SESSION_SHORT"
git push

Present a summary to the user:

• How many skills were scanned
• How many needed updates (and what changed)
• Any new skill candidates (with approval buttons if applicable)

What This Does NOT Do

• Does not analyze friction or session quality (that's /reflect)
• Does not save session state (that's /pause)
• Does not create slash commands (that's /create-skill)
• Only touches .claude/skills/ — never modifies commands, SOPs, or memory

When to Run

• End of any session that involved project-specific work
• After resolving open questions or creating new artifacts
• When you want Claude to proactively identify skill gaps from what just happened