errors — Claude Code skill: what it does, how to install
The errors skill sorts Claude Code session failures by type, looks for earlier matches, and suggests recovery steps. It activates after a command, network, or tool error.
MIT 223 installs ★ 305 updated 2026-11-07
npx skills add yonatangross/orchestkit --skill errors -a claude-codeWhat errors does
The skill reviews errors recorded from Claude Code sessions and sorts them into network, authentication, model, tool, and permission issues. It compares new failures with earlier occurrences, surfaces repeated patterns, and gives recovery guidance. Raw entries are kept in .claude/logs/errors.jsonl.
Its files include .claude/hooks/posttool/error-collector.sh for collection, a pre-command warning hook, and .claude/scripts/analyze_errors.py for batch analysis. The script can inspect the last day or 7 days and write a Markdown report. Learned patterns go to .claude/rules/error_rules.json, which can also be queried with jq.
Claude Code 2.1.277+ and the memory MCP server are required. Without that MCP server, the skill cannot perform its main analysis.
What it helps with
- classify failures from a Claude Code session
- find repeated errors across the last 7 days
- separate network failures from authentication issues
- inspect rules for commands that fail repeatedly
- create a Markdown report from the error log
Example prompts for the agent
- Analyze Claude Code errors from the last 7 days and group recurring patterns.
- Run
python .claude/scripts/analyze_errors.py --reportand create a Markdown report. - Read
.claude/rules/error_rules.jsonand explain which recorded failures have recovery steps.
How to install errors
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill errors -a claude-code2Manually: put the files in place
~/.claude/skills/errors/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/errors/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill errors -a codex2Manually: put the files in place
.agents/skills/errors/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill errors -a cursor2Manually: put the files in place
.cursor/skills/errors/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/errors2Manually: put the files in place
.github/skills/errors/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill errors -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/errorsManually: put the files in place
.devin/skills/errors/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill errors -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 errors
How do I install errors in Claude Code?
Run npx skills add yonatangross/orchestkit --skill errors -a claude-code, then use the file ~/.claude/skills/errors/SKILL.md.
What does the errors skill do?
It reviews Claude Code session failures, classifies them, finds repeated occurrences, and suggests recovery actions. Its analysis uses .claude/logs/errors.jsonl and .claude/rules/error_rules.json.
What does errors need to work?
It requires Claude Code 2.1.277+ and the memory MCP server. The skill also uses Read, Bash, and Grep.
Source text
SKILL.md · MIT
---
name: errors
license: MIT
compatibility: "Claude Code 2.1.277+. Requires memory MCP server."
description: "Claude Code session error triage: categorizes network, auth, model, tool and permission errors, finds prior occurrences, suggests recovery. Use when a session hits errors or failures."
context: inherit
user-invocable: false
allowed-tools: "Read Bash Grep"
effort: low
model: haiku
metadata:
category: document-asset-creation
mcp-server: memory
version: "1.0.0"
author: "OrchestKit"
complexity: "low"
tags: "errors, debugging, troubleshooting, patterns"
---
# Error Pattern Analysis
Analyze errors captured from Claude Code sessions to identify patterns and get actionable insights.
## Quick Start
```bash
/errors # Batch analysis of historical error patterns
/debug # CC 2.1.30 real-time debug for current session
```
### When to Use Which
| Command | Purpose | Scope |
|---------|---------|-------|
| `/errors` | Batch analysis of error patterns (last 24h/7d) | Historical patterns |
| `/debug` | Real-time debug of current session state | Current session |
| `fix-issue` | Full RCA workflow for specific bug | Single issue |
> **CC 2.1.169+:** for errors that survive `/clear` and restarts, `claude --safe-mode` boots with every customization disabled (CLAUDE.md/plugins/skills/hooks/MCP) — the one-step test that separates "ork/hook/MCP bug" from "CC bug" before deeper analysis.
## Quick Analysis
```bash
# Run batch analysis on last 24h of errors
python .claude/scripts/analyze_errors.py
# Analyze last 7 days
python .claude/scripts/analyze_errors.py --days 7
# Generate markdown report
python .claude/scripts/analyze_errors.py --report
```
## What Gets Captured
The error collector hook captures:
- Tool name (Bash, mcp__memory__search_nodes, etc.)
- Error message (first 500 chars)
- Tool input (command/query that failed)
- Timestamp and session ID
**Location:** `.claude/logs/errors.jsonl`
## Current Error Rules
Check learned patterns that trigger warnings:
```bash
cat .claude/rules/error_rules.json | jq '.rules[] | {id, signature, count: .occurrence_count}'
```
## Files
| File | Purpose |
|------|---------|
| `.claude/hooks/posttool/error-collector.sh` | Captures errors to JSONL |
| `.claude/hooks/pretool/bash/error-pattern-warner.sh` | Warns before risky commands |
| `.claude/scripts/analyze_errors.py` | Batch pattern analysis |
| `.claude/rules/error_rules.json` | Learned error patterns |
| `.claude/logs/errors.jsonl` | Raw error log |
## Common Patterns
### Connection Refused / Wrong Port
```
pattern: ECONNREFUSED|connection refused|ERR_CONNECTION_REFUSED|connect ECONNREFUSED
fix: The port may have changed or the service isn't running.
1. Check services: portless list (if installed)
2. Use named URLs: api.localhost instead of localhost:PORT
3. Fallback: lsof -iTCP -sTCP:LISTEN -nP | grep -E 'node|python|java'
4. Install Portless to avoid port guessing: npm i -g portless
pattern: ERR_CONNECTION_RESET|ECONNRESET|socket hang up
fix: Service may have crashed. Check process logs, restart the service,
and use agent-browser to verify the app is responding:
agent-browser open "https://myapp.localhost"
```
### PostgreSQL Connection Errors
```
pattern: role "X" does not exist
fix: Use Docker connection: docker exec -it orchestkit-postgres-dev psql -U orchestkit_user -d orchestkit_dev
pattern: relation "X" does not exist
fix: Check MCP postgres server connection string - may be connected to wrong database
```
### Hook Errors (CC 2.1.98)
Since CC 2.1.98, hook errors show the first line of stderr directly in the transcript — no need for `--debug`:
```
pattern: hook.*error|hook.*failed|PreToolUse.*error
diagnosis: Read the stderr line shown in the transcript.
1. If path error → check CLAUDE_PLUGIN_ROOT is set
2. If JSON parse error → hook is returning invalid JSON
3. If timeout → hook exceeds 50ms budget (PreToolUse) or 100ms (PostToolUse)
4. If "module not found" → run: cd src/hooks && npm run build
```
## Related Skills
- `ork:fix-issue`: Fix identified errors
- `debug-investigator`: Debug error root causes
## Adding New Rules
Rules are auto-generated by `analyze_errors.py` when patterns repeat 2+ times.
For manual rules, edit `.claude/rules/error_rules.json`:
```json
{
"id": "custom-001",
"pattern": "your regex pattern",
"signature": "human readable signature",
"tool": "Bash",
"occurrence_count": 1,
"fix_suggestion": "How to fix this"
}
```
© OrchestKit · MIT · yonatangross/orchestkit