error-recovery
Provides structured error handling protocol for all agent operations. Ensures users receive clear error reports, troubleshooting guidance, and actionable next steps. Use when any tool operation fails, encounters an error, or produces unexpected results.
When & Why to Use This Skill
The error-recovery skill implements a robust, structured protocol for Claude agents to handle operational failures and unexpected tool results. It enhances agent reliability by enforcing a 'stop-and-report' workflow, providing users with clear troubleshooting guidance and actionable next steps, which prevents autonomous errors and reduces unnecessary API costs.
Use Cases
- Scenario 1: Managing API failures or authentication errors by providing specific troubleshooting steps (e.g., checking environment variables) instead of proceeding with invalid data.
- Scenario 2: Handling file system errors or invalid URLs in media processing workflows, ensuring the user is notified of the exact cause (e.g., FFmpeg missing or invalid YouTube link).
- Scenario 3: Preventing cascading failures in complex multi-step agentic tasks by pausing execution when a tool output is unexpected and requesting human intervention for the next course of action.
| name | error-recovery |
|---|---|
| description | Provides structured error handling protocol for all agent operations. Ensures users receive clear error reports, troubleshooting guidance, and actionable next steps. Use when any tool operation fails, encounters an error, or produces unexpected results. |
Error Recovery
On Failure Protocol
- STOP IMMEDIATELY — Do not continue with other actions
- REPORT CLEARLY — Explain what went wrong concisely
- OFFER NEXT STEPS — Provide specific troubleshooting or retry options
- WAIT FOR RESPONSE — Do NOT proceed autonomously
Error Response Template
[Operation] Failed
[Brief explanation of what went wrong]
This can happen when:
- [Possible cause 1]
- [Possible cause 2]
**Would you like to:**
1. [Retry option]
2. [Alternative option]
3. Cancel and return to main menu
Please let me know how you'd like to proceed.
Common Error Patterns
| Category | Error | Troubleshooting |
|---|---|---|
| Transcription | YouTube URL invalid | Check URL format and video availability |
| Transcription | File not found | Verify file path exists |
| Transcription | FFmpeg missing | Install FFmpeg (apt install ffmpeg) |
| Transcription | API key missing | Set OPENAI_API_KEY environment variable |
| Transcription | Timeout | Video too long; suggest splitting |
| KG | Bootstrap failed | Transcript may be too short or lack entities |
| KG | Extraction failed | Project may not be bootstrapped yet |
| KG | Project not found | Check project ID validity |
NEVER Do
- Try to work around failures without user consent
- Make assumptions about what went wrong
- Proceed with alternative approaches autonomously
- Leave the user stuck without a path forward
This saves time and money by avoiding unnecessary API calls when something has already failed.