Proposal: Skills — workflow-level context for tool composition

[Idan-Levin]

Proposal to let pages register skills — bundling tools with structured context and workflow guidance — so agents can use a site competently, not just functionally.

Tools can tell agents what a site can do, but Skills tell agents how to do it well.

A skill bundles registered tools with structured context and optional guidance, so agents can operate competently within a domain rather than calling functions blind.

Strawman API

navigator.modelContext.registerSkill({
  name: "personal_shopper",
  description: "Shopping assistant guidance for this store",
  instructions: `
    1. Ask about occasion and budget before searching
    2. Our sizing runs small — suggest one size up
    3. For orders over $100, mention current promotion
    4. Always mention 30-day return policy before checkout
    5. Use requestUserInteraction() for payment confirmation
  `,
  tools: ["searchProducts", "showProducts", "addToCart", "applyPromoCode"],
  context: {
    currentPromotion: { code: "SPRING30", minOrder: 100, discount: "30%" },
    returnPolicy: "30-day free returns, free first exchange",
    sizingNote: "Sizes run ~1 size small vs. US standard"
  },
  annotations: { category: "commerce", version: "1.0" }
});

Tools are still registered independently via registerTool(). A skill references them by name and adds the layer of how and when to use them.

instructions is an optional hint — clients that don't interpret natural language (accessibility tools, OS assistants) can ignore it and still use the tools and structured context directly.

Problem

An e-commerce site registers searchProducts, addToCart, and applyPromoCode. An agent can call them. But it doesn't know the store's sizing runs small, there's an active promo code, it should ask about occasion before searching, or which products pair well together.

Tool descriptions can't carry this weight — they document individual functions, not workflows. The gap grows with domain complexity: travel sites need fare class knowledge, support portals need triage logic.

Design Considerations

• Trust. Skills influence agent behavior. Safeguards: user-inspectable (like page source), domain-scoped (like tools), advisory (agents serve users first). Browsers could enforce content policies on instructions.
• Discoverability. A .well-known/webmcp manifest could include skill declarations alongside tools.
• Agnosticism. instructions is a hint for LLM-based agents. The structured context object and tools list are useful to any client. Non-LLM clients skip what they don't understand — same pattern as readOnlyHint.

Open Questions

• New method (registerSkill) or extension to provideContext()?
• Should instructions be plain text, structured steps, or both?
• How should skills interact with the agent's own system-level constraints?

Prior Art

• MCP prompts/resources — backend MCP's guidance and data primitives
• MCP-B — already bridges WebMCP to full MCP including prompts and resources via npm packages
• Claude Skills, Custom GPTs, LobeHub Skills — production patterns bundling instructions + tools + context

[DavidMulder0]

Generally this proposal seems very overengineered and too narrow in scope, but I agree that "descriptions for multiple tools at the same time" are useful. In our own applications we indeed need to "explain" to the LLM a variety of concepts that then apply to multiple tools. Those aren't "workflows" whatsoever, just slightly obscure domain specific concepts that especially smaller models struggle with. In our main application we simply treat this as a system prompt, however for our WebMCP POC this is simply missing completely at the moment.

Your example seems particularly weak, "Ask about occasion and budget before searching" can be solved by requiring search to have an occasion and budget parameter, "Our sizing runs small — suggest one size up" can be communicated in tool responses when enumerating individual products. "For orders over $100, mention current promotion" should probably be an addToCart response. "Always mention 30-day return policy before checkout" should probably be a part of the response of a startCheckout tool. "Use requestUserInteraction() for payment confirmation"... this seems to fundamentally misunderstand what that function is for. However, I agree that there will be cases where such workflows could make sense in more complex applications.

[andreban]

I did an exploration on using the registerTool to provide "skills" to an agent.

The TL:DR is that It uses the tool description as a short summary to get the agent understand when that skill should be used and the tool implementation returns the full instructions to combine the available tools to achieve a higher level goal. You can read more at: https://bandarra.me/posts/webmcp-tools-as-skills.

The implementation works, but it would likely be good for developers to be able to differentiate skills from tools during implementation but, more importantly, for agents to know how to differentiate those.

[Idan-Levin]

I did an exploration on using the registerTool to provide "skills" to an agent.

The TL:DR is that It uses the tool description as a short summary to get the agent understand when that skill should be used and the tool implementation returns the full instructions to combine the available tools to achieve a higher level goal. You can read more at: https://bandarra.me/posts/webmcp-tools-as-skills.

The implementation works, but it would likely be good for developers to be able to differentiate skills from tools during implementation but, more importantly, for agents to know how to differentiate those.

@andreban this is great - your factory demo is basically what I was trying to describe. And your post makes the tradeoff clearer than my issue did.

I think your last point is right, the pattern works today, but there's no shared signal that tells an agent "this is a skill, not just another tool." So it has to guess from the name.

What if a skill was just a tool with an annotation - something like annotations: { kind: "skill" }? Minimal change and backwards compatible. Agents that recognize it can treat skills differently (load them early, prioritize them). Agents that don't just see a normal tool.

Curious if you think that's enough, or if a proper registerSkill() would still be worth it.

[DavidMulder0]

