AI agents

AI agent skill

One markdown file that teaches Claude Code — or any AI agent — the entire API: every endpoint, price, limit, and a step-by-step playbook for every kind of output. Install it, hand over a key securely, and your agent can build videos for you.

What it is

The skill is a single self-contained SKILL.md — the agent-readable twin of these docs. It carries the full endpoint reference, credit prices and purchase rates, account limits, polling rules, and ready-made playbooks (create a character, pick or clone a voice, estimate then queue a talking-head or multi-scene video, poll, deliver). It also teaches the agent to handle your key safely and to quote the credit cost of every video before firing it.

Grab it here: /skill/SKILL.md

Install for Claude Code

Download the skill

Personal install (available in every project)

mkdir -p ~/.claude/skills/promoat-partner-api
curl -fsSL https://platform.promoat.ai/skill/SKILL.md \
  -o ~/.claude/skills/promoat-partner-api/SKILL.md

Prefer it scoped to one repo? Use .claude/skills/promoat-partner-api/SKILL.md inside the project instead — same file, project-local.

Hand over your key — securely

Set the key as an environment variable

# In your shell profile (~/.zshrc / ~/.bashrc), or a gitignored .env:
export PROMOAT_KEY="pmat_..."   # from https://platform.promoat.ai/partner

Don't paste the key into the chat — conversations get logged and synced. The skill tells the agent to read PROMOAT_KEY from the environment, never print it, and never commit it. If a key does leak, ask Promoat support to replace it (rotation is not self-serve for current keys; see Authentication).

Use it

That's it — Claude Code discovers the skill automatically. Ask in plain language: “create a presenter from these two selfies and make a 30-second multi-scene video about our summer menu”. The agent will set up the character and voice, quote the credit cost, queue the job, poll it, and hand you the video URL.

MCP

This deployment also serves an MCP endpoint at https://platform.promoat.ai/mcp. Connect it with Authorization: Bearer $PROMOAT_KEY. Use the same key as above, and do not paste it into chat. When that server is connected, the agent calls these tools instead of raw HTTP. The quoting, idempotency, and polling rules in the skill still apply, and a failed tool returns the API JSON, including error_code and message.

get_balance, create_character, list_voices, clone_voice, estimate_video, create_video, get_job, get_scenes, fix_scene, edit_script, fix_sound, plus list, fetch, and delete for characters, voices, assets, and jobs, and regenerate_character, list_voice_presets, reclone_voice, synthesize_speech, create_first_frame, plan_scenes, and create_checkout_session. create_video and the three edit tools take idempotency_key, which is sent as the Idempotency-Key header.

Other agents & frameworks

The file is plain markdown with YAML frontmatter — nothing Claude-specific in the content. For any agent that can read files and run HTTP requests, attach SKILL.md as context (or paste it into the system prompt) and expose the key as the PROMOAT_KEY environment variable. Agent SDK users can load it as a skill directly.

The key spends real credits

An agent holding your key can charge your balance. Give it the same key hygiene you'd give a payment token: environment variables only, get it replaced on any suspicion, and keep the skill's default behavior of quoting costs via POST /videos/estimate before queueing.

Staying current

The skill is versioned alongside the API and served from this deployment, so re-running the download command picks up new endpoints and prices. If the agent ever sees behavior that contradicts the file, the live API — and /openapi.yaml — win.

← PreviousUsage & history Next →MCP server