Agent Skills

Overview

Roark publishes 15 Agent Skills: short, focused guides that teach a coding agent how to use Roark. The 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, the CLI or an SDK to actually call the API.

Install

Any agent (recommended)
Claude Code
Manual

The skills CLI installs straight from the Roark repository:

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:

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:

/plugin marketplace add roarkhq/mcp-roark-analytics
/plugin install roark@roark

Set your API key in the environment that launches Claude Code:

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:

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:

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:

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.

Build a regression suite

“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.

Gate a deploy on a simulation

“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.

Author an IVR test

“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.

Grade production traffic

“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:

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

MCP Server

Give your agent access to the Roark API

GitHub Repository

Read the skills source

CLI

Drive Roark from your terminal and CI

Config as Code

Define agents, personas, flows and metrics as YAML

Node.js SDK

The TypeScript SDK the skills write against

API Reference

Explore the full API documentation

Getting Started

Simulations

Observability

Metrics

Config as Code

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Overview

Install

Supported agents

The skills

Concepts versus skills

Using them

Keeping them current

Additional Resources

MCP Server

GitHub Repository

CLI

Config as Code

Node.js SDK

API Reference

​Overview

​Install

​Supported agents

​The skills

​Concepts versus skills

​Using them

​Keeping them current

​Additional Resources

MCP Server

GitHub Repository

CLI

Config as Code

Node.js SDK

API Reference

Overview

Install

Supported agents

The skills

Concepts versus skills

Using them

Keeping them current

Additional Resources