Pilot Role Assign

Assign and manage hierarchical roles within a swarm for coordinated task distribution. Use this skill when: 1. Agents need different responsibilities (leader...

Security Scan

The skill's stated purpose (role assignment via pilotctl) matches the instructions, but the runtime instructions reference tools and environment variables that are not declared, which is an incoherence you should understand before installing.

Purpose & Capability

The name/description (assigning roles in a swarm) align with the commands in SKILL.md which call pilotctl to publish capabilities, query inbox, and send role_assignment messages.

Instruction Scope

SKILL.md instructs the agent to read the pilotctl inbox and peers, publish messages, and send role assignment messages — all consistent with the stated purpose. However the instructions reference many environment variables ($SWARM_NAME, $AGENT_ID, $AGENT_ADDRESS, $ROLE_NAME, $COORDINATOR_ID, REGISTRY_HOST) and expect jq/base64 to be available, but the skill does not declare these env vars or those binaries in its metadata. The agent will rely on external message contents (inbox) which may contain arbitrary data; the skill gives the agent little guidance about validation or authorization when sending assignments.

Install Mechanism

This is instruction-only (no install spec, no code files), so nothing is written to disk by the skill itself. That lowers installation risk. The SKILL.md does require pilotctl to already be present on PATH.

Credentials

The skill declares no required environment variables, yet its examples and workflow assume many runtime env vars. It also references jq and base64 (not declared as required binaries). While it does not request secrets or cloud credentials, the mismatch between declared requirements and what the instructions actually use is a proportionality/information problem that could lead to misconfiguration or unexpected behavior.

Persistence & Privilege

always is false and there is no install step modifying agent settings. The skill does not request permanent platform privileges or modify other skills' configs.

What to consider before installing

Before installing or enabling this skill: 1) Verify that the pilotctl binary you will use is the legitimate, trusted implementation from the pilot-protocol project (check the homepage and upstream releases). 2) Ask the author/maintainer to update the skill metadata to list jq and base64 as required bins (or remove their usage), and to declare the environment variables the skill expects. 3) Confirm how role assignments are authorized—who can send them and whether messages in the pilotctl inbox are validated or signed—because the skill reads inbox messages and forwards assignments. 4) Test in an isolated environment (not production) to observe behavior and make sure no unexpected messages are sent. If you cannot get clarification about the undeclared env vars/tools or about authorization/validation of messages, treat the skill as risky to enable in production.

Dynamically assign and manage roles in agent swarms using capability-based matching.

Commands

Advertise agent capabilities

pilotctl --json publish "registry-hostname" "capabilities:$SWARM_NAME" \
  --data "{\"agent\":\"$AGENT_ID\",\"capabilities\":{\"cpu_cores\":16,\"ram_gb\":64,\"gpu\":true}}"

Assign role to agent

pilotctl --json send-message "$AGENT_ADDRESS" \
  --data "{\"type\":\"role_assignment\",\"role\":\"$ROLE_NAME\",\"assigned_by\":\"$COORDINATOR_ID\"}"

pilotctl --json publish "registry-hostname" "roles:$SWARM_NAME" \
  --data "{\"agent\":\"$AGENT_ID\",\"role\":\"$ROLE_NAME\",\"assigned_at\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

Query current role distribution

ROLE_DIST=$(pilotctl --json inbox \
  | jq '[.messages[] | select(.topic == "roles:'$SWARM_NAME'")] | group_by(.payload.role) | map({role: .[0].payload.role, count: length})')
echo "$ROLE_DIST" | jq '.'

Workflow Example

Coordinator assigns roles based on capabilities:

#!/bin/bash
SWARM_NAME="compute-swarm"
REGISTRY_HOST="registry.example.com"

# Get agent capabilities
CAPABILITIES=$(pilotctl --json inbox | jq '[.messages[] | select(.topic == "capabilities:'$SWARM_NAME'") | .payload]')

for agent_data in $(echo "$CAPABILITIES" | jq -r '.[] | @base64'); do
  AGENT=$(echo "$agent_data" | base64 -d | jq -r '.agent')
  HAS_GPU=$(echo "$agent_data" | base64 -d | jq -r '.capabilities.gpu // false')

  if [ "$HAS_GPU" = "true" ]; then
    ROLE="gpu_worker"
  else
    ROLE="worker"
  fi

  AGENT_ADDR=$(pilotctl --json peers | jq -r '.[] | select(.node_id == "'$AGENT'") | .address')

  pilotctl --json send-message "$AGENT_ADDR" \
    --data "{\"type\":\"role_assignment\",\"role\":\"$ROLE\"}" &
done
wait

Dependencies

Requires pilot-protocol skill, jq, and base64.