/reflect-skills

description: Discover skill candidates from repeating session patterns
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TodoWrite

Arguments

• `--days N`: Analyze sessions from last N days (default: 14)
• `--project <path>`: Analyze sessions from a specific project (default: current project)
• `--all-projects`: Analyze ALL projects (slower, use when looking for cross-project patterns)
• `--dry-run`: Show analysis without generating skill files

Context

• Current project: !`pwd`
• Session files location: `~/.claude/projects/`
• Skills location: `.claude/commands/` (per-project) or `~/.claude/commands/` (global)

Your Task

You are analyzing session history to discover **repeating patterns** that could become reusable skills.

IMPORTANT: AI-Powered Detection

**DO NOT use hardcoded patterns, regex, or keyword matching.**

Your job is to **reason** about the sessions and identify: 1. **Workflow patterns** - Multi-step sequences the user requests repeatedly 2. **Misunderstanding patterns** - Corrections that keep happening (could become skill guardrails) 3. **Prompt sequences** - Similar intents expressed in different words

Use your semantic understanding. The same intent might appear as:

• "search for X on linkedin"
• "find X's linkedin profile"
• "lookup X on linkedin"

These are the **same pattern** despite different wording.

---

Workflow

Step 1: Initialize Task Tracking

**REQUIRED:** Use TodoWrite immediately to show progress. Update after each step.

{
  "todos": [
    {"content": "Parse arguments", "status": "in_progress", "activeForm": "Parsing command arguments"},
    {"content": "Gather session data", "status": "pending", "activeForm": "Reading session files"},
    {"content": "Check existing commands", "status": "pending", "activeForm": "Checking existing commands"},
    {"content": "Analyze for patterns", "status": "pending", "activeForm": "Analyzing sessions for patterns"},
    {"content": "Propose skill candidates", "status": "pending", "activeForm": "Proposing skill candidates"},
    {"content": "Assign skills to projects", "status": "pending", "activeForm": "Assigning skills to projects"},
    {"content": "Get user approval", "status": "pending", "activeForm": "Getting user approval"},
    {"content": "Generate skill files", "status": "pending", "activeForm": "Generating skill files"},
    {"content": "Validate skills", "status": "pending", "activeForm": "Validating generated skills"}
  ]
}

Step 2: Parse Arguments

Check for:

• `--days N` → Limit to last N days of sessions (default: 14)
• `--project <path>` → Specific project path
• `--all-projects` → Scan all projects (otherwise default to current project)
• `--dry-run` → Analysis only, no file generation

**Default behavior:** Only scan current project unless `--all-projects` is specified.

Step 3: Gather Session Data

**Default behavior:** Only scan current project's sessions unless `--all-projects` specified.

# Resolve this project's session directory. Do NOT encode the path in shell:
# `sed 's|/|-|g'` leaves "_", "." and spaces alone, so it names a folder
# Claude Code never writes to and the scan silently finds nothing.
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/project_paths.py"

Read `session_dir`, `session_dir_exists` and `session_files` from the JSON it prints. If `session_dir_exists` is false, report that and stop.

If `--all-projects` is specified:

# Find all project session directories
ls -la ~/.claude/projects/ 2>/dev/null | head -20

Find session files:

# Find recent sessions (adjust date filter based on --days)
find "$SESSION_PATH" -name "*.jsonl" -mtime -14 -type f 2>/dev/null

**Extract user messages using the existing script:**

# Use the plugin's extraction script - DO NOT reinvent with bash/jq
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/extract_session_learnings.py" "$SESSION_FILE"

The extraction script handles:

• String and list content formats
• isMeta filtering (excludes command expansions)
• Skip patterns (XML, JSON, tool results)

**What to extract:**

• User prompts (natural language requests)
• Sequences of tool calls that followed
• Any corrections or clarifications

Step 3b: Check Existing Commands

Before analyzing patterns, discover what skills already exist:

# Check current project
ls .claude/commands/*.md 2>/dev/null | xargs -I{} basename {} .md

# Check global commands
ls ~/.claude/commands/*.md 2>/dev/null | xargs -I{} basename {} .md

Store the list of existing command names. During pattern analysis (Step 4), if a pattern's suggested name matches an existing command:

• **Skip it** from the NEW candidates list
• Show it in "Existing skills (patterns match)" section

This prevents proposing duplicates.

Step 4: Analyze for Patterns (AI-Powered)

**This is the core step. Use your reasoning to identify patterns.**

Read the extracted session data and think:

1. **Workflow Repetition**

• "I see the user asked for [X] multiple times"
• "Each time, I performed steps: A → B → C"
• "This could be automated as a skill"

2. **Semantic Similarity**

• "These 3 requests have different wording but same intent"
• "User wants to [accomplish Y] but phrases it differently"
• "A skill with good trigger detection would help"

3. **Correction Patterns**

• "User corrected me twice about [Z]"
• "This should be a guardrail in the skill"
• "Next time, the skill should do [Z] by default"

**Output your analysis GROUPED BY PROJECT:**

═══ PROJECT: edu-website ═══

PATTERN 1: Campaign Analytics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Evidence (all from edu-website):
- Session [date]: "review analytics for..."
- Session [date]: "check campaign performance..."

Intent: [What the user is trying to accomplish]

Typical Steps:
1. [First action]
2. [Second action]
3. [Third action]

Corrections Applied: [Any guardrails learned from corrections]

Suggested