How to use the Colony Progress Tracker agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a situation calls for them. This skill is named hive.colony-progress-tracker and is listed as a default skill for worker agents only.

When a worker agent starts with a spawn message that includes a db_path field, the skill tells it how to use a SQLite database as its working memory and as a shared task queue. The worker claims a task, loads that task's step plan, marks steps in progress and done with evidence, checks required SOP gates, and then marks the task done or failed.

• Claim a task: use the task_id named in the spawn message, or take the next pending task if none is given.
• Load the plan: read the task's steps and its sop_checklist, and skip steps already marked done.
• Record progress: mark each step in_progress, then done with a short piece of evidence.
• Enforce gates: refuse to mark a task done while required checklist items are still open.
• Finish: mark the task done or failed, and claim the next task until the queue is empty.

Install the skill in Claude or Claude Code

Download the skill as a ZIP from the directory page. Then choose one of these options, depending on how you run your agent.

For Claude Code, unzip the folder into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project. The skill's folder should contain SKILL.md.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

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

Set up the environment the skill needs

The skill does not work on its own. It needs the Hive agent framework, with a terminal_exec tool that lets the agent run commands, and a colony SQLite database that the queen agent has already created. The agent must also have the sqlite3 command-line tool available in its terminal.

The skill runs scripts and does not use the network, according to its listing. Its procedures are carried out through sqlite3 commands run via terminal_exec.

• sqlite3 command-line tool available to the agent
• Hive agent framework with terminal_exec
• A colony SQLite database created by the queen agent
• Your spawn message must include db_path and colony_id fields

How to trigger the skill with a natural request

You do not call this skill by name from a chat box. It activates when a worker agent is spawned with the right fields. In a Hive colony, the spawn message is what triggers it, so your request is really the spawn message the queen or your orchestration code sends.

The skill applies when the spawn message has db_path: and colony_id: fields. If it also has a task_id: field, the worker claims that specific row. If not, it falls back to taking the next pending task from the queue.

• Include db_path: pointing at the colony SQLite file, and colony_id: for the colony.
• Include task_id: to assign one specific task; leave it out for a generic fan-out worker.
• A spawn message without db_path does not activate this skill.

Examples of what the worker does

The examples below show the sequence the skill follows. The exact values come from your own database and spawn message.

Example 1, assigned task: the spawn message names task_id 42. The worker runs an UPDATE that claims row 42 only if it is still pending. If the command returns nothing, another worker got there first or the task is already done, so the worker stops and reports. If a row comes back, the worker loads steps for task 42, skips any already marked done, and works through the rest.

Example 2, gate check: before reporting success, the worker lists required checklist items that have no done_at timestamp. If any remain, it completes that work, records a note, and checks the item off. Only an empty result lets it mark the task done.

What the skill refuses to do: safety and guardrails

The skill sets firm rules for the worker. It forbids schema changes (CREATE, ALTER, DROP) and DELETE, so failed tasks stay in the table as failed for audit. It also forbids skipping the SOP gate check and inventing task IDs; only the queen adds new tasks.

The skill runs scripts and runs sqlite3 commands against a shared database. Its listing warns that a misconfigured database could be corrupted if agents ignore these rules, so treat the database file as production state and restrict who can write to it.

• Do not run CREATE, ALTER or DROP.
• Do not run DELETE.
• Do not mark a task done while required SOP items are open.
• Do not hold a claimed task for more than 15 minutes without updates; the stale-claim reclaimer revokes it.
• Workers only update existing rows.

Tips for getting reliable results

Keep the database on a path the worker can reach and make sure the queen has created the tables before any worker starts. Check queue health with a simple count query when you suspect a stall.

When a write hits a locked database, the skill tells the worker to retry with backoff, up to five attempts, and notes that busy_timeout=5000 handles most contention.

• Check queue health: SELECT status, count(*) FROM tasks GROUP BY status;
• Check a worker's in-flight work: SELECT id, goal, status FROM tasks WHERE worker_id='<worker-id>';
• On 'database is locked' errors, retry with 100ms to 1s backoff, max 5 attempts.