| name | improve-skill |
| description | Analyze Claude Code session transcripts to improve existing skills or create new ones. Use when you want to review a past session to identify what worked, what didn't, and how to enhance skill documentation. Extracts session data and provides structured analysis prompts. Triggers on "improve skill", "analyze session", "review session", "skill improvement", "create skill from session", "skill not working", "skill missed", "skill didn't trigger", "enhance skill", "refine skill", "skill feedback", "session transcript", "what went wrong", "skill optimization", "better triggers". |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
ABOUTME: Skill for analyzing Claude Code sessions to improve or create skills
ABOUTME: Extracts session transcripts and provides structured improvement workflows
Improve Skill
Analyze Claude Code session transcripts to enhance existing skills or create new ones.
When to Use This Skill vs Others
Use improve-skill When:
- You've just finished a debugging/automation session and want to analyze it
- You need to extract session transcript for offline review
- You want to identify what went wrong in your workflow
- You're creating new skills from successful workflows
- You want to improve existing skills based on what you learned
- Decision: Use AFTER you've completed a web-automation session
Use web-automation When:
- You're actively debugging or automating something NOW
- Decision: Use BEFORE you would use improve-skill (this is the "doing" skill)
Typical Workflow
1. Run web-automation to debug/automate
(this is the "doing" phase)
2. Save session transcript
3. Use improve-skill to analyze what happened
(this is the "learning" phase)
4. Update skill documentation based on findings
5. Next time, your updated skill helps you work faster
🔄 RESUMED SESSION CHECKPOINT
When a session is resumed from context compaction, verify skill improvement state:
┌─────────────────────────────────────────────────────────────┐
│ SESSION RESUMED - IMPROVE-SKILL VERIFICATION │
│ │
│ Before continuing skill improvement work: │
│ │
│ 1. Was I in the middle of session analysis? │
│ → Check /tmp/ for extracted transcripts │
│ → Check summary for "analyzing", "extracting" │
│ │
│ 2. Was I updating a skill? │
│ → Check which skill was being modified │
│ → Run: uv run validate_skill.py on the skill │
│ │
│ 3. Did the previous work complete? │
│ → Check todo list for pending analysis tasks │
│ → Verify skill validation passed │
│ │
│ If analysis was in progress: │
│ → Re-run the extraction/analysis scripts │
│ → Do NOT assume previous analysis is still valid │
└─────────────────────────────────────────────────────────────┘
Quick Reference
| Script | Purpose |
|---|
extract_session.py | Extract session transcript to markdown |
analyze_session.py | Analyze session for skill improvements |
Run any script with --help for full options:
uv run ~/.claude/skills/improve-skill/scripts/extract_session.py --help
Workflows
1. Improve an Existing Skill
When a skill didn't work as expected, extract the session and analyze it:
uv run ~/.claude/skills/improve-skill/scripts/extract_session.py \
--session-id <session-id> \
--output /tmp/session.md
uv run ~/.claude/skills/improve-skill/scripts/analyze_session.py \
--transcript /tmp/session.md \
--skill ~/.claude/skills/<skill-name>/SKILL.md \
--output /tmp/analysis.md
Then start a new Claude Code session with:
Review the analysis in /tmp/analysis.md and update the skill accordingly.
Why a new session? Starting fresh ensures only the transcript and skill are loaded,
without prior context influencing the analysis.
2. Create a New Skill from Session
When you've done something successfully and want to capture it as a skill:
uv run ~/.claude/skills/improve-skill/scripts/extract_session.py \
--session-id <session-id> \
--output /tmp/session.md
uv run ~/.claude/skills/improve-skill/scripts/analyze_session.py \
--transcript /tmp/session.md \
--create-skill \
--output /tmp/new_skill_prompt.md
Then start a new session to create the skill based on the analysis.
3. Quick Session Review
List recent sessions and extract the most recent one:
uv run ~/.claude/skills/improve-skill/scripts/extract_session.py --list
uv run ~/.claude/skills/improve-skill/scripts/extract_session.py --latest
uv run ~/.claude/skills/improve-skill/scripts/extract_session.py \
--latest \
--cwd /path/to/project
Finding Session IDs
Session IDs can be found:
- In the Claude Code UI (shown in session info)
- Using the
/tasks command
- By listing sessions:
uv run ~/.claude/skills/improve-skill/scripts/extract_session.py --list
Analysis Framework
When analyzing a session transcript, look for:
| Pattern | What to Look For |
|---|
| Confusion | Where did the agent struggle or misunderstand? |
| Missing Info | What information was needed but not in the skill? |
| Workarounds | What manual steps were needed that could be automated? |
| Errors | What errors occurred and how were they resolved? |
| Success | What approaches worked well and should be documented? |
| Wrong Skill | Was a different skill more appropriate? |
Output Format
The analysis produces structured recommendations:
## Session Analysis
### What Worked Well
- [List of successful approaches]
### Issues Identified
- [List of problems encountered]
### Recommended Improvements
- [Specific changes to make to the skill]
### Missing Documentation
- [Information that should be added]
Help Output Examples
extract_session.py
usage: extract_session.py [-h] [--list] [--latest] [--session-id SESSION_ID]
[--cwd CWD] [--output OUTPUT]
Extract Claude Code session transcripts to markdown
options:
-h, --help show this help message and exit
--list List all available sessions
--latest Extract most recent session
--session-id SESSION_ID, -s SESSION_ID
Extract specific session by ID
--cwd CWD Filter sessions by working directory
--output OUTPUT, -o OUTPUT
Save transcript to file (default: stdout)
Examples:
uv run extract_session.py --list
uv run extract_session.py --latest --output /tmp/session.md
uv run extract_session.py --session-id abc123 --output /tmp/session.md
analyze_session.py
usage: analyze_session.py [-h] --transcript TRANSCRIPT [--skill SKILL]
[--create-skill] [--quick] [--output OUTPUT]
Analyze Claude Code session transcripts for skill improvement
options:
-h, --help show this help message and exit
--transcript TRANSCRIPT, -t TRANSCRIPT
Path to the session transcript markdown file (required)
--skill SKILL, -s SKILL
Path to existing skill SKILL.md to improve
--create-skill Generate prompt for creating a new skill
--quick Quick analysis summary only (no full prompt)
--output OUTPUT, -o OUTPUT
Output file path (default: stdout)
Examples:
# Quick analysis
uv run analyze_session.py --transcript /tmp/session.md
# Improve existing skill
uv run analyze_session.py --transcript /tmp/session.md \
--skill ~/.claude/skills/web-automation/SKILL.md
# Create new skill
uv run analyze_session.py --transcript /tmp/session.md --create-skill
# Save analysis to file
uv run analyze_session.py --transcript /tmp/session.md --output /tmp/analysis.md
Output includes:
- Automatically detected struggles (missing files, permission issues, import errors, etc.)
- Missing information (implicit knowledge, missing examples, edge cases, etc.)
- Success patterns (what worked well, effective approaches)
- Session metrics (tool invocations, errors, retries, successes)
- Assessment (overall session quality and recommendations)
Tips
- Use a fresh session for analysis to avoid context pollution
- Focus on patterns, not individual instances
- Keep skills concise - only add essential information
- Include examples for complex workflows
- Update trigger words if the skill wasn't invoked when expected
- Start with quick analysis to get overview, then full analysis for details
