docs/rfds: Add support for Agent Skill discovery

docs/rfds/skills.mdx

@@ -0,0 +1,111 @@
+---
+title: "Skills Discovery and Delivery"
+---
+
+- Author(s): [@timvisher-dd](https://github.com/timvisher-dd), Codex <codex@openai.com>
+
+## Elevator pitch
+
+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** 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?”
+
+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.
+
+## What we propose to do about it
+
+Introduce an **optional Skills capability** in ACP that standardizes discovery 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`: string (unique key)
+     - `description`: string
+   - 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[]`.
+   - This is sufficient for `/skills` and `$` pickers without requiring any skill content transfer.
+
+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 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**
+   - ACP does not re-define file layout; it adopts the SKILL.md frontmatter as the canonical metadata source.
+   - 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
+
+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.
+
+## Shiny future
+
+- 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.
+
+## Implementation details and plan
+
+> Optional for initial draft; fill in after discussion.
+
+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. 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. This also shields clients from provider-specific skill discovery quirks.
+
+## Does this replace filesystem skills?
+
+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.
+
+## Who owns skills?
+
+Agents own the skills they expose. ACP does not define client-side or proxy-defined skills; it only reports what the agent makes available.
+
+## 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. This is not considered necessary for an MVP.
+
+## 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.
+- **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