@andreban Question, what was your reason for creating a bunch of bespoke tools and introducing the concept of 'skills' rather than a single getRecipeFor tool with a readOnlyHint? (Context: In general we've felt like we needed to limit the number of tools to a decently small number).

@Idan-Levin If the goal is to expose the concept of 'skills' to an LLM, why not just have a getSkill tool? What would be gained by having this be a part of the specification? What would "load them early, prioritize them" mean in practise and how would it be different from readOnlyHint? Is this about MCP Hosts that implement tool discovery mechanisms rather than exposing all tools to the LLM? (if yes, I would argue that tool discovery deserves it's own issue, as there are a variety of ways to implement those, and they all require different types of information).

And general question: So skills as understood here would always be loaded on demand? They are not about exposing information in something akin to the system prompt? (FWIW, our need is definitely more about putting information in something akin to the system prompt)

[Idan-Levin]

@DavidMulder0

The difference between getSkill as a tool and registerSkill as a protocol primitive isn't whether it works - @andreban already proved it works in his experiment. It's who decides when the skill matters.

With getSkill-as-a-tool, the agent has to first notice the tool exists, decide it's relevant, and call it - all before it has the context that would tell it the skill is relevant in the first place. That's a chicken-and-egg problem. In my examples - the agent needs the sizing-runs-small context to interpret the user's "do you have this in medium?" question, but it won't fetch that context unless something already tipped it off that this store has quirky sizing.

With a protocol-level skill, the client (Gemini, Claude, whatever) can make that decision structurally: "this origin declared a skill, I'm loading it into context at session start, same as I'd load a system instruction." No need for guessing, no wasted tool-call round-trip, no dependence on the agent's judgment about whether to explore an unfamiliar tool.

Protocol recognition lets the client prioritize loading without the agent having to discover-then-decide. It's about when in the loop the context arrives.

[andreban]

@andreban Question, what was your reason for creating a bunch of bespoke tools and introducing the concept of 'skills' rather >than a single getRecipeFor tool with a readOnlyHint? (Context: In general we've felt like we needed to limit the number of tools to a >decently small number).

Having a single tool that would take an enum or oneOf as parameter was my intial idea, but I moved away from that.

The general problem of having too much tools is context management. My alternatives were to either:

1. have single tool where I would have to heavily rely on the description/parameters for the agent to use that tool correctly.
2. break that into multiple tools, each with simple description, where I have to rely on the agent picking the right too.

At the end of the day, option 1 or 2 just move the context management problem around, making a single tool harder for the agent to understand and use or making it harder for the agent to choose which tool to use.

Then, from a developer perspective it felt easier to maintain multiple tools with simple descriptions, which alsomakes the tools completely independent from each other, than it is to maintain a single tool with complex description and parameters.

So, because it sounds like the context management problem is just being moved around, and that the implementation seemed simpler by providing dedicated tools, I changed the design.

On a more opinionated point, which wasn't in my mind when I changed the path I was taking, I think there's an argument to be made that defining a tool with good names, descriptions and parameters so the agent can use it correctly is a developer problem, while handling the selection of the right tool to use when there are many tools is a problem for the implementer of the agent. So, philosophically, it might mean we'd be moving a problem that should be solved by the agent by adding complexity for developers instead.

[Idan-Levin]

@andreban Question, what was your reason for creating a bunch of bespoke tools and introducing the concept of 'skills' rather >than a single getRecipeFor tool with a readOnlyHint? (Context: In general we've felt like we needed to limit the number of tools to a >decently small number).

Having a single tool that would take an enum or oneOf as parameter was my intial idea, but I moved away from that.

The general problem of having too much tools is context management. My alternatives were to either:

1. have single tool where I would have to heavily rely on the description/parameters for the agent to use that tool correctly.
2. break that into multiple tools, each with simple description, where I have to rely on the agent picking the right too.

At the end of the day, option 1 or 2 just move the context management problem around, making a single tool harder for the agent to understand and use or making it harder for the agent to choose which tool to use.

Then, from a developer perspective it felt easier to maintain multiple tools with simple descriptions, which alsomakes the tools completely independent from each other, than it is to maintain a single tool with complex description and parameters.

So, because it sounds like the context management problem is just being moved around, and that the implementation seemed simpler by providing dedicated tools, I changed the design.

On a more opinionated point, which wasn't in my mind when I changed the path I was taking, I think there's an argument to be made that defining a tool with good names, descriptions and parameters so the agent can use it correctly is a developer problem, while handling the selection of the right tool to use when there are many tools is a problem for the implementer of the agent. So, philosophically, it might mean we'd be moving a problem that should be solved by the agent by adding complexity for developers instead.

@andreban

On the last point, I think about this in terms of a “context hierarchy.” Skills sit above tools in the stack - they provide general context, while tools provide specific execution context. I do not think an agent will reliably have the domain-specific knowledge needed to infer that hierarchy on its own, unless each tool description explicitly states that another tool should always be loaded first because it is relevant to the others. But that is effectively the same as marking it as a skill at the protocol layer. So the distinction between a skill and a tool is not really an agent problem - it is a developer problem.

[andreban]

On the last point, I think about this in terms of a “context hierarchy.” Skills sit above tools in the stack - they provide general context, while tools provide specific execution context. I do not think an agent will reliably have the domain-specific knowledge needed to infer that hierarchy on its own, unless each tool description explicitly states that another tool should always be loaded first because it is relevant to the others. But that is effectively the same as marking it as a skill at the protocol layer. So the distinction between a skill and a tool is not really an agent problem - it is a developer problem.

Ah, yes, my point was more on the side of how to design and expose tools to the agent and less about skills - I was using my skills implementation as an example. I agree agents might need to manage the context from skills vs tools differently.