Tool Schemas

Complete JSON Schema definitions for all 8 LLM tools. Use these schemas to configure function calling in your LLM integration (OpenAI, Anthropic, etc.).

Overview

The Skills Protocol exposes exactly 8 tools via JSON-RPC 2.0. Each tool definition below includes:

Parameters — JSON Schema for function arguments
Response — Example response structure
Implementation notes — Special considerations

All tools use JSON-RPC 2.0 over HTTP at a single endpoint (typically /rpc).

Discovery tools

list_skills

{
  "name": "list_skills",
  "description": "Enumerate available skills, optionally filtering by namespace. Results are deterministically sorted.",
  "parameters": {
    "type": "object",
    "properties": {
      "namespace": {
        "type": "string",
        "description": "Optional namespace to filter skills (e.g., 'salesforce')"
      },
      "detail": {
        "type": "string",
        "enum": ["names", "summary"],
        "default": "names",
        "description": "Level of detail to return"
      },
      "limit": {
        "type": "integer",
        "default": 50,
        "description": "Maximum number of results"
      },
      "cursor": {
        "type": "string",
        "description": "Pagination cursor from previous response"
      }
    }
  }
}

describe_skill

{
  "name": "describe_skill",
  "description": "Retrieve a skill's manifest and documentation frontmatter.",
  "parameters": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Skill name (e.g., 'salesforce.leads.sync')"
      },
      "version": {
        "type": "string",
        "description": "Skill version (omit for latest)"
      },
      "detail": {
        "type": "string",
        "enum": ["manifest", "summary", "full"],
        "default": "summary",
        "description": "Level of detail to return"
      }
    },
    "required": ["name"]
  }
}

read_skill_file

{
  "name": "read_skill_file",
  "description": "Read any file in a skill's directory (e.g., SKILL.md, extra docs, schemas).",
  "parameters": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Skill name"
      },
      "version": {
        "type": "string",
        "description": "Skill version (omit for latest)"
      },
      "path": {
        "type": "string",
        "description": "Path to file within skill directory (e.g., 'SKILL.md')"
      }
    },
    "required": ["name", "path"]
  }
}

Execution tools

execute_skill

{
  "name": "execute_skill",
  "description": "Execute a skill's entrypoint in an ephemeral sandbox.",
  "parameters": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Skill name"
      },
      "version": {
        "type": "string",
        "description": "Skill version (omit for latest)"
      },
      "args": {
        "type": "object",
        "description": "JSON-serializable arguments to pass to the skill"
      },
      "input_blobs": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Blob IDs to mount in the sandbox"
      },
      "timeout_ms": {
        "type": "integer",
        "description": "Execution timeout in milliseconds"
      }
    },
    "required": ["name"]
  }
}

run_code

{
  "name": "run_code",
  "description": "Execute LLM-written code in a sandbox with specified skills and blobs mounted.",
  "parameters": {
    "type": "object",
    "properties": {
      "language": {
        "type": "string",
        "enum": ["python"],
        "description": "Programming language (MVP: python only)"
      },
      "code": {
        "type": "string",
        "description": "Source code to execute"
      },
      "entrypoint": {
        "type": "string",
        "default": "main",
        "description": "Function name to call"
      },
      "args": {
        "type": "object",
        "description": "Arguments to pass to entrypoint function"
      },
      "mount_skills": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Skill names to mount in sandbox"
      },
      "input_blobs": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Blob IDs to mount in sandbox"
      },
      "limits": {
        "type": "object",
        "properties": {
          "timeout_ms": {"type": "integer"}
        },
        "description": "Execution limits"
      }
    },
    "required": ["language", "code"]
  }
}

Blob tools

create_blob

{
  "name": "create_blob",
  "description": "Store large content as a blob and return its ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "content": {
        "type": "string",
        "description": "Content to store"
      },
      "kind": {
        "type": "string",
        "description": "MIME type (e.g., 'text/plain', 'application/json')"
      }
    },
    "required": ["content", "kind"]
  }
}

read_blob

{
  "name": "read_blob",
  "description": "Retrieve a preview of blob content. Full reads discouraged for large blobs.",
  "parameters": {
    "type": "object",
    "properties": {
      "blob_id": {
        "type": "string",
        "description": "Blob identifier"
      },
      "mode": {
        "type": "string",
        "enum": ["sample_head", "sample_tail", "full"],
        "default": "sample_head",
        "description": "How to sample the blob"
      },
      "max_bytes": {
        "type": "integer",
        "default": 2000,
        "description": "Maximum bytes to return"
      }
    },
    "required": ["blob_id"]
  }
}

Bootstrap tool

load_skills_protocol_guide

{
  "name": "load_skills_protocol_guide",
  "description": "Load the Skills Protocol Guide to learn how to use these tools. Call this first if you haven't read the guide yet.",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}

Using These Schemas

OpenAI Function Calling

Adapt these schemas to OpenAI's function calling format:

{
  "type": "function",
  "function": {
    "name": "execute_skill",
    "description": "Execute a skill's entrypoint in an ephemeral sandbox.",
    "parameters": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "args": {"type": "object"},
        "input_blobs": {"type": "array"}
      },
      "required": ["name"]
    }
  }
}

Anthropic Tool Use

Adapt for Anthropic's tool_use format in a similar way, using the parameter definitions above.

Next Steps

Python Client Example Tool Interface Overview