Guide · Agent skill
How to use the Error Recovery Decision Tree agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Error Recovery Decision Tree is an agent skill from the Hive framework (skill name hive.error-recovery) that changes what an agent does when a tool call fails. Instead of retrying forever or abandoning work after one error, the agent first classifies the failure as temporary or structural and then follows a fixed set of rules. This guide explains what the skill does, how to install it, how to trigger it, and what it needs, so you can decide whether it fits your workflow.
Error Recovery Decision Treeaden-hive/hive · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page and unzip it so you have a folder containing SKILL.md.
- 2Place the skill folder. Move the folder into ~/.claude/skills/ for personal use or into the project's .claude/skills/ folder for a single project.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill.
- 4Prepare the task database. Confirm sqlite3 is installed, that your Hive colony task database has a tasks table, and that $DB_PATH points to it.
- 5Set the worker ID. Make sure a worker ID is available in the environment so the update query can match the correct task.
- 6Run an agent with tools. Start a workflow that uses tools and ask it to handle failures using error recovery, then check how failed items are recorded.
What is an agent skill, and what does this one make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when relevant. This skill is one of the default skills in the Hive framework, and its job is to govern what happens after a tool call fails.
When a tool call fails, the skill tells the agent to diagnose the failure first. A temporary failure, such as a network blip, rate limit or timeout, gets one retry. A structural failure, such as a wrong selector, missing login, bad input or denied permission, is either fixed and retried if it can be fixed, or recorded and skipped if it cannot. If a failure blocks all progress, the agent escalates. The skill also stops the agent from repeatedly calling a tool that keeps failing, and it prevents failed queue tasks from being silently dropped by writing the failure to the database.
- Transient failure: retry once.
- Structural and fixable: correct the input and retry.
- Structural and unfixable: record the failure and move to the next item.
- Blocking all progress: escalate.
- Same tool failing repeatedly: stop using it and find another approach.
How do you install the error-recovery skill?
Download the ZIP for the skill from this page and unzip it. The skill is delivered as a folder that contains SKILL.md. Place the folder in one of these locations: ~/.claude/skills/ to make it available across your projects, or the .claude/skills/ folder inside a specific project to limit it to that project.
If you use the Claude apps instead, you can upload the skill through Settings, then Capabilities, then Skills.
- Personal install: unzip into ~/.claude/skills/.
- Project install: unzip into the project's .claude/skills/ folder.
- Claude apps: Settings → Capabilities → Skills, then upload the skill.
How do you trigger the skill with natural requests?
The source material does not define a special trigger command, so the simplest approach is to describe the situation in plain language when you run your agent. The skill is meant for work that uses tools, especially long-running workflows and task queues, so ask for error handling in those terms.
Requests that match the skill's purpose include asking the agent to handle a failing tool without retrying endlessly, to keep going past a single bad item, or to record failed tasks in the queue rather than losing them. The skill's description notes that it is meant to replace both blind retries and giving up too early.
- "If a tool call fails, classify the error before retrying."
- "When a task fails, record it in the queue and move on to the next item."
- "If the same tool keeps failing, stop using it and try another approach."
What does a typical example look like?
Suppose an agent is processing a queue of tasks and one task calls a web tool that returns a rate-limit error. Under this skill, the agent treats the rate limit as transient and retries once. If the retry also fails, the agent makes a new decision based on the failure type rather than retrying again.
Now suppose a different task fails because a login is missing. That is structural and not fixable within the run, so the agent records the failure in the task database and moves to the next item. The source does not describe a specific output format, so check your agent's logs to see how each decision is reported.
- Rate limit or timeout: one retry, then reassess.
- Wrong selector with a corrected selector available: fix the input and retry.
- Missing login or denied permission with no fix available: record the failure and continue.
What does the skill need to run?
The database step depends on a few things being in place. You need the SQLite command-line tool (sqlite3), a Hive colony task database containing a tasks table, a $DB_PATH variable pointing to that database, and a worker ID available in the environment for the update query. For the full queue protocol, the skill refers to the hive.colony-progress-tracker skill.
The skill runs scripts. Its only shell example is an sqlite3 command that updates a task's status, last_error, completed_at and updated_at fields, filtered by task ID and worker ID. The source says the skill does not use the network.
- sqlite3 installed and available on the command line.
- A Hive colony task database with a tasks table, referenced by $DB_PATH.
- A worker ID in the environment for the update query.
- The hive.colony-progress-tracker skill for the full queue protocol.
sqlite3 "$DB_PATH" "UPDATE tasks SET status='failed', last_error='<one-sentence reason>', completed_at=datetime('now'), updated_at=datetime('now') WHERE id='<task-id>' AND worker_id='<your-worker-id>';"What are the safety notes for scripts and network access?
The skill runs a shell command that writes to a database, so it can change task records. The update only targets the task whose ID and worker ID match, but you should confirm that $DB_PATH points to the database you intend to change before running agents with this skill.
The skill does not use the network according to its source. Its effects are local: decisions made within the agent's run and writes to the task database.
- The skill writes to the task database through sqlite3, so verify $DB_PATH first.
- The source states the skill does not use the network.
- Escalation depends on your configuration. The skill says to escalate when a failure blocks all progress, so make sure your agent has a defined escalation path.
What tips help the skill work well?
Use this skill for agents that run tools inside long workflows, where predictable failure handling matters more than a quick answer. Make sure the task database is set up with the expected tasks table before you rely on the record-and-skip behaviour, because the update step will fail without it.
Pay attention to the repeat-failure threshold. The skill's protocol uses a max retries per tool setting, and when a tool has failed that many times in a row the agent should stop using it. Check how this value is configured in your setup, since the source uses a template placeholder and does not give a default.
- Set up the tasks table and $DB_PATH before enabling the skill.
- Pair it with hive.colony-progress-tracker if you use the full queue protocol.
- Review recorded failures periodically so skipped items do not go unnoticed.
- Configure escalation so that human review happens for blocking problems.
What people use it for
- Keeping a long-running Hive agent workflow moving when one tool call fails for a temporary reason.
- Recording failed items from a colony task queue in the database instead of losing them in memory.
- Stopping an agent from repeatedly calling a tool that keeps returning errors and trying another approach.
- Escalating when a single failure blocks all further progress in a workflow.
Frequently asked questions
Is the hive.error-recovery skill free to use?
The source for this skill is licensed under Apache-2.0, which is stated on this page. Check the license file in the repository for the full terms before using or redistributing it.
What do I need to install the error recovery skill?
You need the SKILL.md file, delivered as a ZIP from this page, placed in ~/.claude/skills/ or a project's .claude/skills/ folder. For the database step you also need sqlite3, a Hive colony task database with a tasks table, and a $DB_PATH variable.
Does this skill need an internet connection?
The source states that this skill does not use the network. It runs a local sqlite3 command for the queue update step.
Can I use this skill outside the Hive framework?
The source says the SQL update step assumes a Hive colony tasks table with specific columns and a $DB_PATH variable. Outside that environment, the agent would need to adapt or skip that step, while the classification and retry rules can still be followed.
How is this different from simple retry logic?
Simple retry logic usually retries the same call until it stops or gives up. This skill first classifies the failure as temporary or structural, retries only when a retry makes sense, records unfixable items, and stops using a tool that keeps failing.
What should I do if failed tasks are not showing up in the database?
First check that $DB_PATH points to the correct colony task database, that sqlite3 is installed, and that a worker ID is set in the environment. The update query matches on both task ID and worker ID, so a mismatch will prevent the update.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers running long, tool-heavy agent workflows in the Hive framework who want predictable handling of failures and no silently lost queue tasks. It is a poor fit for simple chats or tool-free tasks, and for environments without the Hive colony task database, where the database step would need to be adapted or removed.
Download the skill