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