Skip to content
CanaryCoders AI CanaryCoders AI Docs

AI Agent Skill

An Agent Skill for Codex and Claude Code that drives the gateway from a single Bun script — no resident MCP server, no extra process. Point an agent at it and it can research, search X, run any chat model, and generate or edit images through CanaryCoders AI.

What it does

  • Perplexity web research, with an optional reasoning-model pass
  • Grok/X (Twitter) search, scoped by handle and date range
  • Generic chat completion against any provider/model on the gateway
  • Image generation and editing, with reference images
  • Live provider/model catalogue lookup, for picking a model by capability and price

Prerequisites

  • Bun on PATH — the agent runs the skill's script with bun run
  • CANARY_AI_API_KEY in the environment the agent inherits (legacy CANARYLLM_API_KEY still works)
  • Optional CANARY_AI_BASE_URL only if you're pointing at a self-hosted gateway — the default is the hosted api.ai.canarycoders.es

The skill is a plain folder in the SDK's GitHub repo, not part of the published npm package. Installing or updating @canarycoders/ai never touches your ~/.claude or~/.codex config — installing, updating, and removing the skill are separate, explicit steps you run yourself.

Install — Claude Code

Claude Code has no built-in "install from GitHub" command for skills; the documented mechanism is copying the folder into a skills directory it auto-discovers. Personal (all projects):

bash
git clone https://github.com/CanaryCoders/canaryllm-sdk.git
mkdir -p ~/.claude/skills
cp -r canaryllm-sdk/skills/canary-ai ~/.claude/skills/canary-ai

Project-scoped instead (this repo only): copy to <project>/.claude/skills/canary-ai instead of the personal path. Start a new Claude Code session after installing so the skill is discovered.

Install — Codex

Codex ships a bundled skill-installer skill that installs straight from a GitHub path:

bash
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo CanaryCoders/canaryllm-sdk --path skills/canary-ai

Lands in $CODEX_HOME/skills/canary-ai (or ~/.codex/skills/canary-ai when CODEX_HOME is unset). If that skill isn't installed, fall back to the same manual clone-and-copy as Claude Code, targeting ~/.codex/skills/canary-ai. Restart Codex after installing.

Update

Neither agent version-pins or diffs skills — updating means replacing the directory contents. Codex's installer refuses to overwrite an existing install, so remove it first:

bash
git -C canaryllm-sdk pull

# Claude Code
rm -rf ~/.claude/skills/canary-ai
cp -r canaryllm-sdk/skills/canary-ai ~/.claude/skills/canary-ai

# Codex manual install
rm -rf ~/.codex/skills/canary-ai
cp -r canaryllm-sdk/skills/canary-ai ~/.codex/skills/canary-ai

If you installed through Codex's bundled installer, remove its existing directory and rerun the installer command above instead. Start a new agent session after updating.

Uninstall

No command, no registration to undo — just delete the directory:

bash
rm -rf ~/.claude/skills/canary-ai
rm -rf ~/.codex/skills/canary-ai

Model freshness and cost policy

The skill never hardcodes a model ID. Every command that doesn't get an explicit --model resolves one from GET /api/public/models at call time, filtered by the capability it needs (chat, image-generation, …). If a resolved model turns out region-locked or unavailable, it retries the next current match instead of failing outright.

Cost isn't a reason to skip a useful call, but among suitable models the agent is instructed to default to the least expensive one that meets the quality/context/reasoning bar, and only reach for premium/reasoning variants for complex or high-stakes requests — never below whatever quality or model the user explicitly asked for.

Skill source: canaryllm-sdk/skills/canary-ai

SDK repo: github.com/CanaryCoders/canaryllm-sdk