# Agent Skills (/skills/overview)



<SurfaceStatus id="skills" />

The `riffads` plugin gives Claude Code the RiffAds MCP tools plus a written procedure: look up, estimate, quote, submit, follow, hand over the file. No code, no new capability.

## Install [#install]

```bash title="Inside Claude Code"
/plugin marketplace add riffads-ai/skills
/plugin install riffads@riffads
```

* `riffads@riffads` is `<plugin>@<marketplace>`. The repo is its own marketplace.
* Claude Code only. Other clients get the same tools, without the procedure: [connect a client](/mcp/connect).
* No API key. The plugin adds the MCP server, and you sign in in a browser.

The plugin ships this `.mcp.json`:

```json title=".mcp.json"
{
  "mcpServers": {
    "riffads": {
      "type": "http",
      "url": "https://mcp.riffads.com"
    }
  }
}
```

Not live for you yet? Add the server by hand. You get all 17 tools, just not the procedure:

```bash title="Terminal"
claude mcp add --transport http riffads https://mcp.riffads.com
```

## First run [#first-run]

<Steps>
  <Step>
    ### Sign in [#sign-in]

    The first tool call opens a browser. Sign in and approve.
  </Step>

  <Step>
    ### Pick a workspace (only if you have several) [#pick-a-workspace-only-if-you-have-several]

    Until you pick, every call refuses with `connection_not_configured`. Pick at [app.riffads.com/connections](https://app.riffads.com/connections).
  </Step>

  <Step>
    ### Just ask [#just-ask]

    No command to type. A skill loads when your request matches:

    * "make me an ad"
    * "what would this cost in RiffAds"
    * "give me four variants of this image"
    * "the same script with three different actors"
  </Step>
</Steps>

Check it worked: ask "What are you connected to?". The agent calls `riffads_ping` and names the workspace.

## The three skills [#the-three-skills]

| Skill                   | Use it for                                                                     | Loads on                                                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `cost-aware-generation` | Any single generation, including talking actor ads. The other two build on it. | "make me an ad", "generate a talking actor video", "what would this cost in RiffAds", "check on the RiffAds generation from earlier" |
| `batch-image-variants`  | Up to 4 takes of one image or video config, read back with `get_batch`.        | "give me four variants of this image", "some options for this product shot"                                                          |
| `batch-actor-variants`  | One script, several actors, through a workflow template.                       | "the same script with three different actors", "which actor reads this script best", "run a RiffAds workflow"                        |

All three can start paid work. Only the short descriptions load each session. The full procedure loads when a skill runs.

## How the agent behaves [#how-the-agent-behaves]

**Free calls first.** Never submits to find out a price.

| # | Tool                    | Why                                                          |
| - | ----------------------- | ------------------------------------------------------------ |
| 1 | `riffads_ping`          | Which workspace, whether it may spend. Once per conversation |
| 2 | `get_credit_balance`    | Stops early if nothing can be spent                          |
| 3 | `list_capabilities`     | Only if the capability id is unknown                         |
| 4 | `get_capability_schema` | Builds a valid config                                        |
| 5 | `estimate_generation`   | The number to quote                                          |
| 6 | `submit_generation`     | Only after you agree to the quote                            |

**Quotes before spending.** Tells you the number and waits for a yes. Sends `max_credits` of at least `ceil(estimate * 1.1)`, never a big round number.

**Follows the job itself.** Calls `wait_for_generation` until `still_running` is `false`. You do not have to ask "is it done?".

**Hands over the file fast.** Links last about 10 minutes. Expired links get refreshed with `get_generation`.

**Respects `retryable`.** `false`: never resends, explains or changes the request. `true`: at most 2 more tries, honouring `retry_after_seconds`. `moderation_blocked` is never reworded around.

**Talking actor = two generations.** `tts` first, then `generate_talking_actor` with `approved_voice_generation_id`. Quotes both up front.

**Several actors = a workflow.** Starts with `list_templates` (node ids cannot be guessed), sets `max_credits` for every step, polls `get_workflow_run` about every 30 seconds.

**Uploads honestly.** `create_upload`, one `PUT`, `finalize_upload`, and uses the asset only after `usable: true`. If it cannot make the `PUT`, it says so.

**Never says** posted, published or shared. Never says finished before the job ends. Never invents an actor id, voice id, capability id or number.

## Guidance, not enforcement [#guidance-not-enforcement]

The server enforces every rule on every call, plugin or not: moderation, `max_credits`, workspace spend caps, one agent submission at a time. An agent that skips the procedure gets refused, not overcharged.

Every tool and argument: [MCP tools](/mcp/tools). Every refusal code: [errors](/reference/errors).