summarize · terrylica — Claude Code skill: analyze large logs and session recordings
summarize is a Claude Code skill that analyzes multi-gigabyte text files and session recordings step by step. It helps trace what happened when a file is too large to read normally.
MIT 103 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill summarize -a claude-codeWhat summarize does
summarize works in phases. It first asks what you're looking for — an overview, errors, or a specific topic. Then it reads the start, end, and middle of the file and gathers statistics on keywords. Based on that, it offers ways to drill deeper: find a specific timeframe, trace a problem chain, or extract moments where things went well.
The skill uses Bash, Grep, Read, and AskUserQuestion for dialogue. For files under 100 MB, it samples the beginning, middle, and end. For larger files, it searches by keywords from built-in libraries (trading, ML, development, Claude Code). Each round refines the search, and you can save the findings to markdown at the end.
Arguments: path to a .txt file, optionally --topic for focus, --depth (quick, medium, deep) for analysis depth, and --output to save results. The skill improves through use — if instructions drift or a workaround is needed, you fix the file immediately.
What it helps with
- make sense of 12 GB of session logs in minutes
- find the moment something broke in a large file and trace how it was fixed
- extract key findings and decisions from a long recording
- build an analysis system that refines its own questions as it goes
Example prompts for the agent
- Analyze session.txt and tell me what happened and what went wrong
- Review research.cast focused on model training results
- Extract errors from logfile.txt with deep analysis and save findings to report.md
How to install summarize
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill summarize -a claude-code2Manually: put the files in place
~/.claude/skills/summarize/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/summarize/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill summarize -a codex2Manually: put the files in place
.agents/skills/summarize/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill summarize -a cursor2Manually: put the files in place
.cursor/skills/summarize/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/asciinema-tools/skills/summarize2Manually: put the files in place
.github/skills/summarize/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill summarize -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/asciinema-tools/skills/summarizeManually: put the files in place
.devin/skills/summarize/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill summarize -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about summarize
How do I install summarize in Claude Code?
Run npx skills add terrylica/cc-skills --skill summarize -a claude-code, then open ~/.claude/skills/summarize/SKILL.md.
What does summarize do?
It analyzes large text logs and session recordings step by step. Asks what you're interested in, samples the file, searches by keywords, and lets you drill into findings. Results can be saved to markdown.
What if the file is over 1 GB?
The skill does not load the entire file. For files over 100 MB, it samples by keywords; for smaller ones, it reads the start, middle, and end. Analysis stays interactive — you choose what to explore next.
Source text
SKILL.md · MIT
---
name: summarize
description: AI-powered iterative deep-dive analysis of converted recordings. TRIGGERS - summarize recording, analyze session, what happened
allowed-tools: Bash, Grep, Read, AskUserQuestion, Task, Write
argument-hint: "[file] [--topic topic] [--depth quick|medium|deep] [--output file]"
---
# /asciinema-tools:summarize
AI-powered iterative deep-dive analysis for large .txt recordings. Uses guided sampling and AskUserQuestion to progressively explore the content.
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## Philosophy
Large recordings (1GB+) cannot be read entirely. This command uses:
1. **Initial guidance** - What are you looking for?
2. **Strategic sampling** - Head, middle, tail + keyword-targeted sections
3. **Iterative refinement** - AskUserQuestion to drill deeper into findings
4. **Progressive synthesis** - Build understanding through multiple passes
## Arguments
| Argument | Description |
| ---------- | -------------------------------------------------- |
| `file` | Path to .txt file (converted from .cast) |
| `--topic` | Initial focus area (e.g., "ML training", "errors") |
| `--depth` | Analysis depth: `quick`, `medium`, `deep` |
| `--output` | Save findings to markdown file |
## Workflow
### Phase 1: Initial Guidance
```yaml
AskUserQuestion:
question: "What are you trying to understand from this recording?"
header: "Focus"
options:
- label: "General overview"
description: "What happened in this session? Key activities and outcomes"
- label: "Key findings/decisions"
description: "Important discoveries, conclusions, or decisions made"
- label: "Errors and debugging"
description: "What went wrong? How was it resolved?"
- label: "Specific topic"
description: "I'll specify what I'm looking for"
```
### Phase 2: File Statistics
```bash
/usr/bin/env bash << 'STATS_EOF'
FILE="$1"
echo "=== File Statistics ==="
SIZE=$(ls -lh "$FILE" | awk '{print $5}')
LINES=$(wc -l < "$FILE")
echo "Size: $SIZE"
echo "Lines: $LINES"
echo ""
echo "=== Content Sampling ==="
echo "First 20 lines:"
head -20 "$FILE"
echo ""
echo "Last 20 lines:"
tail -20 "$FILE"
echo ""
echo "=== Keyword Density ==="
echo "Errors/failures:"
grep -c -i "error\|fail\|exception" "$FILE" || echo "0"
echo "Success indicators:"
grep -c -i "success\|complete\|done\|pass" "$FILE" || echo "0"
echo "Key decisions:"
grep -c -i "decision\|chose\|selected\|using" "$FILE" || echo "0"
STATS_EOF
```
### Phase 3: Strategic Sampling
Based on file size, sample strategically:
**For files < 100MB:**
```bash
# Sample head, middle, tail (1000 lines each)
head -1000 "$FILE" > /tmp/sample_head.txt
tail -1000 "$FILE" > /tmp/sample_tail.txt
TOTAL=$(wc -l < "$FILE")
MIDDLE=$((TOTAL / 2))
sed -n "${MIDDLE},$((MIDDLE + 1000))p" "$FILE" > /tmp/sample_middle.txt
```
**For files > 100MB:**
```bash
# Keyword-targeted sampling
grep -B5 -A20 -i "$TOPIC_KEYWORDS" "$FILE" | head -5000 > /tmp/sample_targeted.txt
```
### Phase 4: Initial Analysis
Read the samples and provide initial findings. Then ask:
```yaml
AskUserQuestion:
question: "Based on initial analysis, what would you like to explore deeper?"
header: "Drill down"
multiSelect: true
options:
- label: "Specific timeframe"
description: "Jump to a particular section (e.g., 'around line 50000')"
- label: "Follow keyword trail"
description: "Search for specific patterns and expand context"
- label: "Error investigation"
description: "Deep dive into errors and their resolution"
- label: "Success moments"
description: "What worked? What were the wins?"
- label: "Generate summary"
description: "Synthesize findings into a report"
```
### Phase 5: Iterative Deep-Dive
For each selected focus area:
1. **Extract relevant sections** using grep with context
2. **Read and analyze** the extracted content
3. **Report findings** to user
4. **Ask for next action** via AskUserQuestion
```yaml
AskUserQuestion:
question: "Found {N} relevant sections. What next?"
header: "Continue"
options:
- label: "Show me the most significant"
description: "Display top 3 most relevant excerpts"
- label: "Search for related patterns"
description: "Expand search to related keywords"
- label: "Move on"
description: "I have enough on this topic"
```
### Phase 6: Synthesis
```yaml
AskUserQuestion:
question: "Ready to generate summary. What format?"
header: "Output"
options:
- label: "Concise bullet points"
description: "Key findings in 10-15 bullets"
- label: "Detailed markdown report"
description: "Full report with sections and evidence"
- label: "Executive summary"
description: "1-paragraph high-level summary"
- label: "Save to file"
description: "Write findings to markdown file"
```
## Keyword Libraries
### Trading/ML Domain
```
sharpe|drawdown|backtest|overfitting|regime|validation
model|training|loss|epoch|gradient|convergence
feature|indicator|signal|position|portfolio
```
### Development Domain
```
error|exception|fail|bug|fix|debug
commit|push|merge|branch|deploy
test|assert|verify|validate|check
```
### Claude Code Domain
```
tool|bash|read|write|edit|grep
task|agent|subagent|spawn
permission|approve|reject|block
```
## Example Usage
```bash
# Interactive exploration
/asciinema-tools:summarize session.txt
# Focused on ML findings
/asciinema-tools:summarize session.txt --topic "ML training results"
# Quick overview
/asciinema-tools:summarize session.txt --depth quick
# Full analysis with report
/asciinema-tools:summarize session.txt --depth deep --output findings.md
```
## Example Output
```markdown
# Session Summary: research-repo-research_20251226
## Overview
- **Duration**: 4 days (Dec 26-30, 2025)
- **Size**: 12GB recording → 3.2GB text
- **Primary Focus**: ML robustness research
## Key Findings
### 1. Training-Evaluation Mismatch (CRITICAL)
- MSE loss optimizes magnitude, but Sharpe evaluates direction
- Result: 80% Sharpe collapse from 2024 to 2025
### 2. Fishr λ=0.1 Solution (BREAKTHROUGH)
- Gradient variance penalty solves V-REx binary threshold
- Feb'24 Sharpe: -6.14 → +6.14
### 3. Model Rankings
| Model | Window | Sharpe |
| ------ | ------ | ------ |
| TFT | 15mo | 1.02 |
| BiLSTM | 12mo | 0.50 |
## Evidence Locations
- Line 15234: "Fishr λ=0.1 SOLVES the V-REx binary threshold problem"
- Line 48102: Phase 4 results summary table
## Next Steps Identified
1. TFT 15mo + Fishr training
2. PSR/PBO statistical validation
3. Agent research synthesis
```
## Troubleshooting
| Issue | Cause | Solution |
| --------------------- | ------------------------------ | ------------------------------------- |
| File too large | Recording exceeds memory limit | Use `--depth quick` for sampling only |
| No keywords found | Wrong domain or sparse content | Try different `--topic` focus area |
| Sampling timeout | Very large file | Increase terminal timeout or use grep |
| grep context error | Missing GNU grep | `brew install grep` (BSD grep limits) |
| Output file not saved | Permission denied | Check write permissions on `--output` |
## Related Commands
- `/asciinema-tools:convert` - Convert .cast to .txt first
- `/asciinema-tools:analyze` - Keyword-based analysis (faster, less deep)
- `/asciinema-tools:finalize` - Process orphaned recordings
## Post-Execution Reflection
After this skill completes, reflect before closing the task:
0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — Fix the instruction that caused it.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality.
4. **Log it.** — Evolution-log entry with trigger, fix, and evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.
© terrylica · MIT · terrylica/cc-skills
Similar skills
All skills for AI and ML →summarize by other authors comes first.