Skip to content
Get packs

Guide · Agent skill

How to use the Queen Colony Debug agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The queen-colony-debug skill is a step-by-step debugging procedure for the Hive agent system. It is written for engineers working on the Hive codebase who need to reproduce bugs in the colony pipeline: creating a colony from a queen chat, sharing a tracker database with workers, and spawning parallel workers. After following this guide you will know how to install the skill, how to ask an agent to use it, and what the agent does on your machine while it runs.

Queen Colony Debugaden-hive/hive · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the queen-colony-debug ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
  2. 2Open a Hive repository checkout. Work from inside a Hive repository that has uv and the hive CLI available, since the skill starts the server with uv run hive serve.
  3. 3Make a request in plain language. Describe the colony or tracker bug you want reproduced, or the refactor you want verified, and name the symptom you see.
  4. 4Let the agent start an isolated server. The agent creates /tmp/hive_e2e and starts the server on a non-default port such as 8901, keeping your real Hive Desktop data untouched.
  5. 5Drive the flow and check invariants. The agent creates a session, forks it into a colony and inspects worker.json, then checks the expected results against the logs.
  6. 6Review results and stop the server. Read the findings the agent reports, confirm which expected results passed or failed, and stop the background test server when finished.

What the skill makes the agent do

An agent skill is a folder containing a SKILL.md file of instructions that an AI agent loads when your request matches the skill's purpose. This one gives the agent a standard operating procedure for debugging the create_colony, tracker, run_parallel_workers and worker pipeline in Hive.

Instead of guessing, the agent starts a separate test copy of the Hive server with an isolated data folder, sends scripted requests to it, and checks specific expected results such as folder layout and configuration keys. Your real Hive Desktop installation is left alone.

  • Starts a test Hive server on a non-default port such as 8901 with its own HIVE_HOME under /tmp.
  • Drives queen sessions, forks a session into a colony and inspects the resulting worker.json.
  • Checks invariants, such as that a DM queen session does not create a colonies/<session_uuid>/ folder and that the tracker database is shared inside the colony.

Install the queen-colony-debug skill

Download the ZIP for this skill from this page and unzip it. You can install it in one of two places. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

  • Personal: ~/.claude/skills/queen-colony-debug/
  • Project: .claude/skills/queen-colony-debug/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Prepare the Hive repository

The skill expects a Hive repository checkout with uv and the hive CLI available. It starts the server with uv run hive serve, so run the agent from inside the checkout. The skill's own setup creates the isolated folders it needs under /tmp/hive_e2e.

  • Hive repository checkout with uv and the hive CLI available
  • A local server on a non-default port such as 8901
  • An LLM provider configured only if you want the optional LLM-driven steps, which cost credits
mkdir -p /tmp/hive_e2e/colonies /tmp/hive_e2e/agents/queens PORT=8901 HIVE_HOME=/tmp/hive_e2e uv run hive serve --port $PORT --verbose 2>&1 > /tmp/hive_e2e/server.log &

How to trigger the skill with a natural request

You do not need special syntax. Describe the bug or the verification you want in plain language and mention the Hive part involved. The skill is designed to trigger on requests about queen sessions, colonies, tracker tables and parallel workers.

Be specific about the symptom. Requests that name a visible failure or a behaviour you want checked tend to match the procedure most directly.

  • "Queen says no such table, can you reproduce it?"
  • "Workers can't see what the queen wrote, debug the tracker binding."
  • "A phantom colony folder appeared after I opened a DM. Investigate."
  • "Verify my colony refactor didn't break anything."

Safety notes: scripts and network

This skill runs scripts and uses the network. It starts a local server, makes HTTP calls to 127.0.0.1, and can drive LLM-backed queen turns, which cost credits. The procedure says not to run against the real Hive Desktop runtime by default and not to read the real secrets, credentials or configuration.json folders. Switching to the real runtime is only for when you explicitly ask for live LLM verification.

Review the commands before you approve them, and stop the test server when you finish.

  • Defaults to an isolated HIVE_HOME=/tmp/hive_e2e rather than your real Hive Desktop data.
  • Uses a non-default port to avoid colliding with Hive Desktop on 8787.
  • Runs the server in the background and logs to a file you can inspect.
  • Expect LLM-driven steps to cost credits.

Tips for getting useful results

Keep queen prompts terse and deterministic. The procedure favours instructions like calling create_colony with exact arguments over open-ended questions, because each LLM turn costs money. Prefer the non-LLM fork path when it is enough to show the bug.

Use the log file as the source of truth. A missing log line such as the run_parallel_workers binding message is itself evidence that the binding plumbing is broken.

  • Start with the isolated runtime and only move to the real one when it is necessary.
  • Check the startup log for the expected green-light line before trusting results.
  • Look at worker.json input_data to confirm the binding shape.

What people use it for

  • Reproducing a bug where a queen cannot see a tracker table inside a colony.
  • Checking that a DM queen session does not create a phantom colony folder.
  • Verifying that worker.json input_data carries only the binding key after a refactor.
  • Confirming that run_parallel_workers attaches the binding to its spawns.

Frequently asked questions

How do I install the queen-colony-debug skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into a project's .claude/skills/ folder. In the Claude apps you can instead open Settings, go to Capabilities, then Skills, and upload it there.

Is the queen-colony-debug skill free?

The skill is licensed under Apache-2.0. Running it is not free in one respect: the optional LLM-driven steps cost credits from your configured LLM provider. The non-LLM steps do not need that.

What does the queen-colony-debug skill require?

It requires a Hive repository checkout with uv and the hive CLI available, a local server running on a non-default port such as 8901, and an LLM provider only for the optional LLM-driven steps.

Can I use this skill to debug projects other than Hive?

No. The checks and file paths are specific to the Hive repository, so it is not suited to debugging unrelated projects. End users who only want to use Hive Desktop should not need it either.

Will this skill change my real Hive Desktop data?

By default it does not. The procedure uses an isolated HIVE_HOME under /tmp/hive_e2e and a separate port, and it says not to touch the real runtime unless live LLM verification is explicitly requested.

Why does the skill run scripts and use the network?

It starts a local Hive server in the background and makes HTTP calls to it. It can also send prompts to an LLM-backed queen, which uses the network and costs credits.

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

Use this skill if you work on the Hive codebase and need a repeatable way to reproduce or verify colony, tracker and worker-binding behaviour without touching your real installation. Pick something else if you only want to use Hive Desktop, or if you need to debug a project that is not the Hive repository.

Download the skill