| name | Handle Agent Failure |
| description | Notify the orchestrator when an agent fails or becomes inactive unexpectedly, so recovery actions can be taken. |
| version | 1.0.0 |
| category | monitoring |
| skillType | claude-skill |
| assignableRoles | ["orchestrator"] |
| triggers | ["agent failed","agent crashed","agent inactive","handle failure","recovery"] |
| tags | ["monitoring","failure","recovery","agent-lifecycle"] |
| execution | {"type":"script","script":{"file":"execute.sh","interpreter":"bash","timeoutMs":15000}} |
Handle Agent Failure
Sends a failure notification to the orchestrator when an agent becomes inactive unexpectedly (runtime exit, API failure, crash). The orchestrator can then decide to restart the agent, reassign the task, or inform the user.
Usage
bash config/skills/orchestrator/handle-agent-failure/execute.sh '{"agentSession":"agent-dev-1","reason":"runtime_exited","hadActiveTasks":true,"taskSummary":"Implementing login form","restartAttempted":true,"restartSucceeded":false}'
Parameters
| Parameter | Required | Description |
|---|
agentSession | Yes | The failed agent's PTY session name |
reason | Yes | Failure reason: runtime_exited, api_failure, connectivity_stuck, update_interrupted |
hadActiveTasks | No | Whether the agent had in-progress tasks (default: false) |
taskSummary | No | Brief description of what the agent was working on |
restartAttempted | No | Whether an automatic restart was attempted |
restartSucceeded | No | Whether the automatic restart succeeded |
Behavior
The script sends a structured failure notification to the orchestrator via the chat API. The orchestrator receives the message and can:
- Restart the agent if the failure was transient
- Reassign the task to another available agent
- Notify the user about the failure and ask for guidance
- Record the failure for future prevention
