skill-session-analyzer
/skill-session-analyzer
This skill should be used when the user asks to "analyze session", "evaluate skill execution", "check session logs", provides a session ID with a skill path, or wants to verify that a skill executed correctly in a past session. Post-hoc analysis of Claude Code sessions to validate skill/agent/hook behavior against SKILL.md specifications.
- Author
- team-attention ↗
- Repository
- hoyeon ↗
- Licence
- MIT
- Last repository change
- 21.05.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 3
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 3 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/extract-hook-events.sh, scripts/extract-subagent-calls.sh, scripts/find-session-files.sh
What it does and when to use it
This skill should be used when the user asks to "analyze session", "evaluate skill execution", "check session logs", provides a session ID with a skill path, or wants to verify that a skill executed correctly in a past session. Post-hoc analysis of Claude Code sessions to validate skill/agent/hook behavior against SKILL.md specifications.
Triggers from the description
Original author description
This skill should be used when the user asks to "analyze session", "evaluate skill execution", "check session logs", provides a session ID with a skill path, or wants to verify that a skill executed correctly in a past session. Post-hoc analysis of Claude Code sessions to validate skill/agent/hook behavior against SKILL.md specifications.
How it works
- Purpose
- Input Requirements
- Phase 1: Locate Session Files
- Phase 2: Parse Target SKILL.md
- Phase 3: Analyze Debug Log
- Phase 4: Verify Artifacts
- Phase 5: Compare Expected vs Actual
- Phase 6: Generate Report
- Scripts Reference
- Usage Example
SKILL.md preview
---
name: skill-session-analyzer
description: |
This skill should be used when the user asks to "analyze session", "evaluate skill execution",
"check session logs", provides a session ID with a skill path,
or wants to verify that a skill executed correctly in a past session.
Post-hoc analysis of Claude Code sessions to validate skill/agent/hook behavior against SKILL.md specifications.
allowed-tools:
- Read
- Grep
- Glob
- Bash
- Task
- Write
---
# Session Analyzer Skill
Post-hoc analysis tool for validating Claude Code session behavior against SKILL.md specifications.
## Purpose
Analyze completed sessions to verify:
1. **Expected vs Actual Behavior** - Did the skill follow SKILL.md workflow?
2. **Component Invocations** - Were SubAgents, Hooks, and Tools called correctly?
3. **Artifacts** - Were expected files created/deleted?
4. **Bug Detection** - Any unexpected errors or deviations?
---
## Input Requirements
| Parameter | Required | Description |
|-----------|----------|-------------|
| `sessionId` | YES | UUID of the session to analyze |
| `targetSkill` | YES | Path to SKILL.md to validate against |
| `additionalRequirements` | NO | Extra validation criteria |
---
## Phase 1: Locate Session Files
### Step 1.1: Find Session Files
Session files are located in `~/.claude/`:
```bash
# Main session log
~/.claude/projects/-{encoded-cwd}/{sessionId}.jsonl
# Debug log (detailed)
~/.claude/debug/{sessionId}.txt
# Agent transcripts (if subagents were used)
~/.claude/projects/-{encoded-cwd}/agent-{agentId}.jsonl
```
Use script to locate files:
```bash
${baseDir}/scripts/find-session-files.sh {sessionId}
```
### Step 1.2: Verify Files Exist
Check all required files exist before proceeding. If debug log is missing, analysis will be limited.
---
## Phase 2: Parse Target SKILL.md
### Step 2.1: Extract Expected Components
Read the target SKILL.md and identify:
**From YAML Frontmatter:**
- `hooks.PreToolUse` - Expected PreToolUse hooks and matchers
- `hooks.PostToolUse` - Expected PostToolUse hooks
- `hooks.Stop` - Expected Stop hooks
- `hooks.SubagentStop` - Expected SubagentStop hooks
- `allowed-tools` - Tools the skill is allowed to use
**From Markdown Body:**
- SubAgents mentioned (`Task(subagent_type="...")`)
- Skills called (`Skill("...")`)
- Artifacts created (`.hoyeon/drafts/`, `.hoyeon/specs/`, etc.)
- Workflow steps and conditions
### Step 2.2: Build Expected Behavior Checklist
Create checklist from SKILL.md analysis:
```markdown
## Expected Behavior
### SubAgents
- [ ] Explore agent called (parallel, run_in_background)
- [ ] gap-analyzer called before plan generation
- [ ] plan-reviewer called after plan creation
### Hooks
- [ ] PreToolUse[Edit|Write] triggers plan-guard.sh
- [ ] Stop hook validates plan-reviewer approval
### Artifacts
- [ ] Draft file created at .hoyeon/drafts/{name}.md
- [ ] Plan file created at .hoyeon/specs/{name}.md
- [ ] Draft file deleted after OKAY
### Workflow
- [ ] Interview Mode before Plan Generation
- [ ] User explicit request triggers plan generation
- [ ] Reviewer REJECT causes revision loop
```
---
## Phase 3: Analyze Debug Log
The debug log (`~/.claude/debug/{sessionId}.txt`) contains detailed execution traces.
### Step 3.1: Extract SubAgent Calls
Search patterns:
```
SubagentStart with query: {agent-name}
SubagentStop with query: {agent-id}
```
Use script:
```bash
${baseDir}/scripts/extract-subagent-calls.sh {debug-log-path}
```
### Step 3.2: Extract Hook Events
Search patterns:
```
Getting matching hook commands for {HookEvent} with query: {tool-name}
Matched {N} unique hooks for query "{query}"
Hooks: Processing prompt hook with prompt: {prompt}
Hooks: Prompt hook condition was met/not met
permissionDecision: allow/deny
```
Use script:
```bash
${baseDir}/scripts/extract-hook-events.sh {debug-log-path}
```
### Step 3.3: Extract Tool Calls
Search patterns:
```
executePreToolHooks called for tool: {tool-name}
File {path} written atomically
```
### Step 3.4: Extract Hook Results
For prompt-based hooks, find the model response:
```
Hooks: Model response: {
"ok": true/false,
"reason": "..."
}
```
---
## Phase 4: Verify Artifacts
### Step 4.1: Check File Creation
For each expected artifact:
1. Search debug log for `FileHistory: Tracked file modification for {path}`
2. Search for `File {path} written atomically`
3. Verify current filesystem state
### Step 4.2: Check File Deletion
For files that should be deleted:
1. Search for `rm` commands in Bash calls
2. Verify file no longer exists on filesystem
---
## Phase 5: Compare Expected vs Actual
### Step 5.1: Build Comparison Table
```markdown
| Component | Expected | Actual | Status |
|-----------|----------|--------|--------|
| Explore agent | 2 parallel calls | 2 calls at 09:39:26 | ✅ |
| gap-analyzer | Called before plan | Called at 09:43:08 | ✅ |
| plan-reviewer | Called after plan | 2 calls (REJECT→OKAY) | ✅ |
| PreToolUse hook | Edit\|Write matcher | Triggered for Write | ✅ |
| Stop hook | Validates approval | Returned ok:true | ✅ |
| Draft file | Created then deleted | Created→Deleted | ✅ |
| Plan file | Created | Exists (10KB) | ✅ |
```
### Step 5.2: Identify Deviations
Flag any mismatches:
- Missing component calls
- Wrong order of operations
- Hook failures
- Missing artifacts
- Unexpected errors
---
## Phase 6: Generate Report
### Report Template
```markdown
# Session Analysis Report
## Session Info
- **Session ID**: {sessionId}
- **Target Skill**: {skillPath}
- **Analysis Date**: {date}
---
## 1. Expected Behavior (from SKILL.md)
[Summary of expected workflow]
---
## 2. Skill/SubAgent/Hook Verification
### SubAgents
| SubAgent | Expected | Actual | Time | Result |
|----------|----------|--------|------|--------|
| ... | ... | ... | ... | ✅/❌ |
### Hooks
| Hook | Matcher | Triggered | Result |
|------|---------|-----------|--------|
| ... | ... | ... | ✅/❌ |
---
## 3. Artifacts Verification
| Artifact | Path | Expected State | Actual State |
|----------|------|----------------|--------------|
| ... | ... | ... | ✅/❌ |
---
## 4. Issues/Bugs
| Severity | Description | Location |
|----------|-------------|----------|
| ... | ... | ... |
---
## 5. Overall Result
**Verdict**: ✅ PASS / ❌ FAIL
**Summary**: [1-2 sentence summary]
```
---
## Scripts Reference
| Script | Purpose |
|--------|---------|
| `find-session-files.sh` | Locate all files for a session ID |
| `extract-subagent-calls.sh` | Parse subagent invocations from debug log |
| `extract-hook-events.sh` | Parse hook events from debug log |
---
## Usage Example
```
User: "Analyze session 3cc71c9f-d27a-4233-9dbc-c4f07ea6ec5b against .claude/skills/spec/SKILL.md"
1. Find session files
2. Parse SKILL.md → Expected: Explore, gap-analyzer, plan-reviewer, hooks
3. Analyze debug log → Extract actual calls
4. Verify artifacts → Check .hoyeon/
5. Compare → Build verification table
6. Generate report → PASS/FAIL with details
```
---
## Additional Resources
### Reference Files
- **`references/analysis-patterns.md`** - Detailed grep patterns for log analysis
- **`references/common-issues.md`** - Known issues and troubleshooting
### Scripts
- **`scripts/find-session-files.sh`** - Session file locator
- **`scripts/extract-subagent-calls.sh`** - SubAgent call extractor
- **`scripts/extract-hook-events.sh`** - Hook event extractor
Files in this package (6)
- SKILL.md 7 KB
- references/analysis-patterns.md 5 KB
- references/common-issues.md 6 KB
- scripts/extract-hook-events.sh 4 KB
- scripts/extract-subagent-calls.sh 2 KB
- scripts/find-session-files.sh 1 KB
Versions
The database has no other skills named skill-session-analyzer.
Database snapshot: 13.11.2026 · package version 090778338ae5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100skill-session-review
Analyze how an existing agent skill was used in past Claude Code, Grok, Codex, and Oh My Pi conversations. Use when the user asks to 分析某 skill 的使用情况, 这个 skill 用着有什么问题, 根据历史对话反馈改进 this skill, review skill sessions, or write a session-review report. Writes… - 100sessiondex
This skill should be used when finding, listing, or reading past AI agent sessions across Codex, Claude Code, OpenCode, and Pi from one local full-text index. Triggers on "recent sessions", "recent Codex sessions", "what did I work on", "find the session where", "which agent did… - 100session-learning
This skill should be used when the user asks about "session learning", "learn from session", "improve future sessions", "session reflection", "session metrics", "session analysis", "/session-reflect", "req learning", "learning updates", "rollback learning", or wants to… - 100session-analyzer
Scan past Claude Code session transcripts for unfinished work, repeated workflow corrections, and candidate memories not yet captured. Use when the user says "analyze my sessions", "what am I missing", "what did I leave hanging", "/session-analyzer", or when starting a new day… - 100replay
Find, analyze, and share AI coding sessions with vibe-replay. Use when the user asks for a replay, wants to find a past session, run a session retro, share Cursor/Claude/Codex session context, or attach session context to a PR. - 100claude-code-hook-development
This skill should be used when the user asks to "create a hook", "add a hook", "write a hook", or mentions Claude Code hooks. Also suggest this skill when the user asks to "automatically do X" or "run X before/after Y" as these are good candidates for hooks.