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