RFD: Add Agent Skills List proposal

[ignatov]

Proposes a mechanism for agents to advertise available skills to clients, aligned with the Agent Skills Specification (https://agentskills.io/specification).

Introduces:

• AvailableSkill type with name, description, license, compatibility, and allowedTools fields
• AvailableSkillsUpdate session notification

[benbrandt]

Seems reasonable. If I understand correctly, this is solely for informational purposes to the client to show the user?
At this stage, there would be no management of the skills available from the client?

[jwflicker]

What about enabling the client to forward additional locations of some skills folders to the agent, say at session creation, similar to how the client can forward a collection of MCP servers for the agent to use. Maybe the IDE has its own skills folders. Maybe the user wrote their own skills folder they would like to use across different agents.

[yordis]

How would it work when Skills are acting as Slash Commands? Does the Agent decide to put them in the Slash Command or not?

Recently, that is what has been happening, deprecating "Slash Commands" per se, and just have metadata in the skills to allow such direct activation.

Second, I am guessing the intention here is to do something like @skillname along with /skillname?

[timvisher-dd]

I'll add the basic premise of my duplicate RFD: I mainly want $ to work like it does in the codex and claude CLIs as well as the / completion to include skills as it does in the same. I think all we really need for this is an extremely small skills/list message and data structure containing a name and description.

[yurishkuro]

From a client perspective why does a client need to know the difference between command and skill? If client can invoke the skill directly then it's no different from invoking a command. If it cannot invoke the skill directly (i.e. the agent autonomously decides when to use a skill) then the client doesn't need to know such structured info about the skill, it would be sufficient to include capabilities in the description of the agent itself.

[timvisher-dd]

From a client perspective why does a client need to know the difference between command and skill? If client can invoke the skill directly then it's no different from invoking a command. If it cannot invoke the skill directly (i.e. the agent autonomously decides when to use a skill) then the client doesn't need to know such structured info about the skill, it would be sufficient to include capabilities in the description of the agent itself.

IMO it's because agents see skills as special. I went to the effort of translating most of my old docs into skills and saw a meaningful improvement to the agents' use of them. So as a human I'm interested in being able to surface what skills an agent knows about conveniently.

That said I agree that / should just fold them all together (perhaps with a simple type indicator like /foo Bar bat bin (skill) at most) and $ should only surface skills.

[dmeehan1968]

Whilst this provides a mechanism for agents to notify clients of skills (which in part already seems to be covered by the availableCommands update), I feel its imperative that the ACP client can provide skills/subagents to the agent (like it does for MCPs) because agents don't have a universal way of installing such assets.

From the users perspective, the ACP client should be able to display the 'source of truth' for MCPs/skills/subagents) because its very important that the user can review these assets for malicious content. Whilst existing agents have allowed ways of doing this, its tied up with the agents UI, and for most its quite primitive.

I feel there is an opportunity for ACP to enable the client to have first class support for agent extensibility, using standards such as MCP, skills and subagents. This could even extends to hooks, and other forms of extension, but I suspect we need standards around these before that can happen.

Having such a facility means that the ACP client can be the users sole window into agent extensibility, and that allows ACP to enable true agnosticism of which agent is used for a session. I already have this principle in my ACP client, but the lack of skills/subagents support through ACP means that I have to defer to each and every peculiar configuration scenario, delegate to a third-party tool, and don't have the ability to build a consistent UI with providing adapters, monkey patching or workarounds.

[nikomatsakis]

Hey, I'm catching up on RFDs. I'm very excited about the idea of adding skills and in fact I intended to write an RFD much like this one. I haven't read it over in detail yet, I will, but I've been giving thought into how to address this.

My ideal would be that we allow "injecting" skills programmatically, much like MCP servers. There are some challenges to this.

For starters, Claude at does does not give programmatic access to "injecting skills"; I haven't looked closely at other agents.

For another, skills can reference files and things (e.g., use scripts/foo). This means that you have to either materialize the skill on the disk as a real directory the agent can read or else give it a tool to read files from a particular skill.

I am not sure the best way to put this into the protocol proper.

For now, I've been toying with an experimental "skills proxy" that injects some initial context listing out the available skills and then provides an MCP tool for activating a skill. This will give back the SKILL.md content along with the directory. I kind of like the idea of having a tool for all the file access because I'd prefer if all that access is mediated by the protocol.

[anna239]

@nikomatsakis we're currently using this functionality for adding skills to the agents: https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/additional-directories.mdx We just send a folder with the skill.md files as additional directory and agent loads skills form it.
We explored if we can do something similar to mcp servers, but it turned out that agents don't actually support it and we've decided to go with additional directories approach

[dmeehan1968]

@anna239 can you expand on this approach? This seems not to follow the skills spec, which says that skills should each be in a directory, with SKILL.md as a minimum.

• Are you creating a directory with foo.md, bar.md, etc?
• What about skill resources?

Whilst providing additional directories would allow an agent to discover those files, does it actually add its internal skill index, and provide /commands for activation? Does it add them to additionalCommands? Is that universally supported by agents?

Or is it just relying on the models curiosity about what those files might mean, given a semantic match to the task at hand?

@nikomatsakis It would be true to say that the agents don't currently provide programmatic access (and certainly not universally) but that doesn't mean that cannot. Once ACP defines the shape of skills/subagent/hook definitions, then agents can decide whether and how to implement that, just as they do for the other capabilities.

