Skills Protocol

LLM Tool Interface

The Skills Protocol exposes exactly 8 tools to LLM agents. These meta-tools enable agents to work with an extensible ecosystem of skills.

Overview

Skills are not exposed as native LLM tools. Instead, the protocol provides a small set of meta-tools that let agents discover, inspect, and execute any skill.

Discovery Tools

  • list_skills — Enumerate available skills
  • describe_skill — Get skill manifest & docs
  • read_skill_file — Read any skill file

Execution Tools

  • execute_skill — Run a skill's entrypoint
  • run_code — Execute LLM-written code

Blob Tools

  • create_blob — Store large content
  • read_blob — Retrieve blob previews

Bootstrap Tool

  • load_skills_protocol_guide — Load protocol guide

All tools use JSON-RPC 2.0 over HTTP. See JSON-RPC Conventions for error handling details.

Discovery tools

list_skills

Enumerate available skills, optionally filtering by namespace. Results are deterministically sorted.

Parameters

  • Name
    namespace
    Type
    string
    Description

    Optional namespace to filter skills (e.g., 'salesforce')

  • Name
    detail
    Type
    string
    Description

    Level of detail: "names" or "summary" (default: "names")

  • Name
    limit
    Type
    integer
    Description

    Maximum number of results (default: 50)

  • Name
    cursor
    Type
    string
    Description

    Pagination cursor from previous response

Example

{
  "method": "list_skills",
  "params": {
    "namespace": "salesforce",
    "detail": "summary",
    "limit": 50
  }
}

Response Returns an array of skills with basic metadata:

  • name — Skill identifier
  • version — Skill version
  • description — Brief description
  • namespace — Grouping namespace
  • kind — "action" or "instruction"
{
  "skills": [
    {
      "name": "salesforce.leads.sync",
      "version": "0.1.0",
      "description": "Sync leads from a sheet blob",
      "namespace": "salesforce",
      "kind": "action"
    }
  ],
  "next_cursor": null
}

describe_skill

Retrieve a skill's manifest and documentation frontmatter.

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    Skill name (e.g., 'salesforce.leads.sync')

  • Name
    version
    Type
    string
    Description

    Skill version (omit for latest)

  • Name
    detail
    Type
    string
    Description

    Detail level: "manifest", "summary", or "full" (default: "summary")

Example

{
  "method": "describe_skill",
  "params": {
    "name": "salesforce.leads.sync",
    "detail": "summary"
  }
}

read_skill_file

Read any file in a skill's directory (e.g., SKILL.md, extra docs, schemas).

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    Skill name

  • Name
    version
    Type
    string
    Description

    Skill version (omit for latest)

  • Name
    path
    Type
    string
    Required
    required
    Description

    Path to file within skill directory (e.g., 'SKILL.md')

Example

{
  "method": "read_skill_file",
  "params": {
    "name": "salesforce.leads.sync",
    "path": "SKILL.md"
  }
}

The runtime restricts path to the skill's directory and rejects attempts to escape (e.g., ../).

Execution tools

execute_skill

Run a skill's entrypoint in an ephemeral sandbox.

Parameters

  • Name
    name
    Type
    string
    Required
    required
    Description

    Skill name

  • Name
    args
    Type
    object
    Description

    JSON-serializable arguments to pass to the skill

  • Name
    version
    Type
    string
    Description

    Skill version (omit for latest)

  • Name
    input_blobs
    Type
    array
    Description

    Blob IDs to mount in the sandbox

  • Name
    timeout_ms
    Type
    integer
    Description

    Execution timeout in milliseconds

Example

{
  "method": "execute_skill",
  "params": {
    "name": "salesforce.leads.sync",
    "args": {
      "sheet_blob": "blob:sheet-123",
      "env": "prod"
    },
    "input_blobs": ["blob:sheet-123"]
  }
}

Response

  • Name
    status
    Type
    string
    Description

    "completed" or "failed"

  • Name
    run_id
    Type
    string
    Description

    Stable identifier for this run

  • Name
    summary
    Type
    string
    Description

    Human-readable result description

  • Name
    output
    Type
    object
    Description

    Small JSON output (max 4KB)

  • Name
    output_blobs
    Type
    array
    Description

    Blob IDs created during execution

  • Name
    logs_preview
    Type
    string
    Description

    Truncated execution logs (max 2KB)

{
  "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"
  ],
  "logs_preview": "Connected...\nSynced 742..."
}

run_code

Execute LLM-written code in a sandbox with specified skills and blobs mounted.

Parameters

  • Name
    language
    Type
    string
    Required
    required
    Description

    Programming language (MVP: "python" only)

  • Name
    code
    Type
    string
    Required
    required
    Description

    Source code to execute

  • Name
    entrypoint
    Type
    string
    Description

    Function name to call (default: "main")

  • Name
    args
    Type
    object
    Description

    Arguments to pass to entrypoint function

  • Name
    mount_skills
    Type
    array
    Description

    Skill names to mount in sandbox

  • Name
    input_blobs
    Type
    array
    Description

    Blob IDs to mount in sandbox

  • Name
    limits
    Type
    object
    Description

    Execution limits (e.g., timeout_ms)

Example

{
  "method": "run_code",
  "params": {
    "language": "python",
    "code": "from skills.salesforce...",
    "entrypoint": "main",
    "args": {"sheet_blob": "blob:123"},
    "mount_skills": [
      "salesforce.leads.sync"
    ],
    "input_blobs": ["blob:123"]
  }
}

The runtime provides a runtime package with helpers: blobs.read_text(), blobs.write_text(), log.info(), etc.

Blob tools

create_blob

Store large content as a blob and return its ID.

Parameters

  • Name
    content
    Type
    string
    Required
    required
    Description

    Content to store

  • Name
    kind
    Type
    string
    Required
    required
    Description

    MIME type (e.g., 'text/plain', 'application/json')

Example

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

Response

{
  "blob_id": "blob:transcript-abc123",
  "size_bytes": 200000
}

read_blob

Retrieve a preview of blob content. Full reads are discouraged for large blobs.

Parameters

  • Name
    blob_id
    Type
    string
    Required
    required
    Description

    Blob identifier

  • Name
    mode
    Type
    string
    Description

    Sampling mode: "sample_head", "sample_tail", or "full" (default: "sample_head")

  • Name
    max_bytes
    Type
    integer
    Description

    Maximum bytes to return (default: 2000)

Example

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

Response

{
  "content": "Discussed Q4 goals...",
  "truncated": true,
  "kind": "text/plain"
}

Bootstrap tool

load_skills_protocol_guide

Load the canonical Skills Protocol Guide to learn how to use these tools. Call this first if you haven't read the guide yet.

Parameters None. This method takes no parameters.

Example

{
  "method": "load_skills_protocol_guide",
  "params": {}
}

Response

{
  "content": "# Skills Protocol Overview\n\nAvailable tools:\n..."
}

This method returns the SKILL.md content of the canonical skills.protocol.guide skill, which provides instructions on the protocol workflow.

Next Steps

View Tool SchemasPython Client Example

Learn more about:

Was this page helpful?