Skip to main content

​
PoYo Agent Skill

The poyo-ai-models Skill teaches compatible coding agents to discover models, validate schemas, execute safely, and resume asynchronous tasks. The Skill is distributed from the poyo-devtools repository under:
It works with or without MCP. If PoYo MCP is connected, the agent can use MCP tools. Otherwise it runs models through the PoYo CLI with npx @poyoapi/cli.

​
Install

Run this in your project directory, replacing claude-code with codex or cursor as needed. Add --global to install it for all projects, or omit --agent to choose another client interactively:
Supported clients include Codex, Claude Code, Cursor, GitHub Copilot, and any client that supports Agent Skills. The installer needs Node.js 18 or newer; the CLI it uses needs Node.js 20 or newer. Verify that the key works before asking the agent to run a model:
For the full setup, including an example prompt, see the Quickstart. Source: PoyoAPI/poyo-devtools.

​
How it executes

  • MCP connected: the agent calls PoYo MCP tools such as poyo_search_models, poyo_run_model, and poyo_check_job. See Connect with MCP.
  • No MCP: the agent runs npx @poyoapi/cli, for example submit MODEL_ID ... followed by task wait TASK_ID. The CLI uses the key saved by auth login.
  • Streaming chat: the agent uses the CLI, because MCP poyo_chat returns one complete result.

​
Workflow

The Skill instructs an agent to:
  1. Restate modality, inputs, constraints, output requirements, and budget.
  2. Search the production Capability Catalog.
  3. Inspect the selected model’s schema.
  4. Choose non-streaming MCP chat, CLI streaming chat, short generation, or asynchronous submission.
  5. Poll queued/running tasks until they succeed or fail.
  6. Report model ID, status, outputs, and partial failures.

​
Guardrails

  • Never invent a model ID or parameter.
  • Never put an API key in a prompt or committed file.
  • Do not automatically resubmit a request after a timeout or transport failure; first determine whether a task was created.
  • Do not claim completion while a task is queued or running.
  • Preserve task IDs so an interrupted workflow can resume without resubmission.

​
Troubleshooting

​
Authentication fails after auth login

Credential priority is --api-key, then POYO_API_KEY, then the system keyring, then local config. An old or invalid POYO_API_KEY environment variable overrides the key saved by auth login. Check which source is used:
The output shows the source, such as (environment) or (keyring). Unset the stale variable or update it.

​
npx skills add fails with “Failed to clone”

The installer clones from GitHub. Make sure your network can reach github.com, and configure a proxy for git if needed.

​
JSON input breaks on Windows

Inline --input '{...}' JSON is often broken by shell quoting on Windows. Prefer schema flags such as --prompt "..." --resolution 1K, or put the request in a file and pass --input-file.