diff --git a/docs/rfds/agent-skills-list.mdx b/docs/rfds/agent-skills-list.mdx new file mode 100644 index 0000000..37e77fe --- /dev/null +++ b/docs/rfds/agent-skills-list.mdx @@ -0,0 +1,135 @@ +--- +title: "Agent Skills List" +--- + +- Author(s): [@ignatov](https://github.com/ignatov) + +## Elevator pitch + +Add a mechanism for agents to advertise available [Agent Skills](https://agentskills.io/specification) 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](https://agentskills.io/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](https://agentskills.io/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). | + +```md +--- +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: + +```json +{ + "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 + +4. **Update Rust SDK** (`src/`): + - Add `AvailableSkill` struct with serde validation + - Add `AvailableSkillsUpdate` struct + - Update `SessionUpdate` enum + +### Phase 3: Documentation + +5. **Update protocol documentation**: + - Document the new types + - Provide usage examples + - Link to [Agent Skills Specification](https://agentskills.io/specification) for skill authoring guidance + +## Revision history + +- **2025-01-10**: Initial draft proposal