agent-fleet/skill/SKILL.md

name	description
agent-fleet-integration	Interact with the Agent Fleet Orchestrator. Use this skill when you need to: - Register as an agent and pull tasks for execution - Query task status or list tasks - Submit completion receipts - Retry failed tasks - Integrate with Forgejo Issue → Task → PR workflow Applies when the agent is acting as a worker in an Agent Fleet cluster, or when managing tasks on behalf of the fleet.

Agent Fleet Integration Skill

Quick Start (http_pull mode)

Step 1. Register your agent:

curl -X POST http://localhost:9090/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"my-agent","agent_type":"openclaw","hostname":"myhost","capabilities":["code:rust"],"max_concurrency":2}'

Step 2. Pull and execute a task:

curl -X POST http://localhost:9090/api/v1/tasks/dequeue \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{"agent_id":"my-agent","capabilities":["code:rust"]}'

Step 3. Submit your result:

curl -X POST http://localhost:9090/api/v1/tasks/<task_id>/complete \
  -H 'Content-Type: application/json' \
  -d '{"task_id":"<task_id>","agent_id":"my-agent","status":"completed","duration_seconds":60,"summary":"done","artifacts":[],"error":null}'

---

Choosing Your Execution Mode

If you...	Use this mode
Have a CLI binary installed on a configured host	ssh_cli — Orchestrator calls you
Have your own scheduler or run outside configured hosts	http_pull — You call the API

• ssh_cli agents do not need to call any API. The Orchestrator handles everything via SSH or local subprocess.
• http_pull agents must register, heartbeat, dequeue, and complete via HTTP API.

---

Instructions

http_pull Agent Lifecycle

Register → Heartbeat (loop) → Dequeue → Execute → Complete/Deregister

1. Register once at startup via POST /api/v1/agents/register.
2. Heartbeat periodically (every 60s recommended) via POST /api/v1/agents/heartbeat. Without heartbeats, you will be marked offline and your tasks requeued.
3. Dequeue when ready for work via POST /api/v1/tasks/dequeue. Returns a Task or 204 No Content.
4. Update status to running via POST /api/v1/tasks/{task_id}/status.
5. Complete the task via POST /api/v1/tasks/{task_id}/complete with a Receipt.
6. Deregister when shutting down via POST /api/v1/agents/deregister.

ssh_cli Agent Notes

No API interaction required. Ensure:

• Your CLI binary is in $PATH on the configured host.
• Your CLI accepts a prompt via the configured template (default: codex exec --json '{prompt}' or claude -p '{prompt}' --output-format json --dangerously-skip-permissions).
• Your CLI outputs JSON to stdout with at minimum: {"status": "completed", "summary": "..."}.

---

Examples

Register

curl -X POST http://localhost:9090/api/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "worker-03",
    "agent_type": "openclaw",
    "hostname": "arm0",
    "capabilities": ["code:rust", "review"],
    "max_concurrency": 2,
    "metadata": {"version": "1.0"}
  }'

Heartbeat

curl -X POST http://localhost:9090/api/v1/agents/heartbeat \
  -H 'Content-Type: application/json' \
  -d '{"agent_id": "worker-03"}'

List Available Tasks

curl 'http://localhost:9090/api/v1/tasks?status=created'

Dequeue

curl -X POST http://localhost:9090/api/v1/tasks/dequeue \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer my-token' \
  -d '{"agent_id": "worker-03", "capabilities": ["code:rust"]}'

Returns 200 with Task JSON, or 204 if no matching task.

Get Task Detail

curl 'http://localhost:9090/api/v1/tasks/org%2Frepo%2342'

Update Task Status

curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/status \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer my-token' \
  -d '{"status": "running"}'

Complete Task with Receipt

curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/complete \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "org/repo#42",
    "agent_id": "worker-03",
    "status": "completed",
    "duration_seconds": 180,
    "summary": "Implemented the feature as described",
    "artifacts": [
      {"artifact_type": "pr", "url": "https://git.example/org/repo/pulls/15"}
    ],
    "error": null
  }'

Submit Receipt

curl -X POST http://localhost:9090/api/v1/receipts \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "org/repo#42",
    "agent_id": "worker-03",
    "status": "completed",
    "duration_seconds": 180,
    "summary": "Done",
    "artifacts": [],
    "error": null
  }'

Retry a Failed Task

curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/retry

Only works for tasks in failed or agent_lost status.

List Agents

curl 'http://localhost:9090/api/v1/agents?status=online&capability=code:rust'

Deregister

curl -X POST http://localhost:9090/api/v1/agents/deregister \
  -H 'Content-Type: application/json' \
  -d '{"agent_id": "worker-03"}'

Health Check

curl http://localhost:9090/healthz

---

Guidelines

Authentication

• http_pull endpoints (dequeue, status update): require Authorization: Bearer <token> if http_pull_token is configured. If not configured, no auth is needed.
• All other endpoints: no authentication required.
• Webhook endpoint: requires HMAC-SHA256 signature header.

Error Handling

Code	Meaning	Action
401	Unauthorized	Check your Bearer token. If expired, re-register to get a new one.
404	Not Found	Task may have been completed or never existed. Move on.
400	Bad Request	Check task status — the operation may not be valid for the current state (e.g. retrying a running task).
204	No Content (dequeue)	No matching tasks available. Wait and retry.
500	Server Error	Retry with exponential backoff. Report if persistent.

Retry Strategy

• Use exponential backoff for transient errors (network, 500s): 1s, 2s, 4s, 8s, max 30s.
• Do not retry 400 errors — fix your request.
• For 404 on dequeue: poll again after a reasonable interval (e.g. 10–30 seconds).
• The Orchestrator has its own retry logic for ssh_cli tasks (up to max_retries, default 2).

Task Status Flow

created → assigned → running → review_pending → completed
                               ↘ failed
                  ↘ agent_lost
         ↘ cancelled

• failed and agent_lost tasks can be retried via the retry endpoint.
• review_pending means a PR was opened and is awaiting merge/review.
• completed and cancelled are terminal states.

Heartbeat Requirements

• Send heartbeats at least every heartbeat_interval_secs (default: 60s).
• If the Orchestrator doesn't receive a heartbeat within heartbeat_interval_secs × heartbeat_timeout_threshold (default: 60 × 3 = 180s), your agent is marked offline.
• All active tasks assigned to an offline agent are requeued to created status.

---

Forgejo Workflow

Task Creation (Issue → Task)

1. Open a Forgejo Issue with a label agent:<type> (e.g. agent:code).
2. The webhook creates a task with task_id = {repo}#{issue_number}.
3. Optional labels: priority:urgent, priority:high, priority:low control priority.

Branch Naming

• Branch: task/{url_encoded_task_id}
• Example: org/repo#42 → branch task/org%2Frepo%2342

PR Workflow

1. Work on the task/* branch.
2. Open a PR from that branch.
3. Orchestrator receives pull_request.opened webhook → task goes to review_pending.
4. Pushes to the branch update last_activity_at.
5. When the PR is merged → task goes to completed with an auto-generated receipt.

For http_pull Agents

After dequeuing a task, create the branch and PR yourself:

git checkout -b task/org%2Frepo%2342
# ... do the work ...
git push origin task/org%2Frepo%2342
# Create PR via Forgejo API
# The webhook will update the task automatically

For ssh_cli Agents

The Orchestrator passes the branch name in the structured prompt. Create the branch, push, and open the PR as part of your CLI execution. The webhooks handle status updates.