Agent Skills and WebMCP: giving agents instructions and buttons

Text tells an agent about you. These let it act.

An agent that reads your pages learns what you offer. An agent that has your Skill knows how to do a task with your product the way you would do it. An agent that sees your WebMCP tools can press your buttons without guessing which pixels to click. Both formats appeared in the last year, both are open, and both are already on Cloudflare's agent-readiness checklist under Capabilities. They solve different problems, so it helps to keep them apart.

Agent Skills: a SKILL.md an agent can load

The Agent Skills specification defines a skill as a directory with a SKILL.md file: YAML frontmatter with at least name and description, then Markdown instructions. Optional scripts/, references/ and assets/ folders travel with it. Agents load skills by progressive disclosure: only name and description at startup, the full body when a task matches. That is why the description is the field to spend time on; it decides whether the skill is ever opened.

---
name: brand-order-lookup
description: Look up order status and delivery dates for brand.ch customers. Use when a user asks where their brand.ch order is or wants to change a delivery.
license: Apache-2.0
metadata:
  author: brand.ch
  version: "1.0"
---

# Order lookup

1. Ask for the order number (format BR-12345678) if not given.
2. Call `GET https://api.brand.ch/orders/{id}` with the user's token; see references/auth.md.
3. Report status, carrier and the delivery window. Never invent a date.

For discovery on the web, the convention scanners look for is an index at /.well-known/agent-skills/index.json, following the Agent Skills discovery schema. Cloudflare publishes one on its developer docs: each entry has a name, a description, a type of skill-md or archive, a url and a sha256 digest.

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "brand-order-lookup",
      "type": "skill-md",
      "description": "Look up order status and delivery dates for brand.ch customers.",
      "url": "/.well-known/agent-skills/brand-order-lookup/SKILL.md",
      "digest": "sha256:…"
    }
  ]
}

WebMCP: tools inside the page

WebMCP is a W3C Web Machine Learning community group proposal. Instead of building a separate MCP server that duplicates your login state and business logic, the page itself registers tools while the user is on it, and a browser-integrated agent calls them. The imperative API is document.modelContext.registerTool() with a name, description, JSON schema and an execute function; a declarative variant adds toolname and tooldescription attributes to an ordinary <form> so the browser synthesises the tool from the fields.

<form toolname="search-products"
      tooldescription="Search the brand.ch catalogue by keyword and size"
      action="/search" method="get">
  <label>Keyword <input name="q" required></label>
  <label>Size <select name="size"><option>S</option><option>M</option><option>L</option></select></label>
  <button>Search</button>
</form>

The advantage over screen-driving is that the agent gets your schema rather than inferring it from labels, and the page stays in sync because your own code runs the action. The limitation is reach: it only works in browsers and agents that implement the API, and the explainer's implementation-status page is the place to check what does today. It is also gated by a permissions policy (tools), so a page must opt in.

What Qomvia checks

Agent Skills or WebMCP under Agent protocols is a single point that passes if either is present: a 200 at /.well-known/agent-skills/index.json, or WebMCP markers in the homepage HTML (a toolname= attribute, the word WebMCP, or a modelContext registration in inline script). Tools registered from an external JavaScript bundle are not visible to a crawler, so the declarative form is what a scanner can see. Cloudflare's readiness numbers put both formats in the low single-digit percentages of sites, which means publishing either still puts you well ahead.

For most Qomvia users the practical order is: an MCP discovery document if you have an API, then one Skill for your most common support task with an index file, then WebMCP on the one form that matters most (search, booking, quote). Each is a small file; none of them requires a new backend.

Questions

Is a Skill the same as an MCP server?

No. A Skill is instructions and optional scripts the agent runs itself; an MCP server is code you host that the agent calls. A Skill can tell the agent to use your MCP server or API.

Who reads /.well-known/agent-skills/index.json today?

Readiness scanners and agents that implement the discovery schema. It is early. The file costs nothing and the SKILL.md inside it is useful to any agent a developer installs manually.

Does WebMCP work in Chrome, Safari or Firefox now?

Support is behind flags and early previews; consult the implementation-status page in the WebMCP repository rather than assuming. The declarative form degrades gracefully: unsupported browsers see a normal form.