Discovery Methods

The Skills Protocol provides three methods for discovering and inspecting skills. These methods enable LLM agents to explore available skills, understand their capabilities, and read their documentation.

POST

list_skills

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

Request parameters

Name
namespace
Type
string
Description
Optional namespace to filter skills (e.g., 'salesforce', 'gdrive')
Name
detail
Type
string
Description
Level of detail to return:
- "names" — Just name and version
- "summary" — Include description and metadata
Default: "names"
Name
limit
Type
integer
Description
Maximum number of results to return. Default: 50
Name
cursor
Type
string
Description
Pagination cursor from a previous response

Response

Name
skills
Type
array
Description
Array of skill objects. Each skill contains:
- name — Skill identifier
- version — Skill version
- description — Brief description (if detail="summary")
- namespace — Grouping namespace (if detail="summary")
- kind — "action" or "instruction" (if detail="summary")
Name
next_cursor
Type
string | null
Description
Opaque cursor for next page, or null if no more results

Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "list_skills",
  "params": {
    "namespace": "salesforce",
    "detail": "summary",
    "limit": 50
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "skills": [
      {
        "name": "salesforce.leads.sync",
        "version": "0.1.0",
        "description": "Sync leads from a sheet blob into Salesforce.",
        "namespace": "salesforce",
        "kind": "action"
      },
      {
        "name": "salesforce.contacts.export",
        "version": "0.2.1",
        "description": "Export Salesforce contacts to CSV.",
        "namespace": "salesforce",
        "kind": "action"
      }
    ],
    "next_cursor": null
  }
}

Important: list_skills returns results in deterministic sort order. It does NOT perform semantic search or relevance ranking.

POST

describe_skill

Retrieve a skill's manifest and optional documentation frontmatter. This method provides structured metadata about a skill without reading its full documentation.

Request parameters

Name
name
Type
string
Required
required
Description
Skill name (e.g., 'salesforce.leads.sync')
Name
version
Type
string
Description
Specific skill version. If omitted, returns the latest version.
Name
detail
Type
string
Description
Level of detail to return:
- "manifest" — Only the skill.toml manifest
- "summary" — Manifest + SKILL.md frontmatter
- "full" — Manifest + frontmatter + full SKILL.md content
Default: "summary"

Response

Name
skill
Type
object
Description
Object containing:
- manifest — Parsed skill.toml as JSON
- skill_md_frontmatter — Parsed YAML frontmatter from SKILL.md
- skill_md_content — Full SKILL.md content (only if detail="full")

Request

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "describe_skill",
  "params": {
    "name": "salesforce.leads.sync",
    "detail": "summary"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "skill": {
      "manifest": {
        "name": "salesforce.leads.sync",
        "version": "0.1.0",
        "description": "Sync leads from a sheet blob into Salesforce.",
        "kind": "action",
        "namespace": "salesforce",
        "tags": ["crm", "leads", "sync"],
        "runtime": {
          "language": "python",
          "entrypoint": "code/main.py",
          "export": "main"
        },
        "inputs": {
          "sheet_blob": {
            "type": "blob",
            "description": "Blob id of the source sheet"
          },
          "env": {
            "type": "string",
            "description": "Which Salesforce env"
          }
        },
        "permissions": {
          "network": ["https://*.salesforce.com"],
          "secrets": ["SALESFORCE_API_KEY"]
        }
      },
      "skill_md_frontmatter": {
        "name": "Salesforce Lead Sync",
        "short_description": "Sync leads from a sheet blob into Salesforce.",
        "tags": ["crm", "leads", "sync"]
      }
    }
  }
}

For large SKILL.md files, prefer using describe_skill with detail="summary" and then read_skill_file to get the full documentation separately.

POST

read_skill_file

Read any file in a skill's directory. This enables access to full documentation, schemas, examples, and other supporting files.

Request parameters

Name
name
Type
string
Required
required
Description
Skill name
Name
version
Type
string
Description
Skill version. If omitted, uses the latest version.
Name
path
Type
string
Required
required
Description
Path to file within the skill directory. Common paths:
- "SKILL.md" — Main documentation
- "resources/examples.md" — Example usage
- "resources/schema.json" — Input/output schemas

Response

Name
content
Type
string
Description
The file's content as a string

Request

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

Response

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "content": "---\nname: Salesforce Lead Sync\nshort_description: Sync leads from a sheet blob into Salesforce.\ntags: [crm, leads, sync]\n---\n\n# Salesforce Lead Sync\n\nThis skill syncs lead data from a CSV blob into Salesforce...\n\n## Usage\n\nCall this skill with:\n- `sheet_blob`: Blob ID containing CSV data\n- `env`: Target environment ('dev', 'staging', 'prod')\n\n## Example\n\n```python\nresult = execute_skill(\n    name='salesforce.leads.sync',\n    args={'sheet_blob': 'blob:abc', 'env': 'prod'}\n)\n```"
  }
}

Security

Runtimes MUST:

Restrict path to the skill's directory
Reject paths attempting to escape (e.g., ../, absolute paths)
Return an error for non-existent files

Common Patterns

Discovery workflow

A typical discovery workflow:

List skills — Use list_skills with a namespace filter to find relevant skills
Get summary — Use describe_skill with detail="summary" to understand the skill's purpose and inputs
Read documentation — Use read_skill_file to get full usage instructions from SKILL.md
Read resources — Optionally use read_skill_file to access schemas, examples, or other supporting files

Example: Full discovery

# 1. Find Salesforce skills
skills = call_rpc("list_skills", {
    "namespace": "salesforce",
    "detail": "summary"
})

# 2. Pick one and get details
info = call_rpc("describe_skill", {
    "name": "salesforce.leads.sync",
    "detail": "summary"
})

# 3. Read full documentation
docs = call_rpc("read_skill_file", {
    "name": "salesforce.leads.sync",
    "path": "SKILL.md"
})

# 4. Check for schema files
schema = call_rpc("read_skill_file", {
    "name": "salesforce.leads.sync",
    "path": "resources/schema.json"
})

Next Steps

Execution Methods Blob Methods

Learn about:

Execution Methods — How to run skills and custom code
Blob Methods — Managing large data
Tool Interface — Overview of all 8 tools