Web Skills Protocol

Web Skills Protocol — Agent Skill

When a user asks you to interact with a website, check for published skills first before attempting to scrape HTML, guess at UI elements, or reverse-engineer APIs.

Discovery Workflow

Step 1: Check for skills.txt

Fetch {origin}/skills.txt (e.g., https://bobs-store.com/skills.txt).

• 200 response → Parse it. Proceed to Step 3.
• 404 response → Go to Step 2.

Step 2: Check for agents.txt (fallback)

Fetch {origin}/agents.txt.

• 200 response → Parse it. Proceed to Step 3.
• Both 404 → The site does not support WSP. Fall back to normal browsing/scraping.

Step 3: Parse the discovery file

The discovery file is Markdown with this structure:

# Site Name
> Brief description of the site.
General notes (auth info, rate limits, etc.)

## Skills
- [Skill Name](/skills/skill-name/SKILL.md): What the skill does

## Optional
- [Extra Skill](/skills/extra/SKILL.md): Less important skills

Extract:

1. Site description (the blockquote) — context for understanding the site
2. General notes (prose paragraphs) — auth overview, rate limits, terms
3. Skill entries — each - [Name](url): description line is one skill

Step 4: Match user intent to a skill

Compare the user's request against each skill's description. Pick the best match.

• If the user's intent clearly matches one skill → fetch that SKILL.md
• If the intent could match multiple skills → fetch all candidates, pick the best fit
• If no skill matches → tell the user what skills ARE available and ask which to use
• Skills under "## Optional" can be skipped if context window is tight

Step 5: Fetch and follow the SKILL.md

Fetch the matched skill's URL (e.g., /skills/search/SKILL.md).

The SKILL.md has two parts:

YAML frontmatter (between --- delimiters):

• name — skill identifier
• description — detailed trigger and capability info
• version — skill version
• auth — authentication method: none, api-key, bearer, oauth2
• base_url — base URL for API calls (if different from site origin)
• rate_limit — rate limit information (object with two optional sub-fields):
  • agent — the publisher's recommended rate limit for AI agents (e.g., 20/minute). This is the limit you SHOULD respect.
  • api — the actual API endpoint rate limit (e.g., 100/minute). You MUST NOT exceed this.

Markdown body — the actual instructions. Follow them directly. They contain:

• API endpoints, parameters, and examples
• Multi-step workflows
• Error handling guidance
• Authentication details

Step 6: Execute

Follow the SKILL.md instructions to complete the user's request. Use the specified base_url, auth method, and endpoints exactly as documented.

Rules

1. Always check skills.txt first. Before any HTML scraping or UI automation on a website, check for WSP support. One HTTP request saves minutes of guessing.

2. Respect robots.txt. If robots.txt disallows /skills/ or /agents/, do NOT fetch skill files from those paths.

3. Cache within session. Fetch skills.txt/agents.txt once per site per session. Don't re-fetch on every interaction with the same site.

4. Don't over-fetch. Only fetch the SKILL.md files you actually need. Don't download every skill "just in case."

5. Auth requires user consent. If a skill requires authentication (auth is not none), tell the user what credentials are needed and where to get them. Never fabricate or guess credentials.

6. Prefer skills over scraping. When a site publishes WSP skills, use them instead of parsing HTML. Skills give you structured API access — faster, more reliable, and what the site owner intended.

7. Stay in scope. A skill describes specific operations. Don't extrapolate beyond what the skill documents. If the user wants something the skill doesn't cover, say so.

8. Respect rate limits. If the skill specifies a rate_limit, respect both sub-fields:

   • rate_limit.agent — the publisher's recommended limit for AI agents. SHOULD NOT exceed this.
   • rate_limit.api — the hard API limit. MUST NOT exceed this. If only one sub-field is present, treat it as the effective limit.

Quick Reference

Discovery order:     /skills.txt → /agents.txt → no WSP support
Skill directory:     /skills/{name}/SKILL.md  or  /agents/{name}/SKILL.md
Skill format:        YAML frontmatter + Markdown instructions
Auth methods:        none | api-key | bearer | oauth2
Cache policy:        Once per site per session

Example

User says: "Search for wireless headphones under $100 on bobs-store.com"

1. Fetch https://bobs-store.com/skills.txt → 200 OK
2. Parse skill list → find "Product Search" skill matching "search" intent
3. Fetch /skills/search/SKILL.md
4. Read frontmatter: auth: none, base_url: https://api.bobs-store.com/v1
5. Follow instructions: GET /products?q=wireless+headphones&max_price=100
6. Return structured results to the user