Skill: teoslayer/pilot-service-agents (version 1.0.0)

--- name: pilot-service-agents description: > Discover and query the pilot-service-agents catalogue — ~370 always-on data agents reachable over Pilot Protocol that wrap real-world APIs (Google Maps, OpenAlex, NHTSA, USGS, CoinGecko, NASA, aviation weather, and many more) so callers don't need their own API keys, rate limits, or HTTP plumbing. Use this skill when: 1. You need to answer a question that depends on up-to-date external data (geography, finance, aviation, science, health, academic literature, etc.) and do not want to hit the upstream APIs yourself. 2. You want to discover which agents exist for a topic before invoking one. 3. You want structured, paginated, filter-driven access to an upstream API without touching its SDK or auth. Do NOT use this skill when: - You want agent-to-agent chat (use pilot-chat instead). - You are looking for swarm/task coordination (use pilot-task-router instead). - You need to run your own data source — these agents are consumer-side only. tags: - pilot-protocol - service-agents - data-sources - discovery - data-exchange license: AGPL-3.0 compatibility: > Requires pilot-protocol skill and pilotctl binary on PATH. The daemon must be running (pilotctl daemon start) and joined to network 9 (data-exchange), which is where the catalogue lives. metadata: author: vulture-labs version: "1.0" openclaw: requires: bins: - pilotctl homepage: https://pilotprotocol.network allowed-tools: - Bash --- # pilot-service-agents Every service agent on Pilot Protocol exposes the **same four-command interface** over the overlay, so once you understand one you understand them all. The catalogue itself is served by a directory agent called `list-agents` — always start there. ## The flow: discover → pick → invoke → read inbox ``` pilotctl send-message list-agents --data "/data {filters}" (find agents) pilotctl send-message <hostname> --data "/help" (read contract) pilotctl send-message <hostname> --data "/data {filters}" (fetch data) pilotctl inbox (read response) ``` The send-message call returns an ACK immediately; the **actual response comes back as an inbox message** a few seconds later from the agent you called. ## Discovering agents via list-agents `list-agents` is the directory. Talk to it like any other agent. ### List all commands it supports ```bash pilotctl --json send-message list-agents --data "/help" pilotctl --json inbox ``` ### Filter the catalogue ```bash pilotctl --json send-message list-agents --data '/data {"category":"academic","limit":20}' pilotctl --json inbox ``` Supported filter fields on `list-agents` `/data`: | field | type | meaning | |---|---|---| | `category` | string | academic, geo, finance, news, health, science, security, … | | `tier` | string | `free` (no per-request cost) or `premium` (paid, higher quality, e.g. Google Cloud) | | `search` | string | substring match on hostname + category + description | | `hostname` | string | exact hostname match | | `limit` | int | max items (default 50, max 500) | The response envelope contains `items`, `count`, `total`, `groups` (counts per category), and `tiers.free` / `tiers.premium` buckets with their disclaimers. ### Gemini summary of matches ```bash pilotctl --json send-message list-agents --data '/summary {"category":"flights"}' pilotctl --json inbox ``` ### Free-text question over the catalogue ```bash pilotctl --json send-message list-agents --data 'which agent gives me Formula 1 race results?' pilotctl --json inbox ``` ## Talking to a specific service agent Once you have a hostname, the **same four commands** work on every agent: | message | what it does | |---|---| | `/help` | prints the filter schema + pagination + example call | | `/data {json}` | fetch real data, returns a normalised envelope | | `/summary {json}` | same fetch, piped through Gemini for prose | | `<any free text>` | Gemini picks filters and fetches | Filter shape for `/data` is agent-specific. Always read `/help` first — it lists every filter with type, required flag, default, and description. Premium agents (hostname prefix `gcp-`) announce themselves with a `[PREMIUM]` tag in `/help`. ### Canonical response envelope Every `/data` response has this shape: ```json { "source": "<hostname>", "items": [...], "count": <int>, "total": <int|null>, "page": <int|null>, "next": <cursor|null>, "truncated": <bool>, "upstream_url": "<resolved upstream URL>" } ``` ## Pagination If an agent's `/help` shows `Pagination: page|offset|cursor`, pass the knob in your filter JSON. The knobs the agent recognises are in the same `/help` output. Omit pagination and you get the upstream's default page. ## Workflow Example Answer "what aircraft are currently over Manhattan?" with zero upfront API knowledge: ```bash # 1. Find the right category pilotctl --json send-message list-agents --data '/data {"category":"flights","limit":5}' sleep 5 pilotctl --json inbox # pick e.g. adsb-lol-latlon # 2. Read its filter contract pilotctl --json send-message adsb-lol-latlon --data '/help' sleep 5 pilotctl --json inbox # 3. Query with the filters you just learned pilotctl --json send-message adsb-lol-latlon \ --data '/data {"lat":40.78,"lon":-73.97,"radius":8}' sleep 5 pilotctl --json inbox ``` ## What to expect across the catalogue The catalogue grows; treat every hostname list as a snapshot. To stay current, always start with `list-agents /data` — never hard-code a list. - **Free agents** — community API wrappers. Best for volume, exploration, unauthenticated lookups. Rate-limited on the upstream's side. - **Premium agents** — `gcp-*` hostnames, backed by Google Cloud credits managed centrally. Higher accuracy, SLA-grade freshness, real cost per call. - **Every agent caches upstream responses** for ~60s and serves stale data on upstream errors (`"cached": true, "cache_age_seconds": N` fields appear in the envelope when that happens). - **Authentication is handled agent-side.** You never hold an API key. ## Related skills (per category) There is a dedicated `pilot-service-agents-<category>` skill for each category in the catalogue — read one of those once you know which kind of data you need. Discover the list with: ```bash pilotctl --json send-message list-agents --data '/data {}' ``` Then look for the matching `pilot-service-agents-*` skill. ## Dependencies Requires pilot-protocol core skill, a running `pilotctl daemon` joined to network 9 (`pilotctl --json network join 9`), and the `list-agents` directory agent reachable on the overlay.

path: README.md
content: # Service Agents

Discover and query the pilot-service-agents catalogue — hundreds of always-on data agents on Pilot Protocol that wrap real-world APIs (Maps, OpenAlex, NHTSA, USGS, CoinGecko, NASA, and many more) so callers don't need their own API keys or HTTP plumbing.

**Category:** Data Sources | **License:** AGPL-3.0

## Install

```bash
clawhub install pilot-service-agents
```

## Requirements

- [Pilot Protocol](https://pilotprotocol.network) daemon running (`pilotctl daemon start`)
- `pilotctl` binary on PATH
- Daemon joined to network 9 (`pilotctl --json network join 9`)
- `list-agents` directory agent reachable on the overlay

## Tags

`pilot-protocol`, `service-agents`, `data-sources`, `discovery`, `data-exchange`

## Documentation

See [SKILL.md](SKILL.md) for the full skill definition including commands, examples, and error handling.

## Links

- [ClawHub](https://clawhub.ai/teoslayer/pilot-service-agents)
- [Pilot Protocol](https://pilotprotocol.network)
- [All Skills](https://teoslayer.github.io/pilot-skills/)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)