[nikomatsakis]

@dmeehan1968 Yes, I agree. What I think we ought to do is to act "as if" they provided programmatic access -- then I think we can have the agent implement it or even have a polyfill (I'm working on a standard set of polyfill proxies for this kind of thing).

But there are some interesting questions -- for example, assume that there is an "activate skill" message. What does it return?

I see two possibilities

• it returns a directory where the skill can be found; I don't like this, because I prefer for ACP to be "self-contained".
• it returns a JSON entry that contains the SKILL.md contents along with the paths of all other files and directories. And then there is some way to fetch the contents of one or more of those files, e.g., another message like "load skill resource(s)".

@anna239: that's an interesting point, maybe a useful hack, I'd still prefer though it takes place at the agent side or in a polyfill, the above seems like how skills would be most obviously supported "natively" in ACP. WDYT?

[dmeehan1968]

@nikomatsakis I was imagining that this would be more like the MCP list specified to the agent.

The initialize response would need to be extended to include whether the agent supports skill/subagents.

If supported the client includes skills in session/new, which gets new properties for skills, subagents etc) which provides the essential SKILL.md text (not a file) and an array of optional parts that are a map of path: content that mimics the normal skill directory layout. Now I imagine this gets more complex as skills resources/assets could be any file type and size, so this could be a burdensome approach, especially if it has to be repeated on all session/new calls. So I'd accept this is probably naive but I don't have a good handle on just how big skills actually can get, but appreciate from a spec perspective its probably unbounded.

Assuming such a design, it's up to the agent to supplement its normal discovery of skills (e.g filesystem), probably by mapping the provided skills to a temporary directory that is included in its normal skill discovery process, which seems like a trivial ask for the agent to provide client provision of skills/subagents.

Your approach seems more two way, in that the client would presumably provide a simple list of skills/subagents (perhaps the equivalent of skill frontmatter) and the agent would make requests to serve up the components, similar to the filesystem requests. This might be a way to get around the client having to provide complete skills and resources up front, when they might not even get referenced. This seems to require a little more wiring on the part of the agent to fit into its existing discovery mechanism, but then also reuses some logic that agents can already opt into (skill and resource requests are then very similar to fs reads requests, either on a separate namespace or some indicator to show they are 'virtual' and not real fs requests).

I think its worth being mindful that the protocol shouldn't care where the client stores its skills/subagents, e.g. they could be in a database rather than file system, so trying to piggy back directly onto the filesystem requests might lead to all sorts of issues, not least then running into whether permissions get invoked for reads outside of the CWD.

I think there might be an argument for coming up with a more generic interface to 'extensions', so they have a 'type' discriminator that is extensible, and saves having multiple keys on the session/new for new ones that we can't imagine just yet. Hooks might be a good candidate for something that implies something other than a filesystem like mapping. I suspect that anything requiring execution should be handled on the agent server side, not the client, but maybe that even speaks to something more akin to an MCP like capability, so the client can provide native or pluggable extensions that do more complex processing. Hello can of worms.

[egor-baranov]

@dmeehan1968 hi, I was the one who worked on the additionalDirectories implementation. It is a more general mechanism than skill injection specifically: the client exposes additional absolute filesystem roots to the agent.

You can think of these as extra cwds alongside the main one. The main cwd remains primary, but the agent can apply the same discovery/indexing/resource-loading behavior to each additional root that it already applies to the main workspace.

For skills, the intended layout is still the normal filesystem-backed skill layout: a root containing skill directories, each with its own SKILL.md plus any sibling resources/scripts/assets. We are not relying on the model noticing arbitrary markdown files.

This maps to mechanisms that existing agents already expose:

• Codex CLI: --add-dir and filesystem-backed Codex skills
• Claude Code: --add-dir, additionalDirectories, and skills loaded from .claude/skills/ inside added directories
• Gemini CLI: --include-directories / context.includeDirectories, /directory add, and extension-bundled agent skills

So I see additionalDirectories as the provisioning layer for filesystem-backed assets, including skills. The available_skills_update proposal in this RFD would be the advertising layer: after the agent has indexed whatever skills it actually made available, it can report that normalized list back to the client.

[dmeehan1968]

@egor-baranov Thank you so much for the detail explanation.

This doesn't seem to provide the agent agnosticism that I think ACP needs, as you are suggesting the agent still expect their own specific paths, e.g. .claude/skills (although I guess a universal skill installer with symlinks could patch this to be agnostic).

What I can see is that this is more generic that extends agent capabilities with skill/subagent/hooks specific support, as theoretically it allows any agent extension to be installed as required by the agents own conventions, which probably better covers the 'yet to be imagined' use cases.

I'll give it a go and see what I find.

[dmeehan1968]

@egor-baranov I tried additionalDirectories with Claude Code and it didn't work, but it seems that Claude does not advertise additonalDirectories as a capability (initialise response > agent capabilities > session capabilities > additionalDirectories - at least via the Typescript SDK I'm using).

Also the help for CC suggests that the support is limited, and whilst skills are supposed to be supported, most other config options are not.

So it seems this is likely to be a very agent specific method. Of course, first class support for skills or other extensions is also not going to be universal, but perhaps by advertising the capability in the ACP spec, we'd get agent to follow? The ACP protocol is otherwise at risk of becoming a kind of gatekeeper, with agent just producing their own esoteric solutions to supporting extensions.