Make your site legible to agents
Agents work from the same things people rely on: clear labels, honest links, visible state, and predictable flows. Start there and every visitor benefits. Open standards can take the experience further.
Start with what works for everyone
The highest-leverage work is ordinary web craft: semantic structure an agent can understand and a person can trust.
- Markup
Real semantic HTML
Use a real button, not a div with an onclick. Real labels, real roles. Good for agents, good for screen readers, good for search.
- Links
Stable handles and real links
Persistent element ids and real anchor hrefs mean an agent, and a user, can find the same thing tomorrow.
A manual, not a script
A web skill is a plain-English SKILL.md that teaches an agent how to get one thing done on one site. It contains no code, and it is never executed. Frontmatter declares what it may do; the body is prose the agent reads.
name- The slug the skill is addressed by, unique for the site.
description- One paragraph telling the agent when to reach for this skill, and when not to.
runtime- browser for a skill that drives a page. Skylark ignores the rest.
permissions- What the skill may do. An empty list is a real answer: knowledge only.
scope- The URL patterns the skill applies to. Outside them it is never offered.
triggers- How it surfaces: a url_pattern, a host, or a described user intent.
version- Bumped when the body changes, so a stale copy is visible.
---
name: cancel-subscription
description: >-
Cancels a recurring subscription. Drives the cancel flow and stops at
the final confirm, handing the consequential last click to the user.
runtime: browser
permissions:
- page:read
- page:act
- navigate
scope:
- https://billing.acme.example/account/subscriptions/*
triggers:
- kind: url_pattern
pattern: https://billing.acme.example/account/subscriptions/*
- kind: intent
description: cancel my subscription
version: 1.0.0
---
# Cancel subscription
This is a consequential, hard-to-reverse action. Treat the final confirm
click as gated.
1. Confirm you are on a subscriptions page. If you are not, ask the user
where their subscriptions are. Do not navigate there yourself.
2. List each subscription: product, plan, renewal date, amount, status.
If more than one is active and the user did not say which, ask.
3. Click through to the cancel flow. Use the element reference from the
snapshot, never a hand-written selector: selectors drift across A/B
tests.
4. Before the final confirming click, summarise what will be cancelled,
the effective end date, and any retention offer being declined. Wait
for an explicit yes.
5. Verify the status actually changed, and quote the confirmation back.
What a skill actually does
Four worked examples. Every host below is an .example domain, because these are written by us to show the shape of the format. None is a real published skill.
-
billing.acme.example
Cancel a subscription
Finds the right subscription, drives whichever confirmation pattern the site shows, and reads the retention offer rather than accepting it.
page:readpage:actnavigate
Stops before the final confirm. Consequence is not the same as capability, so the last click stays with the user however the permissions read.
-
shop.storefront.example
Fill a guest checkout
Fills shipping and contact details the user supplied, across whichever steps the checkout wizard uses.
page:readpage:act
Hands the payment step back. It holds no navigate permission, so it cannot wander out of the checkout.
-
billing.acme.example
Explain an invoice
Reads a bill and explains the charges, the proration, and what changed since last month, in plain language.
Knowledge only
Knowledge only. The empty permission list is the proof: it can be read into context, but it drives nothing.
-
developers.acme.example
Search API reference docs
Knows how the documentation is organised, which version selector matters, and where the changelog lives.
Knowledge only
Prefers the site’s remote MCP server for live symbol lookup when the user has enabled it, and falls back to reading the page.
Everything a skill may ask for, in seven words
Seven verbs, and nothing outside the list is granted. A skill that asks for a word Skylark does not recognise does not get the benefit of the doubt: the request is dropped.
-
page:readPassiveRead the page
See the content and structure of the page you are on.
-
page:actActiveAct on the page
Click, type, and interact with controls on the page.
-
navigateActiveNavigate
Follow links and move backwards and forwards within the site.
-
tabsSensitiveSee your tabs
List, open, switch between, and close tabs.
-
network:readSensitiveRead network traffic
Inspect requests and responses, which can include tokens.
-
js:evaluateHighRun JavaScript
Execute arbitrary code in the page, with access to cookies.
-
network:interceptHighIntercept network traffic
Modify or block the requests a page makes.
An empty permission list is a real answer. A knowledge-only skill is read into the agent’s context and drives nothing at all.
The ceiling matters more than the badge
A badge answers one question: do we know who published this? It is an identity claim and never a safety claim. A skill from a verified publisher can still be wrong.
-
communitypage:read, page:act, navigateNo badge
Anyone can publish. Nothing about the publisher has been checked, and the absence of a badge is the honest way to say so.
-
domainAdds tabs and network:readVerified domain
The publisher proved they control the host, by serving a proof from the origin or by DNS.
-
partnerAdds tabs and network:readVerified organisation
A human confirmed the organisation behind the publisher.
-
officialThe full vocabulary, including js:evaluateSkylark
Written and maintained by the Skylark team.
A site-published skill is capped at powers the site already holds over its own page. Granting those adds nothing the origin could not already do. The powers a site does not have, such as your other tabs, need a human to have vouched for the publisher. How verification works
Three open standards
When you want an agent to do more than infer, publish the instructions or tools that remove the guesswork.
- Documentation
Knowledge skills
Ship a markdown manual the agent reads as you wrote it, instead of scraping the page.
- Page functions
WebMCP
Hand the agent typed page functions. The page offers a function and the agent calls it, no DOM scraping.
- Server tools
Remote MCP
Expose tools at /.well-known/mcp.json. Skylark discovers them and wires them into the agent loop.
Offered is not enabled
Being ready for agents never means silent automation. The user remains the decision-maker.
- Consent
Offered is not enabled
An address-bar signal tells the user a skill is available. Nothing runs without a click.
- Trust tiers
Three trust tiers
Read, act, and pay live at different trust levels. The user decides what each skill may do.
- Capability
Capability is not consequence
A skill can click a button. It cannot quietly buy. Dangerous paths need explicit consent.
Publish on your own domain. It beats submitting.
A skill at your own /.well-known/agent-skills/index.json is authoritative
for your host, it verifies your domain by the fact of being served from it, and it
works for agents that have never heard of any directory. The directory is for
discovery and search, not distribution.
WebMCP works in Skylark because it is a Chromium fork. The standard itself is still contested, so it always ships behind your click.