Hi all 👋
I am the owner of the Dart/Flutter MCP server, and this proposal which is very relevant to this working group https://flutter.dev/go/packaged-ai-assets.
I in general love the direction this working group is heading in, but like to propose that we take a slight step back, looking at the core value proposition of skills and figuring out how to replicate that using MCP primitives in a slightly more generic fashion.
The core magic of skills
Skills are really not complicated, literally all the magic is just that the index of them is included in the context, very early on. That is it :). (well, also a tool to read skills).
This could be exactly replicated with an index like this for resources:
<resources>
<resource name="Some resource name" uri="file://my/resource">Description here</resource>
</resources>
Proposal
My argument, is that what we actually need is some metadata attached to the Resource object, which indicates whether or not that resource should be included in an index of resources pro-actively exposed to the model (via whatever mechanism the client chooses, but probably using a similar "index" to what I listed above, similar to most skill implementations).
This metadata could live on Annotation, or just directly on the Resource object. It would be a simple boolean, something like includeInContextIndex or similar (probably we can come up with a better name haha).
We could also have a "behavior" enum, with multiple possible values?
Why not a skills:// URI or similar convention?
This is about more than just skills
Any and all resources should be able to be included in the same way as skills. The skills format really only exists to communicate data which already exists on the Resource object.
If we call something a skill (using a skill URI), that implies it should probably follow the skill format. But, resources are much more than that, and in fact we have little if any need for the actual skill format (the Resource object already contains this metadata from the header).
One specific example of this is including the examples from your package dependencies as "skills" (and by that, I just mean putting their resource descriptions in an index in the context). I have prototyped this out and it is incredibly valuable for agents, this is what it looks like in one package Norbert515/nocterm#62 using my proposal above. Why should I have to wrap each of those examples as a skill? What value does that provide?
Domain specific URIs
Domain specific MCP servers already have opinions about what specific URIs mean, and may prefer to keep those. This means that other URIs inside the skills can be relative paths, and can easily be translated to have a consistent meaning.
As an example, in my proposal above the URI package-root:<package-name>/<path> refers to a relative path under some package dependency. I would love to just use that exact URI as the thing exposed to models (we already expose a tool for reading these URIs, or they can be read as a resource, we have to expose both options because we don't know if a client supports reading resources).
This would allow you to for example expose a resource at package-root:my_package/cool.md like this:
Read `awesome.md` and `really/super/awesome.md` to see how to be a cool agent.
These relative paths can be easily translated by the agent into package-root:my_package/awesome.md and package-root:my_package/really/super/awesome.md.
If I instead use a skills URI like skill://my_package/cool.md, then now there are multiple ways of referencing and loading these files which are actually identical. This might cause duplicate context inclusion and general confusion for the agent. Also, these other files are not skills, so it doesn't make sense for them to have a skill: URI, but that is what you would end up with.
Allow sharing of resources with AI and Humans
One area I get a lot of pushback on when adding skills, is that you are effectively adding documentation only for agents, and not for humans.
Should you then duplicate essentially the same content in two places? With skills, you essentially have to, or you can have a skills that just links to the user documentation, which causes an extra tool call.
You could just make all your user documentation use the skills format, but that also seems less than ideal to me.
By allowing any resource to be treated like a skill, you can just expose directly the user facing documentation you already have to the agent, using your existing URI schemes, etc.
You can still also have skills
Note that there is already a convention for defining if something is a skill, it is simply the base name of the file "SKILL.md". That convention is probably fine, and for servers that do want to use the skills format, I think it would be sufficient to just consider any resource with that base name a skill.
You could also still have a convention around a skill: scheme, but I think it is important that this is not the only way to get the automatic context index inclusion, which is really the only important part here.
Uri collisions
If we all use the same scheme, we are more likely to have collisions. Some MCP servers may use very simplistic URIs, even if they are told to prefix them with the server name, they may not do so.
Hi all 👋
I am the owner of the Dart/Flutter MCP server, and this proposal which is very relevant to this working group https://flutter.dev/go/packaged-ai-assets.
I in general love the direction this working group is heading in, but like to propose that we take a slight step back, looking at the core value proposition of skills and figuring out how to replicate that using MCP primitives in a slightly more generic fashion.
The core magic of skills
Skills are really not complicated, literally all the magic is just that the index of them is included in the context, very early on. That is it :). (well, also a tool to read skills).
This could be exactly replicated with an index like this for resources:
Proposal
My argument, is that what we actually need is some metadata attached to the Resource object, which indicates whether or not that resource should be included in an index of resources pro-actively exposed to the model (via whatever mechanism the client chooses, but probably using a similar "index" to what I listed above, similar to most skill implementations).
This metadata could live on Annotation, or just directly on the Resource object. It would be a simple boolean, something like
includeInContextIndexor similar (probably we can come up with a better name haha).We could also have a "behavior" enum, with multiple possible values?
Why not a skills:// URI or similar convention?
This is about more than just skills
Any and all resources should be able to be included in the same way as skills. The skills format really only exists to communicate data which already exists on the Resource object.
If we call something a skill (using a
skillURI), that implies it should probably follow the skill format. But, resources are much more than that, and in fact we have little if any need for the actual skill format (the Resource object already contains this metadata from the header).One specific example of this is including the examples from your package dependencies as "skills" (and by that, I just mean putting their resource descriptions in an index in the context). I have prototyped this out and it is incredibly valuable for agents, this is what it looks like in one package Norbert515/nocterm#62 using my proposal above. Why should I have to wrap each of those examples as a skill? What value does that provide?
Domain specific URIs
Domain specific MCP servers already have opinions about what specific URIs mean, and may prefer to keep those. This means that other URIs inside the skills can be relative paths, and can easily be translated to have a consistent meaning.
As an example, in my proposal above the URI
package-root:<package-name>/<path>refers to a relative path under some package dependency. I would love to just use that exact URI as the thing exposed to models (we already expose a tool for reading these URIs, or they can be read as a resource, we have to expose both options because we don't know if a client supports reading resources).This would allow you to for example expose a resource at
package-root:my_package/cool.mdlike this:These relative paths can be easily translated by the agent into
package-root:my_package/awesome.mdandpackage-root:my_package/really/super/awesome.md.If I instead use a skills URI like
skill://my_package/cool.md, then now there are multiple ways of referencing and loading these files which are actually identical. This might cause duplicate context inclusion and general confusion for the agent. Also, these other files are not skills, so it doesn't make sense for them to have askill:URI, but that is what you would end up with.Allow sharing of resources with AI and Humans
One area I get a lot of pushback on when adding skills, is that you are effectively adding documentation only for agents, and not for humans.
Should you then duplicate essentially the same content in two places? With skills, you essentially have to, or you can have a skills that just links to the user documentation, which causes an extra tool call.
You could just make all your user documentation use the skills format, but that also seems less than ideal to me.
By allowing any resource to be treated like a skill, you can just expose directly the user facing documentation you already have to the agent, using your existing URI schemes, etc.
You can still also have skills
Note that there is already a convention for defining if something is a skill, it is simply the base name of the file "SKILL.md". That convention is probably fine, and for servers that do want to use the skills format, I think it would be sufficient to just consider any resource with that base name a skill.
You could also still have a convention around a
skill:scheme, but I think it is important that this is not the only way to get the automatic context index inclusion, which is really the only important part here.Uri collisions
If we all use the same scheme, we are more likely to have collisions. Some MCP servers may use very simplistic URIs, even if they are told to prefix them with the server name, they may not do so.