> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Skills
> Teach any coding agent to test voice and chat AI agents with Roark
### Overview
Roark publishes 15 **Agent Skills**: short, focused guides that teach a coding agent how to use Roark. The [MCP Server](/documentation/sdks/mcp-server) gives an agent the tools to reach the Roark API; the skills give it the workflow and the judgment. Which testing template fits the goal, which metrics to attach, how to select flow variants without accidentally placing hundreds of calls.
They use the open Agent Skills format (a `SKILL.md` file plus an optional `references/` folder), so they are not tied to one vendor. Claude Code, Codex, Cursor, Gemini CLI and GitHub Copilot all read them.
Skills and the MCP server are independent. Skills work on their own and make an agent better at reasoning about Roark, but an agent still needs the [MCP server](/documentation/sdks/mcp-server), the [CLI](/documentation/sdks/cli) or an [SDK](/documentation/sdks/node-sdk) to actually call the API.
***
### Install
The `skills` CLI installs straight from the Roark repository:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
npx skills add roarkhq/mcp-roark-analytics
```
This installs all 15 skills into the current project. The files land in `.agents/skills/`, and the CLI additionally links them into the directory of whichever agent it detects, so seeing both `.agents/skills/` and (for example) `.claude/skills/` afterwards is expected rather than a duplicate install.
To choose targets explicitly, repeat the `-a` flag once per agent:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
npx skills add roarkhq/mcp-roark-analytics -a codex -a cursor -a gemini-cli -a github-copilot
```
A comma-separated list such as `-a codex,cursor` is read as one agent name and rejected. Repeat the flag instead.
Add `-g` to install for your user account rather than the current project, and `-a '*'` to install for every agent the CLI knows.
In Claude Code, install the skills and the MCP server together as one plugin:
```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
/plugin marketplace add roarkhq/mcp-roark-analytics
/plugin install roark@roark
```
Set your API key in the environment that launches Claude Code:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
export ROARK_API_BEARER_TOKEN="your-api-key"
```
The plugin is the simplest route for Claude Code because it brings the API tools along with the skills. The `npx skills add` command also works and installs the skills only.
Every skill is a directory of plain Markdown, so you can copy them yourself from the [plugin repository](https://github.com/roarkhq/mcp-roark-analytics/tree/main/plugins/roark/skills):
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
git clone https://github.com/roarkhq/mcp-roark-analytics
mkdir -p .agents/skills
cp -r mcp-roark-analytics/plugins/roark/skills/* .agents/skills/
```
Copy the whole directory. The skills reference each other by relative path, so installing a subset leaves broken links.
Confirm what landed:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
npx skills list
```
***
### Supported agents
The `skills` CLI writes one shared tree and every agent below reads it, so there is nothing to convert per vendor.
| Agent | Install location | Notes |
| :------------- | :---------------- | :---------------------------------------------------------------------------------------------- |
| Claude Code | `.claude/skills/` | Linked to `.agents/skills/`, not a second copy. Or install the plugin to get the MCP server too |
| Codex | `.agents/skills/` | Universal layout |
| Cursor | `.agents/skills/` | Also reads `.claude/skills/` and `.codex/skills/` |
| Gemini CLI | `.agents/skills/` | Universal layout |
| GitHub Copilot | `.agents/skills/` | Universal layout |
Windsurf, Zed, Cline, Goose, Warp, opencode and others are supported by the same command. Run `npx skills add roarkhq/mcp-roark-analytics -a '*'` to install for every agent the CLI detects.
**Install the skills as a set.** The skills cross-reference each other by relative path, and most of them point into `roark-concepts` for shared definitions. Any installer that packages skills one at a time breaks those links. That rules out Claude Desktop, whose **Customize → Skills** screen accepts one zip per skill and has no notion of sibling skills. Use Claude Code or one of the agents above instead.
***
### The skills
| Skill | Use it to |
| :------------------------ | :-------------------------------------------------------------------------------- |
| `roark-overview` | Understand the Roark object model and choose the right workflow. Start here |
| `roark-concepts` | Look up what each domain object *is*. The shared definitions the others reference |
| `register-agent` | Register an agent and the endpoint Roark should call |
| `author-personas-flows` | Define personas and improv customer flows |
| `author-scripted-flows` | Build exact IVR and DTMF conversation graphs |
| `configure-outbound-dial` | Configure the HTTP request used for outbound calls |
| `build-run-plan` | Assemble and start a simulation run |
| `manage-run-plans` | Find, edit, rerun, or delete saved run plans |
| `configure-metrics` | Select built-in metrics, checks, or custom metrics |
| `read-results` | Read run status, scores, transcripts, and pass/fail results |
| `monitor-live-calls` | Set up metric policies and backfill jobs for production traffic |
| `ingest-calls` | Import recordings and inspect call analysis and sentiment |
| `subscribe-webhooks` | Receive events instead of polling long-running jobs |
| `manage-config-as-code` | Reconcile agents, flows, personas, metrics, and collectors declaratively |
| `gate-ci` | Start a run and gate a CI or deployment pipeline on its results |
Agents load skills on demand, so having all 15 installed costs nothing until one is relevant to what you asked for.
#### Concepts versus skills
`roark-concepts` is generated rather than hand-written. It is synced from Roark's own source repository, and the same corpus composes the in-product assistant's prompt, so your coding agent and the assistant in the Roark dashboard cannot describe the product differently.
The division of labour is deliberate. A **concept** says what a thing is and which choice is right. A **skill** says which call to make and what the API will reject, including the places where the public vocabulary differs from the internal one. A flow's `mode: 'UNSCRIPTED'` is `type: 'IMPROV'` over the API, for example.
***
### Using them
Once installed, the agent picks the right skill from what you ask. You do not name skills explicitly:
```text theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
Set up a Roark simulation for my support agent. Register the agent, create a persona
and customer flow, attach metrics, and show me the estimated call count before starting.
```
*"Create a saved run plan covering our three billing flows with the frustrated-caller persona, attach task-completion and empathy metrics, and add a pass/fail check at 0.8."*
The agent uses `build-run-plan` and `configure-metrics` to assemble the plan, then reports the call count before it starts anything.
*"Add a GitHub Actions job that runs our nightly Roark plan and fails the build if any check fails."*
The agent uses `gate-ci`, which composes start, wait and assert, and warns you if the plan has no checks attached, since that would pass forever.
*"Our new phone tree asks for an account number, then routes to billing or support. Build a scripted flow that presses 1 and enters an account number."*
The agent uses `author-scripted-flows` for the conversation graph and DTMF entry, rather than an improv flow.
*"Score every real call our support agent takes this week for task completion, and alert me when it drops below 0.7."*
The agent uses `monitor-live-calls` to set up a standing metric collector over live traffic instead of a simulation.
Every simulated call is billable. The skills are written to create a run plan, report the estimated call count, and wait for you to confirm before starting a run. Review that number, especially when a plan multiplies flows, personas, endpoints and iterations.
***
### Keeping them current
The skills are versioned with the SDK surface they describe. Update them with:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
npx skills update
```
In Claude Code, the plugin updates with the marketplace. `skills-lock.json` records a content hash for each installed skill, so `skills update` can tell which ones actually changed and leave the rest alone. Commit that file to keep the set consistent across a team.
***
### Additional Resources
Give your agent access to the Roark API
Read the skills source
Drive Roark from your terminal and CI
Define agents, personas, flows and metrics as YAML
The TypeScript SDK the skills write against
Explore the full API documentation