Pilot Presence

Real-time online/offline/busy presence tracking for agent fleets using ping and pub/sub. Use this skill when: 1. You need to track which agents are online/of...

Security Scan

The skill's requirements and instructions are coherent with a presence-tracking purpose; it is instruction-only, asks only for pilotctl and jq, and does not request unrelated credentials or privileged installation.

Purpose & Capability

The name/description (real-time presence via ping and pub/sub) matches the runtime instructions which call pilotctl for ping/peers/publish/subscribe and use jq for JSON handling. Requiring the pilot-protocol skill and the pilotctl binary is appropriate for this functionality.

Instruction Scope

SKILL.md stays on-topic: it shows ping, peers, publish, subscribe commands and a simple broadcaster loop. It reads a local status file (/tmp/pilot-presence-status.txt), calls pilotctl --json info (which exposes hostname and other agent info), and repeatedly publishes presence payloads. These actions are consistent with presence tracking but do transmit agent identifiers and timestamps to the configured coordinator/peers — verify that those recipients are trusted and that publishing this metadata is acceptable.

Install Mechanism

No install spec is provided (instruction-only). Nothing is written to disk by the skill itself; risk is limited to the external pilotctl binary and its network behavior.

Credentials

Requires no environment variables or credentials. The skill does not request unrelated secrets or config paths.

Persistence & Privilege

always:false and normal model invocation; the skill does not request elevated persistent presence or modification of other skills or system-wide settings.

Assessment

This skill is coherent for presence tracking, but before installing: 1) Verify the pilotctl binary and pilot-protocol skill come from a trusted source and review what network endpoints pilotctl contacts. 2) Confirm the coordinator/peers you will publish to are trusted — the skill broadcasts hostnames and timestamps which could reveal availability patterns. 3) If you have privacy/infosec concerns, restrict or sanitize the published payload, avoid writing secrets to the status file, and consider adding authentication/encryption to the pub/sub channel. 4) Be aware the example runs an infinite loop that periodically publishes; ensure this behavior and interval are acceptable for network load and privacy. If you want more assurance, request the pilotctl source or documentation and inspect its network/auth behavior before enabling this skill.

Real-time presence tracking for Pilot Protocol agents. Track online/offline/busy states, broadcast presence changes via pub/sub, and maintain agent availability directories.

Commands

Ping for liveness:

pilotctl --json ping <target-hostname> [--count <n>] [--timeout <ms>]

Get connected peers:

pilotctl --json peers

Publish presence:

pilotctl --json publish <target-hostname> "presence.status" --data '{"hostname":"myagent","status":"online","timestamp":"2026-04-08T10:00:00Z"}'

Subscribe to presence:

pilotctl --json subscribe <target-hostname> "presence.*" [--timeout <seconds>]

Workflow Example

#!/bin/bash
# Broadcast presence every 30 seconds

COORDINATOR="${1:-presence-coordinator}"
INTERVAL=30
STATUS_FILE="/tmp/pilot-presence-status.txt"
echo "online" > "$STATUS_FILE"

while true; do
  status=$(cat "$STATUS_FILE" 2>/dev/null || echo "online")
  timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)

  info=$(pilotctl --json info 2>/dev/null)
  hostname=$(echo "$info" | jq -r '.data.hostname // "unknown"')

  presence_payload=$(jq -n \
    --arg hostname "$hostname" \
    --arg status "$status" \
    --arg timestamp "$timestamp" \
    '{hostname: $hostname, status: $status, timestamp: $timestamp}')

  pilotctl --json publish "$COORDINATOR" "presence.status" --data "$presence_payload"
  sleep "$INTERVAL"
done

Presence States

• online: Agent is reachable and accepting work
• busy: Agent is reachable but not accepting new work
• offline: Agent is unreachable
• away: Agent is reachable but operator is away

Dependencies

Requires pilot-protocol skill, jq, pilotctl binary, and running daemon.