Skills Protocol

Core Concepts

The Skills Protocol is built on four fundamental concepts that work together to enable LLM agents to discover and execute skills safely and efficiently.

Skill

A Skill is a versioned bundle containing:

  • skill.toml — machine-readable manifest (id, runtime, permissions, metadata)
  • SKILL.md — instructions & examples for the LLM
  • code/ — optional executable implementation
  • resources/ — optional supporting files (extra docs, schemas, etc.)

Skill Types

Skills come in two kinds:

  • Name
    Action skills
    Description

    Skills that have a runtime and can be executed. They include executable code and can perform actions like API calls, data processing, or file operations.

  • Name
    Instruction skills
    Description

    Skills that only provide context and instructions to the LLM. They have no runtime and cannot be executed, serving purely as documentation or guidance.

Example Skill Structure

salesforce.leads.sync/
  skill.toml           # Manifest with metadata and permissions
  SKILL.md            # LLM-readable instructions
  code/
    main.py           # Executable implementation
  resources/
    schema.json       # Supporting files

Blob

A Blob is an opaque handle (blob:<id>) to large data (text, binary, JSON). Blobs live in the runtime's storage and can be mounted into sandboxes.

Why Use Blobs?

Large documents, logs, CSVs, and other substantial data should be represented as blobs rather than inline JSON. This approach:

  • Reduces token usage — Large data doesn't pass through the LLM context
  • Improves performance — Skills operate on blobs without serialization overhead
  • Enables streaming — Blobs can be read partially or sampled
  • Supports binary data — Images, PDFs, and other non-text formats

Blob Operations

Creation

{
  "method": "create_blob",
  "params": {
    "content": "Large CSV data...",
    "kind": "text/csv"
  }
}

Returns: blob:abc123

Reading

{
  "method": "read_blob",
  "params": {
    "blob_id": "blob:abc123",
    "mode": "sample_head",
    "max_bytes": 2000
  }
}

Returns truncated preview

Run

A Run is a single ephemeral sandbox execution with a stable identifier and status tracking.

Run Triggers

Via execute_skill Run a skill's entrypoint with provided arguments

Via run_code Run LLM-written code that can import skills

Run Properties

Each run has:

  • Name
    run_id
    Type
    string
    Description

    Stable identifier for the run (e.g., run_9f2a)

  • Name
    status
    Type
    string
    Description

    Either "completed" or "failed"

  • Name
    summary
    Type
    string
    Description

    Short human-readable description of the result

  • Name
    output
    Type
    object
    Description

    Small JSON output (must be < 4KB). Large data goes in output_blobs

  • Name
    output_blobs
    Type
    array
    Description

    List of blob IDs created during execution

  • Name
    logs_preview
    Type
    string
    Description

    Truncated execution logs (typically < 2KB)

  • Name
    error
    Type
    object
    Description

    Error details if status is "failed"

Run Example

{
  "status": "completed",
  "run_id": "run_9f2a",
  "summary": "Synced 742 leads (5 failed).",
  "output": {
    "updated_count": 742,
    "failed_count": 5
  },
  "output_blobs": [
    "blob:sync-log-42",
    "blob:failed-rows-1"
  ],
  "logs_preview": "Connected to Salesforce...\nSynced 742 leads...\n"
}

Skills Runtime

A Skills Runtime is a server implementing the Skills Protocol specification. It provides the infrastructure for skill discovery, storage, and execution.

Runtime Responsibilities

Storage

  • Stores Skills and Blobs
  • Manages skill versions
  • Handles blob lifecycle

Execution

  • Creates sandboxed environments
  • Enforces resource limits
  • Manages permissions

API

  • Exposes JSON-RPC 2.0 endpoint
  • Provides LLM tool surface
  • Handles authentication

Runtime Features

The runtime provides:

  1. Skill Registry — Discover and retrieve skill metadata
  2. Execution Engine — Run skills in isolated sandboxes
  3. Blob Storage — Efficient handling of large data
  4. Permission System — Control network access and secrets
  5. Resource Limits — Enforce CPU, memory, and timeout constraints

Architecture

┌─────────────────────────────────────────┐
│          LLM Agent                       │
│  (Uses 8 protocol tools)                 │
└──────────────┬──────────────────────────┘
               │ JSON-RPC 2.0 over HTTP
┌──────────────▼──────────────────────────┐
│       Skills Runtime                     │
│  ┌────────────┬──────────┬────────────┐ │
│  │   Skills   │  Blobs   │  Sandbox   │ │
│  │  Registry  │ Storage  │   Engine   │ │
│  └────────────┴──────────┴────────────┘ │
└─────────────────────────────────────────┘

Next Steps

Now that you understand the core concepts, learn about the LLM tool interface:

Explore LLM Tools

Was this page helpful?