Agents

Agent skills

A Skill is a loadable context bundle with instructions and optional capability bindings. Your Agent loads the bundle only when a task needs it, instead of carrying all of its instructions in every system prompt. Use Skills for procedures such as a refund protocol, a brand-voice guide, or a data-export recipe.

This page covers Runtype Agent Skills, which your deployed Agents load at runtime. For coding-agent skills that teach Claude Code, Cursor, and other editors how to build on Runtype, see coding-agent skills. The two features use files named SKILL.md, but they are unrelated.

How Skills work

Bind a Skill to your Agent. The model receives the Skill’s description with the other tools and loads the body only when the task matches the description.

Each bound Skill appears to the model as a virtual tool named skill:<slug>, such as skill:refund-protocol. Runtype builds this tool from the manifest’s description and body fields.

The following fields control when the model loads a Skill and which capabilities it receives:

  • description: Text that tells the model what the Skill does and when to load it. Write a trigger such as Load when a user asks for a refund.
  • body: The full instruction sheet that Runtype returns when the model invokes the skill:<slug> tool.

When the model calls skill:<slug>, Runtype returns the body as the tool result. Runtype makes the Skill’s bound capabilities available on the following turn.

Skill manifest format

Skills follow Anthropic’s SKILL.md format: YAML frontmatter followed by a Markdown body. Add Runtype-specific capability bindings under the runtype: key.

Use the following manifest to define a Skill with saved capability references:

SKILL.md
1---
2name: refund-protocol
3description: Process customer refunds. Load when a user asks for a refund.
4runtype:
5  trustLevel: org
6  capabilities:
7    flowIds: [flow_YOUR_FLOW_ID]
8    agentIds: [agent_YOUR_AGENT_ID]
9    toolIds: [tool_YOUR_TOOL_ID]
10    inlineTools: []
11---
12
13## Refund procedure
14
151. Verify the order ID.
162. Confirm that the item is within the return window.
173. Issue the refund and notify the customer.

Replace flow_YOUR_FLOW_ID, agent_YOUR_AGENT_ID, and tool_YOUR_TOOL_ID with the IDs of the Flows, Agents, and tools that you want the Skill to make available.

The runtype: block supports the following fields:

  • name: A slug of up to 64 characters. Use lowercase letters, digits, _, and -, and start with a letter.
  • description: Text of up to 1024 characters that tells the model what the Skill does and when to load it.
  • trustLevel: Set this to org, imported, or community. Runtype auto-publishes an agent-proposed Skill only when this value is org and the account enables auto-publish.
  • capabilities.flowIds: IDs of saved Flows that your Agent can invoke after the Skill loads.
  • capabilities.agentIds: IDs of saved Agents that your Agent can use as subagents after the Skill loads.
  • capabilities.toolIds: IDs of saved tools that your Agent can use after the Skill loads.
  • capabilities.inlineTools: Inline runtime tool definitions. Reference secrets only with {{secret:NAME}}.

Replace NAME with the name of the secret that the inline tool uses.

At runtime, Runtype resolves each capability reference after checking the executing caller’s permissions.

The API rejects manifests with mcpServers on import and save because their authentication fields can store literal credentials. Use flowIds, agentIds, toolIds, or inlineTools for Skill capabilities instead. Skills do not carry secrets of their own. Reference secrets only with {{ secret: NAME }}.

Create and bind a Skill

Create a Skill from the Skills page in the dashboard or with the Runtype API and SDK. A Skill belongs to your organization account or personal account. To create and bind a Skill through the API, follow these steps:

  1. Author the manifest. Write SKILL.md with YAML frontmatter and a Markdown body.
  2. Create and publish the Skill. Send a POST request to /v1/skills with publish: true and either a markdown string or frontmatter plus body.
  3. Bind the Skill to an Agent. Send a POST request to /v1/skills/bind with { agentId, skillId }. The skill:<slug> tool then appears in the Agent’s tool list.
  4. Optional: Mention the tool in the system prompt. Add skill:<slug> to the Agent’s system prompt when you want to tell the model that the tool is available.

The following request creates and publishes a Skill from a structured manifest:

cURL
$curl https://api.runtype.com/v1/skills \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "frontmatter": {
>      "name": "refund-protocol",
>      "description": "Process refunds when users ask."
>    },
>    "body": "Verify the order ID before issuing the refund.",
>    "publish": true
>  }'

Replace YOUR_API_KEY with a Runtype API key that has SKILLS:WRITE or SKILLS:* permission.

Use POST /v1/skills/import when you send a complete pasted SKILL.md document. Skills that you author through the dashboard or API do not enter a review queue. The Skills API uses SKILLS:READ for read operations and SKILLS:WRITE for write operations, including publishing, binding, and proposal review. SKILLS:* grants both permission sets.

How Skills load at runtime

On the first load of a Skill in a turn, Runtype returns the body as the tool result and emits an agent_skill_loaded event. View this event in the execution log.

If a Skill adds tools that the Agent does not already have, the load pauses for approval before those tools activate. A Skill with no capabilities, or one whose capabilities the Agent already has, loads without this approval.

Runtype activates newly bound capabilities on the following turn. To let the Agent use them, turn on Agent Loop and set Max Turns to 2 or higher. Runtype starts a follow-up turn when a Skill adds tools, so leave room for that turn in Max Turns. Knowledge-only Skills can load in one turn.

Runtype deduplicates repeat loads within a single turn. If the model calls the same skill:<slug> tool again in that turn, Runtype returns an alreadyLoaded result without the body or another capability activation. Runtype does not emit another agent_skill_loaded event for that repeat. The model can load the Skill again in a later turn and receive the full body.

Agent-proposed Skills

A running Agent can submit a Skill proposal with the propose_skill tool. This path is separate from dashboard and API authoring. The tool returns immediately, emits an agent_skill_proposed event, and does not pause the current run.

By default, Runtype places every proposal, including text-only proposals, in the review queue. A human must approve or reject the proposal before Runtype publishes it.

When the account’s auto-publish setting is enabled and the manifest uses trustLevel: org, Runtype publishes the proposal without review. This rule does not apply to imported or community trust levels. Runtype creates the Skill in the proposing user’s scope and binds it only to the proposing Agent. Runtype keeps the proposal as an audit record.

Approving a proposal publishes the Skill but does not bind it to an Agent. Bind it separately with POST /v1/skills/bind or from the Skills page.

Next steps

Continue with these guides: