Pilot Formation

Deploy predefined network topologies (star, ring, mesh, tree) for structured swarms. Use this skill when: 1. You need specific communication patterns (star c...

Security Scan

The skill's requirements and instructions are coherent for forming network topologies with pilotctl, but review and test it before use because it performs privileged network actions (handshakes/approvals/publish) and the SKILL.md omits declaring jq as a required binary.

Purpose & Capability

Name/description match the runtime instructions: the skill calls pilotctl to discover peers, handshake, approve, and publish topologies. Requested binary (pilotctl) is appropriate. Minor inconsistency: SKILL.md and prose reference jq for JSON parsing, but the registry metadata's required bins list only pilotctl (jq is not declared).

Instruction Scope

Instructions remain within the stated purpose (forming star/ring/mesh/tree topologies). They do, however, include potentially sensitive operations: automated handshake initiation, bulk approval of pending nodes, and publication of topology metadata to a registry host. These are expected for this skill but are high-impact actions—ensure you want the agent to perform them autonomously.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest install risk. The skill assumes pilotctl and jq are present on PATH; nothing is downloaded or written by the skill itself.

Credentials

No environment variables or credentials are requested. The operations use local pilotctl commands and transient variables (SWARM_NAME, REGISTRY_HOST). This is proportionate to the described functionality. Note: jq is used but not declared as a required binary in the registry metadata.

Persistence & Privilege

always is false and the skill does not request persistent system-wide changes beyond interacting with the pilot daemon via pilotctl. Autonomous invocation is allowed (platform default); combined with the skill's privileged actions (approvals/publish) this increases potential impact if misused, but this is expected behaviour for a network-formation skill.

Assessment

This skill is coherent for forming swarms using the pilotctl tool, but you should only install it if you trust the pilotctl binary and the pilot daemon on your host. Before installing: (1) verify pilotctl and jq are installed from trusted sources (SKILL.md uses jq but the registry metadata does not list it), (2) review the handshake/approve loops — they will automatically approve pending nodes which could add untrusted peers to your topology, (3) confirm where pilotctl will publish topology data (REGISTRY_HOST) so you don't inadvertently leak sensitive metadata, (4) test in an isolated environment first, and (5) ensure you have logging/backup of current topology in case you need to roll back. If you need lower risk, request a version that requires manual approval steps instead of bulk/automated approvals.

Deploy structured network topologies with automatic peer handshaking and trust establishment. Supports star (hub-and-spoke), ring (circular), mesh (all-to-all), tree (hierarchical), and line (chain) formations.

Commands

Deploy star (hub connects to all spokes):

WORKERS=$(pilotctl --json peers --search "role:worker" | jq -r '.[].hostname')
for worker in $WORKERS; do
  pilotctl --json handshake "$worker" "Forming star topology"
  sleep 1
  NODE_ID=$(pilotctl --json pending | jq -r '.pending[] | select(.hostname == "'"$worker"'") | .node_id')
  [ -n "$NODE_ID" ] && pilotctl --json approve "$NODE_ID"
done

Deploy ring (circular connections):

AGENTS=$(pilotctl --json peers --search "swarm:$SWARM_NAME" | jq -r 'sort_by(.node_id) | .[].address')
# Connect to next agent in sorted order (implementation in workflow)

Deploy mesh (all-to-all):

ALL_PEERS=$(pilotctl --json peers --search "swarm:$SWARM_NAME" | jq -r '.[].address')
for peer in $ALL_PEERS; do
  pilotctl --json handshake "$peer" "Forming mesh topology" &
done
wait

# Approve all pending handshakes
PENDING=$(pilotctl --json pending | jq -r '.[].node_id')
for peer in $PENDING; do
  pilotctl --json approve "$peer" &
done
wait

Workflow Example

#!/bin/bash
# Deploy star topology

SWARM_NAME="task-swarm"
MY_ADDR=$(pilotctl --json info | jq -r '.address')
REGISTRY_HOST="registry.example.com"

# Get swarm members
SWARM_MEMBERS=$(pilotctl --json peers --search "swarm:$SWARM_NAME" | jq -r '.[].address')

echo "Deploying star topology (hub: $MY_ADDR)"

# Hub connects to all spokes
for worker in $SWARM_MEMBERS; do
  if [ "$worker" != "$MY_ADDR" ]; then
    echo "Connecting to spoke: $worker"
    pilotctl --json handshake "$worker" "Forming star topology"
    sleep 1
    NODE_ID=$(pilotctl --json pending | jq -r '.pending[] | select(.hostname == "'"$worker"'") | .node_id')
    [ -n "$NODE_ID" ] && pilotctl --json approve "$NODE_ID"
  fi
done

# Publish topology
pilotctl --json publish "$REGISTRY_HOST" "topology:$SWARM_NAME" \
  --data "{\"type\":\"star\",\"hub\":\"$MY_ADDR\",\"formed_at\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

echo "Star topology complete"

Dependencies

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