From 7bb919fd3fb00640813b2ae4b2f3e34aaecdff1b Mon Sep 17 00:00:00 2001 From: Tim Visher <194828183+timvisher-dd@users.noreply.github.com> Date: Sat, 14 Feb 2026 15:53:34 -0500 Subject: [PATCH 1/7] Add draft Skills RFD --- docs/rfds/skills.mdx | 99 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/rfds/skills.mdx diff --git a/docs/rfds/skills.mdx b/docs/rfds/skills.mdx new file mode 100644 index 00000000..1597b33c --- /dev/null +++ b/docs/rfds/skills.mdx @@ -0,0 +1,99 @@ +--- +title: "Skills Discovery and Delivery" +--- + +- Author(s): [@timvisher](https://github.com/timvisher) + +## Elevator pitch + +Define first-class **Skills** in ACP so agents, clients, and proxies can discover and load skill metadata and content in a consistent way. Align with the open agent skills standard (SKILL.md + references/scripts/assets) while keeping the ACP surface area small and transport-agnostic (direct ACP or MCP resources). + +## Status quo + +Skills exist today as **tool-specific filesystem conventions**: + +- Each client defines its own discovery paths and activation heuristics. +- ACP only mentions skills indirectly in the proxy-chains RFD; there is no protocol-level contract for listing or fetching skills. +- Proxies can inject instructions, but there is no standardized metadata, no cross-client interoperability, and no way for an agent to ask, “what skills are available?” + +This leads to: + +- Fragmented discovery and inconsistent activation. +- Reduced portability of skills across clients. +- Difficulty for proxies or agents to expose or request skills programmatically. + +## What we propose to do about it + +Introduce an **optional Skills capability** in ACP that standardizes discovery and retrieval while remaining compatible with existing skill packaging. + +At a high level: + +1. **Skill metadata contract** + - A `SkillDescriptor` includes required fields compatible with the open standard (name + description) plus ACP metadata: + - `name`: string (unique key) + - `description`: string + - `version?`: string + - `source?`: enum (agent, client, proxy, external) + - `uri?`: string (content location, e.g., ACP or MCP resource URI) + - `updatedAt?`: string (ISO 8601) + - `checksum?`: string (optional integrity) + +2. **Discovery and retrieval** + - Add a `skills/list` request/response returning `SkillDescriptor[]`. + - Add a `skills/get` request/response that returns the **SKILL.md** content (and optionally reference/script manifests). + - Agents can request skill content lazily. + +3. **Transport options** + - If MCP-over-ACP is available, skill content may be surfaced as MCP resources and `skills/get` can return resource URIs. + - Otherwise, `skills/get` can return inline SKILL.md content and optional manifests. + +4. **Compatibility with the open standard** + - ACP does not re-define file layout; it adopts the SKILL.md frontmatter as the canonical metadata source. + - References/scripts/assets remain optional and discoverable via the `skills/get` response or MCP resources. + +This keeps ACP small while giving clients and agents a consistent, interoperable skills surface. + +## Shiny future + +- Agents can always ask “what skills are available?” and load details only when needed. +- Proxies can inject or augment skills in a standard way. +- Skills move between clients without repackaging or bespoke integrations. +- The ecosystem converges on a shared contract without losing flexibility in storage or transport. + +## Implementation details and plan + +> Optional for initial draft; fill in after discussion. + +A likely phased plan: + +1. Define `SkillDescriptor` and the `skills/list` + `skills/get` methods in the spec and schemas. +2. Update proxy guidance and MCP-over-ACP docs to describe skill resource mapping. +3. Add SDK support (Rust and TypeScript) and generator updates. +4. Update docs and examples to show skill discovery and retrieval. + +## Frequently asked questions + +## Why not rely only on MCP resources? + +MCP is a transport mechanism, not a semantic contract for “skills.” ACP needs a small skills contract so agents and clients can enumerate and request skills predictably, whether or not MCP is available. + +## Does this replace filesystem skills? + +No. Filesystem layout remains a local implementation detail. ACP simply standardizes how skills are exposed over the protocol. + +## How large can skills be? + +Large skills should be fetched lazily. `skills/get` can return a manifest and/or MCP resource URIs so that clients fetch only what’s needed. + +## Who owns skill sources? + +Skills can be provided by the client, agent, or proxy. The `source` field indicates provenance without enforcing policy. + +### What alternative approaches did you consider, and why did you settle on this one? + +- **Do nothing**: keeps interoperability fragmented and pushes burden onto every client. +- **Proxy-only guidance**: too indirect and does not define an ACP contract for skills. + +The proposed approach is minimal while enabling cross-client interoperability. + +## Revision history From f058866636c9f42ce64771c7b0174c9cd01ccddb Mon Sep 17 00:00:00 2001 From: Tim Visher <194828183+timvisher-dd@users.noreply.github.com> Date: Sat, 14 Feb 2026 15:56:54 -0500 Subject: [PATCH 2/7] Add Codex as skills RFD author --- docs/rfds/skills.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfds/skills.mdx b/docs/rfds/skills.mdx index 1597b33c..3b154ba1 100644 --- a/docs/rfds/skills.mdx +++ b/docs/rfds/skills.mdx @@ -2,7 +2,7 @@ title: "Skills Discovery and Delivery" --- -- Author(s): [@timvisher](https://github.com/timvisher) +- Author(s): [@timvisher-dd](https://github.com/timvisher-dd), Codex ## Elevator pitch From 5d48ed1a73fcf408cc4f613694655550d4257a7b Mon Sep 17 00:00:00 2001 From: Tim Visher <194828183+timvisher-dd@users.noreply.github.com> Date: Sat, 14 Feb 2026 16:07:01 -0500 Subject: [PATCH 3/7] Add skills UI hooks to RFD --- docs/rfds/skills.mdx | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/rfds/skills.mdx b/docs/rfds/skills.mdx index 3b154ba1..a5245fd8 100644 --- a/docs/rfds/skills.mdx +++ b/docs/rfds/skills.mdx @@ -47,7 +47,12 @@ At a high level: - If MCP-over-ACP is available, skill content may be surfaced as MCP resources and `skills/get` can return resource URIs. - Otherwise, `skills/get` can return inline SKILL.md content and optional manifests. -4. **Compatibility with the open standard** +4. **Client UX hooks** + - Recommend a `/skills` slash command via `available_commands_update` when the Skills capability is present. + - Clients may treat `$` as a UI affordance to open a skills picker backed by `skills/list`. + - `$` is not a protocol message; it is a client-side convention that maps to skills discovery. + +5. **Compatibility with the open standard** - ACP does not re-define file layout; it adopts the SKILL.md frontmatter as the canonical metadata source. - References/scripts/assets remain optional and discoverable via the `skills/get` response or MCP resources. @@ -57,6 +62,7 @@ This keeps ACP small while giving clients and agents a consistent, interoperable - Agents can always ask “what skills are available?” and load details only when needed. - Proxies can inject or augment skills in a standard way. +- Users can type `$` to open a skills picker (client UX) or run `/skills` to list available skills. - Skills move between clients without repackaging or bespoke integrations. - The ecosystem converges on a shared contract without losing flexibility in storage or transport. @@ -69,7 +75,7 @@ A likely phased plan: 1. Define `SkillDescriptor` and the `skills/list` + `skills/get` methods in the spec and schemas. 2. Update proxy guidance and MCP-over-ACP docs to describe skill resource mapping. 3. Add SDK support (Rust and TypeScript) and generator updates. -4. Update docs and examples to show skill discovery and retrieval. +4. Update docs and examples to show skill discovery and retrieval, including `/skills` and `$` UX guidance. ## Frequently asked questions @@ -89,6 +95,10 @@ Large skills should be fetched lazily. `skills/get` can return a manifest and/or Skills can be provided by the client, agent, or proxy. The `source` field indicates provenance without enforcing policy. +## How does this relate to slash commands and `$` lookup? + +`/skills` should be a normal slash command advertised via `available_commands_update` when the Skills capability is present. `$` is a client-side UX affordance that opens a skills picker backed by `skills/list`; it does not introduce a new ACP message. + ### What alternative approaches did you consider, and why did you settle on this one? - **Do nothing**: keeps interoperability fragmented and pushes burden onto every client. From e04f117acf110e2b9b9706fecd0269d514f8b3f7 Mon Sep 17 00:00:00 2001 From: Tim Visher <194828183+timvisher-dd@users.noreply.github.com> Date: Sat, 14 Feb 2026 16:43:41 -0500 Subject: [PATCH 4/7] Clarify skills RFD scope and non-goals --- docs/rfds/skills.mdx | 57 ++++++++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/docs/rfds/skills.mdx b/docs/rfds/skills.mdx index a5245fd8..4d3435e2 100644 --- a/docs/rfds/skills.mdx +++ b/docs/rfds/skills.mdx @@ -6,15 +6,16 @@ title: "Skills Discovery and Delivery" ## Elevator pitch -Define first-class **Skills** in ACP so agents, clients, and proxies can discover and load skill metadata and content in a consistent way. Align with the open agent skills standard (SKILL.md + references/scripts/assets) while keeping the ACP surface area small and transport-agnostic (direct ACP or MCP resources). +Define first-class **Skills** discovery in ACP so agents and clients can enumerate skills consistently and power `/skills` and `$` UX. Align with [the open agent skills standard](https://agentskills.io/) (SKILL.md + references/scripts/assets) while keeping the ACP surface area small. ## Status quo -Skills exist today as **tool-specific filesystem conventions**: +Skills exist today as **tool-specific filesystem conventions** that are not directly exposed via ACP at all: - Each client defines its own discovery paths and activation heuristics. - ACP only mentions skills indirectly in the proxy-chains RFD; there is no protocol-level contract for listing or fetching skills. - Proxies can inject instructions, but there is no standardized metadata, no cross-client interoperability, and no way for an agent to ask, “what skills are available?” +- Users have to know what skills are available by heart rather than using the standard `$`/`/skills` discovery mechanisms. This leads to: @@ -24,7 +25,7 @@ This leads to: ## What we propose to do about it -Introduce an **optional Skills capability** in ACP that standardizes discovery and retrieval while remaining compatible with existing skill packaging. +Introduce an **optional Skills capability** in ACP that standardizes discovery while remaining compatible with existing skill packaging. At a high level: @@ -33,36 +34,34 @@ At a high level: - `name`: string (unique key) - `description`: string - `version?`: string - - `source?`: enum (agent, client, proxy, external) - - `uri?`: string (content location, e.g., ACP or MCP resource URI) - `updatedAt?`: string (ISO 8601) - `checksum?`: string (optional integrity) -2. **Discovery and retrieval** +2. **Discovery** - Add a `skills/list` request/response returning `SkillDescriptor[]`. - - Add a `skills/get` request/response that returns the **SKILL.md** content (and optionally reference/script manifests). - - Agents can request skill content lazily. + - This is sufficient for `/skills` and `$` pickers without requiring any skill content transfer. -3. **Transport options** - - If MCP-over-ACP is available, skill content may be surfaced as MCP resources and `skills/get` can return resource URIs. - - Otherwise, `skills/get` can return inline SKILL.md content and optional manifests. - -4. **Client UX hooks** +3. **Client UX hooks** - Recommend a `/skills` slash command via `available_commands_update` when the Skills capability is present. - Clients may treat `$` as a UI affordance to open a skills picker backed by `skills/list`. - - `$` is not a protocol message; it is a client-side convention that maps to skills discovery. + - `/` and `$` are client-side conventions; ACP only defines the discovery data and the `available_commands_update` signal. -5. **Compatibility with the open standard** +4. **Compatibility with the open standard** - ACP does not re-define file layout; it adopts the SKILL.md frontmatter as the canonical metadata source. - - References/scripts/assets remain optional and discoverable via the `skills/get` response or MCP resources. + - ACP does not define installation or execution. It only lets clients discover what the agent already exposes. This keeps ACP small while giving clients and agents a consistent, interoperable skills surface. +## Non-goals + +- Define how skills are installed, updated, or executed. +- Allow clients or proxies to inject or override agent skills. +- Standardize filesystem paths or activation heuristics. + ## Shiny future -- Agents can always ask “what skills are available?” and load details only when needed. -- Proxies can inject or augment skills in a standard way. - Users can type `$` to open a skills picker (client UX) or run `/skills` to list available skills. +- Agents can always ask “what skills are available?” and get a consistent list. - Skills move between clients without repackaging or bespoke integrations. - The ecosystem converges on a shared contract without losing flexibility in storage or transport. @@ -72,28 +71,28 @@ This keeps ACP small while giving clients and agents a consistent, interoperable A likely phased plan: -1. Define `SkillDescriptor` and the `skills/list` + `skills/get` methods in the spec and schemas. -2. Update proxy guidance and MCP-over-ACP docs to describe skill resource mapping. -3. Add SDK support (Rust and TypeScript) and generator updates. -4. Update docs and examples to show skill discovery and retrieval, including `/skills` and `$` UX guidance. +1. Define `SkillDescriptor` and the `skills/list` method in the spec and schemas. +2. Add SDK support (Rust and TypeScript) and generator updates. +3. Update docs and examples to show skill discovery, `/skills`, and `$` UX guidance. +4. If needed, add `skills/get` for richer previews of SKILL.md content without requiring the agent to surface it in conversation. ## Frequently asked questions -## Why not rely only on MCP resources? +## Why not rely only on filesystem conventions? -MCP is a transport mechanism, not a semantic contract for “skills.” ACP needs a small skills contract so agents and clients can enumerate and request skills predictably, whether or not MCP is available. +Filesystem conventions are local and tool-specific. ACP needs a small, explicit contract so clients can discover skills consistently across agents and hosts without hard-coding paths or heuristics. ## Does this replace filesystem skills? -No. Filesystem layout remains a local implementation detail. ACP simply standardizes how skills are exposed over the protocol. +No. Filesystem layout remains a local implementation detail. ACP simply standardizes how skills are exposed over the protocol. It does not define how skills are installed or injected; it only lets clients discover what the agent already exposes. -## How large can skills be? +## Who owns skills? -Large skills should be fetched lazily. `skills/get` can return a manifest and/or MCP resource URIs so that clients fetch only what’s needed. +Agents own the skills they expose. ACP does not define client-side or proxy-defined skills; it only reports what the agent makes available. -## Who owns skill sources? +## Why would we ever add `skills/get`? -Skills can be provided by the client, agent, or proxy. The `source` field indicates provenance without enforcing policy. +Discovery is the primary goal. A follow-up `skills/get` is only for richer previews (e.g., showing SKILL.md details or reference lists in the UI) without the agent spending tokens to restate that content in the chat. It is not a way to execute skills, install them, or inject new ones. ## How does this relate to slash commands and `$` lookup? From 2141f386c9aa06c97a2d34c5b1c221922e2a9854 Mon Sep 17 00:00:00 2001 From: Tim Visher <194828183+timvisher-dd@users.noreply.github.com> Date: Sat, 14 Feb 2026 16:58:04 -0500 Subject: [PATCH 5/7] Address skills RFD feedback --- docs/rfds/skills.mdx | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/rfds/skills.mdx b/docs/rfds/skills.mdx index 4d3435e2..7834363a 100644 --- a/docs/rfds/skills.mdx +++ b/docs/rfds/skills.mdx @@ -12,16 +12,17 @@ Define first-class **Skills** discovery in ACP so agents and clients can enumera Skills exist today as **tool-specific filesystem conventions** that are not directly exposed via ACP at all: +- Users have to know what skills are available by heart rather than using the standard `$`/`/skills` discovery mechanisms. - Each client defines its own discovery paths and activation heuristics. - ACP only mentions skills indirectly in the proxy-chains RFD; there is no protocol-level contract for listing or fetching skills. - Proxies can inject instructions, but there is no standardized metadata, no cross-client interoperability, and no way for an agent to ask, “what skills are available?” -- Users have to know what skills are available by heart rather than using the standard `$`/`/skills` discovery mechanisms. This leads to: +- Difficulty for users to remember skills they can invoke +- Difficulty for proxies or agents to expose or request skills programmatically. - Fragmented discovery and inconsistent activation. - Reduced portability of skills across clients. -- Difficulty for proxies or agents to expose or request skills programmatically. ## What we propose to do about it @@ -30,12 +31,10 @@ Introduce an **optional Skills capability** in ACP that standardizes discovery w At a high level: 1. **Skill metadata contract** - - A `SkillDescriptor` includes required fields compatible with the open standard (name + description) plus ACP metadata: + - A `SkillDescriptor` includes required fields compatible with the open standard: - `name`: string (unique key) - `description`: string - - `version?`: string - - `updatedAt?`: string (ISO 8601) - - `checksum?`: string (optional integrity) + - Optional `meta` object may be added later for caching/sorting/integrity hints (e.g., version, updatedAt, checksum), but is not required in v1. 2. **Discovery** - Add a `skills/list` request/response returning `SkillDescriptor[]`. @@ -43,7 +42,8 @@ At a high level: 3. **Client UX hooks** - Recommend a `/skills` slash command via `available_commands_update` when the Skills capability is present. - - Clients may treat `$` as a UI affordance to open a skills picker backed by `skills/list`. + - Clients should treat `$` as a skills-only picker backed by `skills/list`. + - `/` remains the general slash-command picker; clients may also list skills there for compatibility (e.g., `/1password`), but `$` should remain the skills-only entry point. - `/` and `$` are client-side conventions; ACP only defines the discovery data and the `available_commands_update` signal. 4. **Compatibility with the open standard** @@ -54,6 +54,8 @@ This keeps ACP small while giving clients and agents a consistent, interoperable ## Non-goals +These are intentionally out of scope for ACP and are handled by the Agent Skills standard or local tooling: + - Define how skills are installed, updated, or executed. - Allow clients or proxies to inject or override agent skills. - Standardize filesystem paths or activation heuristics. @@ -74,13 +76,13 @@ A likely phased plan: 1. Define `SkillDescriptor` and the `skills/list` method in the spec and schemas. 2. Add SDK support (Rust and TypeScript) and generator updates. 3. Update docs and examples to show skill discovery, `/skills`, and `$` UX guidance. -4. If needed, add `skills/get` for richer previews of SKILL.md content without requiring the agent to surface it in conversation. +4. If needed, add `skills/get` for richer previews of SKILL.md content without requiring the agent to surface it in conversation. This should not replace existing `/skill` or `$skill` invocation flows. ## Frequently asked questions ## Why not rely only on filesystem conventions? -Filesystem conventions are local and tool-specific. ACP needs a small, explicit contract so clients can discover skills consistently across agents and hosts without hard-coding paths or heuristics. +Filesystem conventions are local and tool-specific. ACP needs a small, explicit contract so clients can discover skills consistently across agents and hosts without hard-coding paths or heuristics. This also shields clients from provider-specific skill discovery quirks. ## Does this replace filesystem skills? @@ -92,7 +94,7 @@ Agents own the skills they expose. ACP does not define client-side or proxy-defi ## Why would we ever add `skills/get`? -Discovery is the primary goal. A follow-up `skills/get` is only for richer previews (e.g., showing SKILL.md details or reference lists in the UI) without the agent spending tokens to restate that content in the chat. It is not a way to execute skills, install them, or inject new ones. +Discovery is the primary goal. A follow-up `skills/get` is only for richer previews (e.g., showing SKILL.md details or reference lists in the UI) without the agent spending tokens to restate that content in the chat. It is not a way to execute skills, install them, or inject new ones. In effect, it lets clients render “what this skill does” by parsing SKILL.md. ## How does this relate to slash commands and `$` lookup? From cae88286d23d57bec6171f71fca938291921e3d6 Mon Sep 17 00:00:00 2001 From: Tim Visher <194828183+timvisher-dd@users.noreply.github.com> Date: Sat, 14 Feb 2026 17:05:03 -0500 Subject: [PATCH 6/7] Clarify slash picker behavior for skills --- docs/rfds/skills.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/rfds/skills.mdx b/docs/rfds/skills.mdx index 7834363a..05dd18c8 100644 --- a/docs/rfds/skills.mdx +++ b/docs/rfds/skills.mdx @@ -43,7 +43,7 @@ At a high level: 3. **Client UX hooks** - Recommend a `/skills` slash command via `available_commands_update` when the Skills capability is present. - Clients should treat `$` as a skills-only picker backed by `skills/list`. - - `/` remains the general slash-command picker; clients may also list skills there for compatibility (e.g., `/1password`), but `$` should remain the skills-only entry point. + - `/` remains the general slash-command picker and SHOULD include skills whenever the Skills capability is advertised (e.g., `/1password`), even if the agent does not expose each skill as a standalone slash command. `$` remains the skills-only entry point. - `/` and `$` are client-side conventions; ACP only defines the discovery data and the `available_commands_update` signal. 4. **Compatibility with the open standard** @@ -94,7 +94,7 @@ Agents own the skills they expose. ACP does not define client-side or proxy-defi ## Why would we ever add `skills/get`? -Discovery is the primary goal. A follow-up `skills/get` is only for richer previews (e.g., showing SKILL.md details or reference lists in the UI) without the agent spending tokens to restate that content in the chat. It is not a way to execute skills, install them, or inject new ones. In effect, it lets clients render “what this skill does” by parsing SKILL.md. +Discovery is the primary goal. A follow-up `skills/get` is only for richer previews (e.g., showing SKILL.md details or reference lists in the UI) without the agent spending tokens to restate that content in the chat. It is not a way to execute skills, install them, or inject new ones. In effect, it lets clients render “what this skill does” by parsing SKILL.md. This is not considered necessary for an MVP. ## How does this relate to slash commands and `$` lookup? From 816013c6b296ebf8420aff0c2b3e27fef95d4ef7 Mon Sep 17 00:00:00 2001 From: Tim Visher <194828183+timvisher-dd@users.noreply.github.com> Date: Sat, 14 Feb 2026 17:10:39 -0500 Subject: [PATCH 7/7] Refine skills RFD based on feedback Co-authored-by: Codex --- docs/rfds/skills.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/rfds/skills.mdx b/docs/rfds/skills.mdx index 05dd18c8..fa1bd824 100644 --- a/docs/rfds/skills.mdx +++ b/docs/rfds/skills.mdx @@ -13,6 +13,7 @@ Define first-class **Skills** discovery in ACP so agents and clients can enumera Skills exist today as **tool-specific filesystem conventions** that are not directly exposed via ACP at all: - Users have to know what skills are available by heart rather than using the standard `$`/`/skills` discovery mechanisms. + - This is also an unnecessary 'surprise' for users coming from direct codex/claude usage who are used to this affordance. - Each client defines its own discovery paths and activation heuristics. - ACP only mentions skills indirectly in the proxy-chains RFD; there is no protocol-level contract for listing or fetching skills. - Proxies can inject instructions, but there is no standardized metadata, no cross-client interoperability, and no way for an agent to ask, “what skills are available?”