name

name: {{name}} description: {{description}} allowed-tools: - Read - Bash

This skill queries an external provider via the relay-proxied telclaude provider-query CLI. Direct network calls to provider endpoints are blocked by the firewall and hook layer; always use the CLI.

When to Use

Invoke this skill when the user asks for data from the provider this skill wraps. Consult references/provider-schema.md (written by the relay at startup) for the authoritative list of services and actions.

User ID

You must extract the actor user ID from <request-context user-id="..." /> in your system context and pass it via --user-id on every call. Requests without it are rejected with HTTP 401.

Calling the Provider

telclaude provider-query \
  --provider {{name}} \
  --service <service> \
  --action <action> \
  --user-id <actor-id>

Pass structured parameters via --params with a JSON string:

telclaude provider-query \
  --provider {{name}} \
  --service <service> \
  --action <action> \
  --user-id <actor-id> \
  --params '{"startDate": "2026-01-01"}'

Handling Responses

The CLI emits a JSON object. The common shape is:

{
  "status": "ok",
  "data": { },
  "attachments": []
}

status: ok — present the data, respecting any confidence / lastUpdated fields.
status: auth_required — tell the operator the service needs setup.
status: challenge_pending — explain the /otp <service> <code> flow.
status: error — surface the error message concisely.

Attachments

When an attachment has a ref, deliver it with telclaude send-attachment --ref <ref>. When it has only an id, fetch via telclaude fetch-attachment. The path emitted on stdout must appear verbatim in your reply so the relay can forward the file to the user.

Guardrails

Never call provider URLs directly (WebFetch, curl, fetch). The firewall blocks them and the hook layer returns a descriptive error.
Never ask the user for API keys or OAuth tokens. The relay handles auth.
Do not log or echo response bodies that may contain secrets.
Use neutral credential placeholders such as <provider-token-placeholder>, sk-..., ghp_xxxxxxxxxxxxxxxxxxxx, example-token-placeholder, or redacted; do not include realistic provider tokens, bearer tokens, cookies, sessions, or infrastructure secret environment names.