Agents

Agent Skills

A Skill is a loadable context bundle: an instruction sheet, plus optional capability bindings, that an Agent pulls into its working context on demand instead of carrying every instruction in its system prompt up front. Use Skills to give an Agent deep, situational procedures (a refund protocol, a brand-voice guide, a data-export recipe) that only matter for some turns.

This page covers Runtype Agent Skills, the product feature your deployed Agents load at runtime. It is not the coding-agent skills that teach Claude Code, Cursor, and other editors how to build on Runtype. Both are files named SKILL.md, but they are unrelated.

How Skills work

A Skill keeps an Agent’s up-front context small. Instead of loading a long procedure into the system prompt for every run, you bind the Skill to the Agent and let the model pull it in only when the task calls for it.

Each bound Skill surfaces to the model as a virtual tool named skill:<slug> (for example, skill:refund-protocol). Runtype builds this tool from two levels of the manifest:

  • The description is what the model sees in its tool list. It decides when to load the Skill from this one line, so write it as a clear trigger (“Load when a user asks for a refund”).
  • The body is the full instruction sheet. It comes back as the tool result only when the Agent actually invokes the Skill, so a Skill costs almost nothing until it is used.

When the model calls skill:<slug>, the body loads and any capabilities the Skill binds (Flows, subagents, custom tools, inline tools) become available on the Agent’s next turn.

Skill manifest format

Skills use Anthropic’s SKILL.md format so external skill packs import without translation: YAML frontmatter followed by a markdown body. Runtype-specific capability bindings live under a runtype: key.

SKILL.md
1---
2name: refund-protocol
3description: How to process a customer refund end to end. Load when a user asks for a refund.
4runtype:
5  trustLevel: org
6  capabilities:
7    flowIds: [flow_...]
8    agentIds: [agent_...]
9    toolIds: [tool_...]
10    inlineTools: []
11---
12
13# Refund Protocol
14
151. Verify the order ID.
162. Confirm the item is within the return window.
173. Issue the refund and notify the customer.
FieldDescription
nameSlug, up to 64 characters. Lowercase letters, digits, _, and -, starting with a letter.
descriptionThe load trigger the model reads. State what the Skill does and when to load it.
trustLevelorg, imported, or community. Governs auto-publish for agent-proposed Skills (see below).
capabilities.flowIdsPublished Flows the Agent may invoke once the Skill loads.
capabilities.agentIdsSaved Agents the Skill makes available as subagents.
capabilities.toolIdsSaved custom tools.
capabilities.inlineToolsInline runtime tools defined in the manifest. Reference secrets only with {{secret:NAME}}.

All capability references are resolved with access checks at runtime, against the Skill owner’s permissions.

Manifests containing mcpServers are rejected when you import or save them, because their auth would embed literal credentials. Bind MCP tools through toolIds or inlineTools instead. Skills carry no secrets of their own: inline tools reference secrets only with {{secret:NAME}}.

Creating and binding a Skill

Create Skills from the Skills page in the dashboard, or through the REST API and SDK. Skills are owned by your organization or personal account, the same way Flows and Agents are.

  1. Author the manifest. Write the SKILL.md with frontmatter and a body.
  2. Create and publish it. POST /v1/skills with { markdown, publish: true }, or import a pasted manifest with POST /v1/skills/import.
  3. Bind it to an Agent. POST /v1/skills/bind with { agentId, skillId }. Binding is what makes the skill:<slug> tool appear in that Agent’s tool list.
  4. Point the Agent at it. The Agent’s system prompt can mention the skill:<slug> tool so the model knows it exists; the model loads it when the description matches the task.
cURL
$curl https://api.runtype.com/v1/skills \
>  -H "Authorization: Bearer $RUNTYPE_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{ "markdown": "---\nname: refund-protocol\n...", "publish": true }'

The REST surface is scoped by API-key permissions (SKILLS:READ and SKILLS:WRITE). There is no review queue on this path: authoring a Skill yourself is authoring.

Loading a Skill at runtime

When the model calls a skill:<slug> tool, Runtype returns the body as the tool result and emits an agent_skill_loaded event you can see in the execution log. Two behaviors are worth knowing.

Capability-expanding Skills trigger an approval gate. A Skill that binds tools the Agent does not already hold expands the Agent’s capability surface, so loading it pauses for approval before those tools activate. A knowledge-only Skill, or one that binds only tools the Agent already has, loads immediately with no approval.

Capabilities activate on the next turn. The Skill body loads within the current turn, but any tools it grants only become callable on a following turn. An Agent that needs to use a Skill’s bound capabilities must run a multi-turn loop, so enable Agent Loop with Max Turns of at least 2 on the Agent. Knowledge-only Skills work in a single turn.

Agent-proposed Skills

A running Agent can author a Skill for itself with the propose_skill tool. This is a separate governance path from admin authoring, and it is review-by-default.

Every proposal, including text-only ones, lands in a review queue for a human to approve or reject. A Skill body is instructions injected into another Agent’s working context, so “no new capability” is not treated as safe to publish automatically. propose_skill returns right away and emits agent_skill_proposed; it does not block the run in progress.

You can opt into auto-publish for your account. When you have turned it on and the proposed manifest’s trustLevel is org, a proposal publishes without review. The published Skill is scoped to the proposing Agent and auto-bound to it alone, with the audit trail on the proposal record.

Approving a proposal publishes the Skill but does not bind it to any Agent. Bind it separately with POST /v1/skills/bind (or from the dashboard) to make it loadable.

Next steps