Skills

A Skill is a reusable, versioned ability your agents call on to complete focused work. It bundles instructions, reference material, and assets into a named capability — and it declares, in a typed contract, exactly which tools it needs to run. 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 the other things an agent calls. A Task 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 instead when you need a single structured LLM call with a typed output. Use a Skill 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, 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.

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.

The effect is measurable. Running the same agent three ways against one Skill:

Cost scales with what’s loaded, not with what’s attached. Ten skills sitting on an agent add only their short descriptions to context — on the order of 500–1,000 tokens total — until one is actually used.

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.

Minimal example

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

$
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" }
>
        }
>
      ]
>
    }
>
  }'

Related