Skip to content
Skills Library
AI & agents · Review & audit

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.

Repository
hoyeon ↗
Licence
MIT
Last repository change
21.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
3
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.05.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

analyze sessionevaluate skill executioncheck session logs
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

  1. Purpose
  2. Input Requirements
  3. Phase 1: Locate Session Files
  4. Phase 2: Parse Target SKILL.md
  5. Phase 3: Analyze Debug Log
  6. Phase 4: Verify Artifacts
  7. Phase 5: Compare Expected vs Actual
  8. Phase 6: Generate Report
  9. Scripts Reference
  10. Usage Example
Original SKILL.md headings · 293 lines, 995 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.