difflabai/ats-skill

Overview

This skill connects to the Agent Task Service (ATS) backend to orchestrate work between AI agents and humans. It exposes commands to create, list, claim, complete, and manage tasks, plus real-time event watching and task messaging. Use it to coordinate handoffs, track progress, and implement human-in-the-loop workflows.

How this skill works

The skill uses the ATS CLI to communicate with a PostgreSQL-backed ATS server (default https://ats.difflab.ai). It issues commands to create and modify tasks, claim leases, post and list messages, and subscribe to event streams. Configuration comes from CLI flags, environment variables, or the local ATS config file, with a clear priority order.

When to use it

• When you need to create tasks that require human review or approval.
• To claim, process, and complete work items programmatically or from agents.
• When you must monitor real-time task events and react to state changes.
• To add audit messages or structured data to task threads.
• When coordinating escalation or handoff between agents and humans.

Best practices

• Set ATS actor identity via environment variables or CLI flags to ensure clear audit trails.
• Respect lease durations: renew or complete tasks before the lease expires to avoid requeueing.
• Use JSON output (-f json) for scripting and jq for safe, reliable pipelines.
• Assign meaningful types, channels, and priority levels to enable filtering and routing.
• Watch specific event types or channels to reduce noise in real-time integrations.

Example use cases

• Create an approval task for a human to authorize a production deployment and poll until completion.
• Claim a code-review task, run automated checks, then complete with review outputs.
• Escalate critical decisions by creating a high-priority human task with contextual payload.
• Stream task.created and task.completed events to a dashboard or automation pipeline.
• Post progress messages and structured data to a task thread for auditability.