Skip to content

agent-skills-list.mdx

Latest commit

 

History

History
135 lines (102 loc) · 6.11 KB

agent-skills-list.mdx

File metadata and controls

135 lines (102 loc) · 6.11 KB
title
Agent Skills List

Elevator pitch

Add a mechanism for agents to advertise available Agent Skills to clients. Skills are reusable, composable capabilities that agents can expose, allowing clients to discover what an agent can do beyond basic prompting. This RFD proposes:

  1. A canonical AvailableSkill type describing skill schema aligned with the Agent Skills Specification
  2. An AvailableSkillsUpdate session notification for streaming skill availability to clients

Status quo

Currently, the ACP protocol provides AvailableCommand and AvailableCommandsUpdate for agents to advertise executable commands. However, commands are designed for user-invoked actions within a session (e.g., /create_plan, /research_codebase), not for describing higher-level agent capabilities that:

  • Have licensing or compatibility requirements
  • Need pre-approved tool access for security
  • Represent modular, composable functionality
  • Require rich metadata for discovery and filtering

This creates several problems:

  • Limited capability discovery - Clients cannot understand what specialized skills an agent offers
  • No licensing visibility - Users cannot see license terms for specific agent capabilities
  • Missing compatibility info - No way to indicate if a skill requires specific environments, network access, or system packages
  • Security blind spots - No pre-declaration of tools a skill might use, making trust decisions difficult
  • Poor extensibility - Commands lack a metadata mechanism for custom integrations

What we propose to do about it

Add a new AvailableSkill type and AvailableSkillsUpdate notification following the existing pattern for AvailableCommand and AvailableCommandsUpdate. The schema aligns with the Agent Skills Specification.

AvailableSkill Schema

Field Required Constraints
name Yes Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. No consecutive hyphens.
description Yes Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
license No License name or reference to a bundled license file (e.g., MIT, Apache-2.0, ./licenses/my-license.txt).
compatibility No Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadata No Arbitrary string key-value mapping for additional properties.
allowedTools No Array of pre-approved tools the skill may use (Experimental). 
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Session Notification

The AvailableSkillsUpdate notification allows agents to stream skill availability during a session:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123",
    "sessionUpdate": "available_skills_update",
    "availableSkills": [
      {
        "name": "code-review",
        "description": "Performs automated code review on staged changes..."
      },
      {
        "name": "test-generator",
        "description": "Generates unit tests for the specified code...",
        "allowedTools": ["Bash", "Read", "Write"]
      }
    ]
  }
}

Shiny future

Once this feature exists:

  1. Rich skill discovery - Clients can browse available skills with detailed metadata, enabling better agent selection and capability understanding
  2. License compliance - Organizations can filter or highlight skills based on licensing requirements
  3. Environment matching - Clients can warn users when skills may not work in their environment (e.g., missing git, no network access)
  4. Security pre-approval - Users can review and pre-approve tool access for skills, reducing permission fatigue
  5. Extensible integrations - The metadata field enables custom integrations without protocol changes
  6. Skill marketplaces - Future tooling could aggregate skills across agents for discovery and comparison

Clients could implement:

  • Skill browser/selector UI
  • Automatic environment compatibility checking
  • License filtering for enterprise compliance
  • Skill-based agent recommendations

Implementation details and plan

Phase 1: Schema Updates

  1. Add AvailableSkill type to schema:

    • name: Required string with validation pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, max 64 chars
    • description: Required string, max 1024 chars, minLength 1
    • license: Optional string
    • compatibility: Optional string, max 500 chars
    • allowedTools: Optional array of strings
    • _meta: Standard extensibility field, we can put metadata from the skills spec

  2. Add AvailableSkillsUpdate type:

    • availableSkills: Required array of AvailableSkill
    • _meta: Standard extensibility field

  3. Update SessionUpdate enum to include available_skills_update variant

Phase 2: SDK Updates

  1. Update Rust SDK (src/):
    • Add AvailableSkill struct with serde validation
    • Add AvailableSkillsUpdate struct
    • Update SessionUpdate enum

Phase 3: Documentation

  1. Update protocol documentation:

Revision history

  • 2025-01-10: Initial draft proposal