Skip to content
Skylark Skills
Submit a skill

Web skills

A web skill is a markdown file that tells an agent how to get one thing done on one site. Not code, not configuration. The same thing you would write for a new colleague on their first day, in the same words.

The problem it solves

An agent arriving at your site knows nothing. It sees a page, guesses which control does what, and finds out by clicking. On a search box that is fine. On a cancellation flow with a retention offer, a type-to-confirm field, and a low-contrast "continue anyway" link, it is a coin toss, and the failure lands on your support team.

You already know how that flow works. Writing it down converts a guess into a procedure.

What it looks like

YAML frontmatter declaring what the skill may do, then plain prose. This is a real example, of a shape you can copy.

---
name: cancel-subscription
description: >-
  Cancels a recurring subscription on Acme Billing. Drives the cancel
  flow and stops at the final confirm, handing the consequential last
  click back to the user.
runtime: browser
permissions:
  - page:read
  - page:act
  - navigate
scope:
  - https://billing.acme.example/account/subscriptions/*
version: 1.0.0
---

# Cancel subscription

## Identify the target

1. From the page snapshot, list each subscription row: product, plan,
   renewal date, amount, status.
2. If more than one is active and the user did not say which, show the
   list and ask. Do not choose for them.

## Drive the flow

3. Click the subscription's **Manage** control. Use the interactive
   element reference from the snapshot, never a CSS selector: our class
   names change with every A/B test.
4. We show one of three confirmation patterns. A retention offer is one
   of them. Do not accept it on the user's behalf.

## Stop here

5. Summarise what will be cancelled and the effective date, then wait
   for an explicit yes before the final click.

The three things that make one good

Name controls, not selectors

Write "the Manage button on the subscription row", not.sub-row > .btn-2. The agent reads your page as an accessibility tree and addresses controls by a stable reference. Your class names change; your visible labels mostly do not. A skill written in selectors breaks on your next deploy and you will not notice.

Say where to stop

The most valuable line in most skills is the one that says do not click yet. Payments, cancellations, deletions, anything carrying personal details: write that the agent must summarise and wait. The browser enforces a confirmation there regardless, but a skill that expects it produces a far better handover than one the guardrail interrupts.

Describe the variants you actually ship

If you run three checkout experiments, say so and describe all three. This is the knowledge an outsider cannot obtain and cannot guess, and it is the difference between a skill that works for 60% of your users and one that works for all of them.

What it cannot do

Be straight about the limits. A skill contains no code, so it cannot compute anything, cannot call your API, and cannot fix a page that is genuinely unusable. It is instructions for driving your UI, which means it inherits every weakness of driving your UI. If your interface is hostile, a skill makes an agent slightly better at struggling with it.

It also cannot grant an agent anything. Permissions gate which tools it may use, capped at what your site can already do to its own page. Publishing a skill does not hand out power; it spends power the user already granted, more precisely.

Publishing

Two files on your own domain: an index at/.well-known/agent-skills/index.json and the skill itself. Full walkthrough on the publish page.

Publishing on your own domain is better than submitting here, and we would rather you did that. It makes your copy authoritative, it verifies your domain automatically because only you can serve from it, and it works for agents that have never heard of this directory.

How to publishRead real skills

The specifications