> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Skills

> Rightbrain Skills are versioned, SKILL.md-shaped abilities agents activate for focused work, with declared executable dependencies.

A **Skill** is a reusable, versioned ability your [agents](/docs/concepts/agents) can activate for focused work. It bundles instructions, reference material, and assets into a named capability — and it declares, in a typed contract, exactly which executable dependencies it needs. When you attach a Skill to an agent, Rightbrain **auto-provisions** those prerequisites for you.

Skills are SKILL.md-shaped: an identity (when the skill should be used), a purpose (how it should behave), and supporting files. They're the unit for packaging know-how you want to reuse across many agents.

A Skill is **declarative**, which sets it apart from executable tools. A [Task](/docs/concepts/tasks) or an MCP tool is imperative — the agent invokes it and gets a result back. A Skill instead loads instructions and knowledge into the model's own context so it does the work itself. The difference is handing someone a calculator versus teaching them mathematics: a tool computes the answer for you, a Skill makes the model better at reaching it.

## When to use a Skill

Use a Skill when you have a repeatable piece of expertise — a procedure, a house style, a domain playbook — that more than one agent should share, and that may depend on external tools. Because a Skill carries its own tool requirements, attaching it is a one-step way to give an agent both the know-how and the wiring.

Use a [Task](/docs/concepts/tasks) instead when you need a single structured LLM call with a typed output. Use a [Skill](/docs/concepts/skills) when you need a versioned, reusable ability with instructions and files.

## How a Skill is structured

Skills are versioned like Tasks and agents. The Skill is a stable handle; its content lives in immutable **revisions**, with exactly one active per Skill.

* `slug` (kebab-case), `display_name`, `description`, `license`, `compatibility`.
* **Scope** — a Skill is either **global** (marketplace-wide, available to every project) or **project-scoped** (owned by one project). Global skills come from a catalog of sources.
* Each **revision** holds `instructions`, `reference_docs` (a map of path to content), `assets`, and metadata.

### The capabilities contract

The hero feature: each Skill revision carries a typed **capabilities contract** — a list of `dependencies`, each marked `required` and pointing at a specific tool it needs. A dependency selects one of:

* a **registered tool** (a platform built-in, by key),
* an **integration** (by integration type and tool name),
* an **MCP server** (by slug),
* an **MCP tool** (by slug and tool name).

This is how a Skill says, in effect, "to work I need Gmail's send-email tool and this MCP server." Listings surface computed flags (`has_capabilities`, `requires_prerequisites`) so you can see at a glance what a Skill will pull in.

### Auto-provisioning onto an agent

When you attach a Skill with capabilities to an [agent revision](/docs/concepts/agents), Rightbrain provisions the Skill's declared prerequisites onto that revision automatically. Those provisioned attachments are tagged with their origin (`provision_source`, plus the source skill, revision, and capability IDs) so you can tell auto-provisioned tools from ones you added by hand.

> **Note**
>
> Auto-provisioning wires the tool onto the revision. You still connect the credential — for an integration or MCP server, that means completing OAuth or supplying an API key. See [Connections](/docs/concepts/connections).

## Progressive disclosure and cost

A Skill doesn't dump its whole body into context up front. The agent discovers a skill cheaply, loads its instructions only when it decides to use it, and pulls in a specific reference file only if it needs the detail. That staging keeps the context footprint proportional to how far the model actually reaches in.

Every attached Skill contributes its discovery metadata. Activated instructions and requested reference files add more input tokens. Keep the Skill description precise, put the core procedure in its instructions, and move detailed material into focused reference files that can load independently.

Loaded Skill content contributes to the agent model's input tokens. Registered tools, Integrations, MCP servers, and MCP tools provisioned by its capabilities keep the runtime behavior of their own tool type. Use [context attribution](/docs/concepts/memory-and-context) to see what an activated Skill contributed to a run.

## Example: a Skill that needs Gmail

Suppose you build a **"Send weekly digest"** Skill. Its instructions explain how to assemble and format the digest; its capabilities contract declares one required dependency: the **Gmail** integration's send-email tool.

#### Attach the Skill to your agent

A single attach carries both the instructions and the declared tool requirements.

#### Rightbrain auto-provisions the tool

The Gmail send-email tool is wired onto the agent's revision, tagged as sourced from the Skill.

#### Authorize the connection

Complete OAuth on the Gmail [connection](/docs/concepts/connections) if it isn't already authorized.

#### Run it end to end

The agent assembles the digest and sends it — no manual integration wiring on your part.

## Minimal example

Create a project-scoped Skill, then attach it to an agent revision.

**`Create a skill`**

```bash title="Create a skill"
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/skill \
  -H "Authorization: Bearer $RB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "send-weekly-digest",
    "display_name": "Send weekly digest",
    "description": "Assembles and emails a weekly summary.",
    "instructions": "Assemble a concise weekly digest and send it via Gmail.",
    "capabilities": {
      "schema_version": "1.0.0",
      "dependencies": [
        {
          "id": "gmail-send",
          "type": "integration",
          "required": true,
          "selector": { "integration_type": "gmail", "tool_name": "send_email" }
        }
      ]
    }
  }'
```

**`List skills available to a project`**

```bash title="List skills available to a project"
curl https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/skill/available \
  -H "Authorization: Bearer $RB_TOKEN"
```

## Related

#### [Agents](/docs/concepts/agents)

Attach Skills to an agent revision.

#### [Connections](/docs/concepts/connections)

Integrations and MCP servers a Skill's capabilities pull in.

#### [Versioning & revisions](/docs/production/revisions)

How Skill revisions are pinned and activated.

#### [API Reference — Skills](/api-reference/api-reference/skills)

Full endpoint reference for skills.