Troubleshooting & FAQ

Agent skills

Runtype publishes official agent skills that teach Claude Code, Cursor, Codex, Copilot, Windsurf, and 30+ other coding agents how to build on Runtype. A skill is a packaged set of instructions, references, and helper scripts the agent loads on demand — once installed, your coding agent knows Runtype’s product schema, MCP tools, flow step types, and SDK conventions without you re-explaining them in every prompt.

Skills are installed via the open-source skills CLI, which auto-detects which coding agents you have installed and drops the right files in the right place.

Install all Runtype skills

Run this once from any project (or your home directory for global install):

$npx skills add runtypelabs/skills

The CLI detects your installed agents and installs every Runtype skill for each of them. That’s it — restart your coding agent and the skills are available.

Install with the Runtype CLI

If you already have the Runtype CLI installed (npm install -g @runtypelabs/cli), you can install skills without a separate tool — it bundles the same agent detection:

Global CLI installations automatically check npm once per hour and stage verified releases under ~/.runtype/cli/versions/ for the next invocation. Use runtype update --check, runtype update, or runtype update --rollback to manage updates manually. Set RUNTYPE_DISABLE_AUTO_UPDATE=true to keep using the package-manager-installed version (including an intentional global version pin), or RUNTYPE_DISABLE_UPDATE_CHECK=true to retain the active managed version without checking for newer releases.

$npx -y @runtypelabs/cli@latest onboard

This is the recommended setup path: runtype onboard signs you into Runtype, targets the current coding agent, installs its Runtype skills, configures hosted OAuth MCP, and prints the exact restart or reload step. Run runtype install-mcp instead when you only want the skills and MCP portion without CLI sign-in, and runtype skills install only when you intentionally want skills without MCP. See Connect Runtype to coding agents for the full walkthrough.

To see which agents the skills-only command detects:

$runtype skills list

To target specific agents, pass their short ids (for example claude, cursor, codex):

$runtype skills install --agent claude --agent cursor

Useful flags:

  • --yes — skip the confirmation prompt (for scripts and CI)
  • --json — structured, non-interactive output
  • --verbose — show install progress

The first time you run any runtype command in an interactive terminal, the CLI also offers this install once automatically.

Install specific skills

To pick a subset interactively:

$npx skills add runtypelabs/skills --list

To install one skill non-interactively:

$npx skills add runtypelabs/skills --skill runtype-build-product -y

Available skills

SkillWhen to use it
runtypeUmbrella onboarding and routing skill. Loads first when the agent recognizes “Runtype” and routes to the focused skill below.
runtype-build-productBuild and validate hosted Runtype products: agents, flows, tools, surfaces, records, schedules, secrets, evals.
runtype-adminOperate a live Runtype account: inspect resources, debug traces and logs, run evals, apply careful mutations.
runtype-personaEmbed, theme, and debug Persona chat widgets, fullscreen assistants, client tokens, and browser-side local tools.
runtype-templatesCreate, validate, and package distributable Runtype FPO templates with pending secrets and import readiness checks.
runtype-sdk-marathonUse the Runtype SDK, CLI, Marathon, playbooks, sandboxes, and code-first stored/upsert/virtual workflows.

Most users want all of them — install once, and the right skill activates based on what you’re asking.

Target a specific agent

The CLI auto-detects installed agents, but you can scope an install to one with the -a flag (repeatable):

$npx skills add runtypelabs/skills -a claude-code -a cursor

Supported agents include claude-code, cursor, codex, copilot, windsurf, cline, gemini, opencode, and many others. See the skills.sh agent directory for the full list and per-agent install paths.

Connect the MCP server

Skills are most useful alongside the Runtype MCP server, which lets the agent read your live workspace and create resources directly. Run the all-in-one onboarding command rather than choosing a separate manual configuration path:

$npx -y @runtypelabs/cli@latest onboard

Complete the sign-in and OAuth actions it reports, then restart or reload the coding agent so it can activate the newly configured tools. If you are already signed into the CLI, runtype install-mcp performs just the skills and MCP steps. See the canonical agent onboarding script for the full first-session sequence.

Updating and removing

$npx skills update runtypelabs/skills   # pull latest versions
$npx skills list                        # show installed skills
$npx skills remove runtype-build-product

Next steps