Skill: 0xtresser/web-skills-protocol (version 1.0.0)

--- name: web-skills-protocol description: > Auto-discover and use Web Skills Protocol (WSP) skills when interacting with websites. Use this skill whenever the user asks you to interact with, use, or perform actions on a website or web service — such as searching a site, placing an order, deploying an app, or calling a web API. Before scraping HTML or guessing at interfaces, check if the site publishes a skills.txt or agents.txt file that teaches you how to use it properly. If a website has complex elements (e.g., heavy JavaScript, interactive UIs), activating this skill can also help you understand the site's purpose and capabilities. Do NOT use for local file operations or non-web tasks. version: 1.0.0 --- # 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

path: README.md
content: # Web Skills Protocol

> **skills.txt** — Teach AI agents how to use your website.

English | [中文](README_ZH.md)

---

In 1994, `robots.txt` told web crawlers what **not** to do.

In 2024, `llms.txt` told LLMs what content to **read**.

In 2026, `skills.txt` (or `agents.txt`) teaches AI agents how to **act**.

The **Web Skills Protocol (WSP)** is an open standard for websites to publish skill files that teach AI agents how to interact with the site — its APIs, workflows, and capabilities — instead of scraping HTML and guessing.

**WSP does not invent a new format.** AI agent skills — Markdown files with YAML metadata that teach agents how to perform tasks — are already an established standard in the AI agent ecosystem (used by Claude, OpenClaw, and others). WSP simply brings this existing skill format to the web by adding a discovery layer: a `skills.txt` file that tells agents which skills a website offers, just like `robots.txt` tells crawlers which pages to avoid.

## The Problem

AI agents are visiting your website right now. They're parsing HTML, guessing at buttons, and reverse-engineering your API from network traffic. It's fragile, slow, and breaks constantly.

Websites have no standard way to say: *"Hey agent, here's how to actually use us."*

## The Solution

Drop a `skills.txt` (or `agents.txt`) file on your site root. List your capabilities. Publish skill definitions in `/skills/` (or `/agents/`). Done.

```
your-website.com/
├── skills.txt              ← Discovery file (or agents.txt)
└── skills/                 ← Skills directory (or /agents/)
    ├── search/
    │   └── SKILL.md        ← "Here's how to search our products"
    └── order/
        └── SKILL.md        ← "Here's how to place an order"
```

WSP also supports an **alternative convention** using `agents.txt` and `/agents/` — same protocol, same format, different name. Use whichever feels natural. AI agents check both.

AI agents check `skills.txt` (or `agents.txt`) first, find the right skill, and follow your instructions — not their guesses.

## Why Not a New Format?

AI agent skills already exist. Thousands of skills are published and used daily by AI agents like Claude — each one a simple `SKILL.md` file with YAML frontmatter (name, description, version) and Markdown instructions. This format is proven, adopted, and works.

WSP inherits this standard as-is. The only addition is a **web discovery mechanism**:

```
Existing standard:  SKILL.md (YAML frontmatter + Markdown instructions)
WSP adds:           skills.txt → points agents to the right SKILL.md files
```

Think of it this way: WSP is to agent skills what RSS was to XML — not a new format, but a well-known location and discovery convention on top of what already works.

## The Evolution

```
robots.txt (1994)  →  "Dear robot, don't crawl /admin"          →  Access Control
llms.txt   (2024)  →  "Dear LLM, here's our documentation"      →  Content
skills.txt (2026)  →  "Dear agent, here's how to use our API"   →  Capabilities
```

## Install

Add WSP auto-discovery skill to your AI agent — one command:

**OpenClaw**

```bash
mkdir -p ~/.openclaw/workspace/skills/web-skills-protocol && curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  -o ~/.openclaw/workspace/skills/web-skills-protocol/SKILL.md
```

**OpenCode**

```bash
mkdir -p ~/.claude/skills/web-skills-protocol && curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  -o ~/.claude/skills/web-skills-protocol/SKILL.md
```

**Claude Code**

```bash
mkdir -p ~/.claude/skills/web-skills-protocol && curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  -o ~/.claude/skills/web-skills-protocol/SKILL.md
```

**Codex (OpenAI)**

Codex reads instructions from `AGENTS.md`. Append the skill to your project:

```bash
curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  >> AGENTS.md
```


## Quick Start

### 1. Create `/skills.txt` (or `/agents.txt`)

```markdown
# Bob's Online Store

> E-commerce platform for electronics and gadgets.

Product search is open (no auth). Other endpoints require an API key — get one at https://bobs-store.com/developers.

## Skills

- [Product Search](/skills/search/SKILL.md): Search products by keyword, category, or price range
- [Place Order](/skills/order/SKILL.md): Add items to cart and complete checkout via API
```

### 2. Create a Skill

`/skills/search/SKILL.md` (or `/agents/search/SKILL.md`):

```markdown
---
name: search
description: >
  Search and browse products in Bob's Online Store catalog.
  Use when the user wants to find products by keyword, category, price, or brand.
version: 1.0.0
auth: none
base_url: https://api.bobs-store.com/v1
---

# Product Search

## Endpoint

GET /products

## Parameters

| Parameter  | Type   | Required | Description                     |
|------------|--------|----------|---------------------------------|
| q          | string | yes      | Search query                    |
| category   | string | no       | Filter by category              |
| min_price  | number | no       | Minimum price                   |
| max_price  | number | no       | Maximum price                   |
| sort       | string | no       | Sort by: relevance, price, rating |
| page       | number | no       | Page number (default: 1)        |

## Example

Request:
​```
GET /products?q=wireless+headphones&sort=rating&max_price=100
​```

Response:
​```json
{
  "products": [
    {
      "id": "prod_8x7k",
      "name": "SoundWave Pro Wireless Headphones",
      "price": 79.99,
      "rating": 4.7,
      "in_stock": true,
      "url": "https://bobs-store.com/products/prod_8x7k"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}
​```
```

That's it. An AI agent visiting your site will:

1. Fetch `/skills.txt` (or `/agents.txt`) → discover available skills
2. Match user intent → pick the right skill
3. Follow your SKILL.md → call your API correctly

## skills.txt Format

The discovery file has a **fixed structure** — not free-form Markdown:

```
# {Site Name}                          ← H1: REQUIRED. Exactly one.

> {Site description}                   ← Blockquote: RECOMMENDED.

{General notes: auth, rate limits...}  ← Prose: OPTIONAL.

## Skills                              ← H2: REQUIRED. At least one section.

- [Skill Name](url): Description      ← List entry: REQUIRED format.
- [Another Skill](url): Description

## Optional                            ← H2 "Optional": agents may skip these.

- [Extra Skill](url): Description
```

**Rules:**

| Element | Format | Required |
|---------|--------|----------|
| Site name | `# Name` (H1) | Yes — exactly one |
| Description | `> text` (blockquote) | Recommended |
| Prose | Paragraphs | No |
| Skill section | `## Section Name` (H2) | Yes — at least one |
| Skill entry | `- [Name](path/SKILL.md): description` | Yes — at least one per section |

The H2 section `## Optional` has special meaning: agents may skip these skills when context is limited. All other H2 sections are treated as primary.

## SKILL.md Format

Each skill file is a standard **AgentSkills** document — the same `SKILL.md` format already used by AI agent platforms (Claude, OpenClaw, and others). WSP does not modify this format.

- **YAML frontmatter** (`---`): `name`, `description`, `version` (required) + optional fields like `auth`, `base_url`, `rate_limit`
  - `rate_limit` is an object with two optional sub-fields: `agent` (recommended limit for AI agents, e.g., `20/minute`) and `api` (actual API rate limit, e.g., `100/minute`)
- **Markdown body**: Instructions for the agent — endpoints, parameters, examples, workflows

If you’ve written an agent skill before, you already know how to write a web skill. See [examples/](examples/) for complete samples.

## For Website Owners

**Why publish skills?**

- **Control the narrative.** Define how AI agents use your site — don't let them guess.
- **Replace scraping.** Structured skills are faster and more reliable than HTML parsing.
- **Reduce load.** One API call beats 50 page fetches.
- **Monetize agent traffic.** Require API keys. Track usage. Offer premium tiers.
- **Progressive adoption.** Start with one `skills.txt` (or `agents.txt`), add skills over time.

## For AI Agent Developers

**Why check for skills?**

- **Structured instructions** instead of parsing unpredictable HTML.
- **Auto-discovery** — one fetch to `/skills.txt` (or `/agents.txt`) reveals all capabilities.
- **Reliable integrations** — follow the site's official instructions, not brittle hacks.
- **Better results** — API calls return structured data, not rendered web pages.

Install the [web-skills-protocol agent skill](skill/SKILL.md) to make your agent automatically discover and use published skills.

## Dual-Path Compatibility

WSP supports two naming conventions — use whichever feels right:

| Component | Primary | Alternative |
|-----------|---------|-------------|
| Discovery file | `/skills.txt` | `/agents.txt` |
| Skills directory | `/skills/` | `/agents/` |
| Skill document | `/skills/{name}/SKILL.md` | `/agents/{name}/SKILL.md` |

Both conventions use the **exact same format**. `skills.txt` frames it as *"what the site can teach"*. `agents.txt` mirrors the `robots.txt` naming — *"talking to agents"*.

**For website owners:** Pick one convention and use it consistently.
**For AI agent developers:** Your agent MUST check both (`skills.txt` first, then `agents.txt`).

See [SPEC.md](SPEC.md) for the full dual-path discovery algorithm.

## Relationship to Other Standards

| Standard     | Purpose                              | Relationship                   |
|-------------|--------------------------------------|--------------------------------|
| robots.txt  | Access control for crawlers          | WSP does NOT override robots.txt. They coexist. |
| llms.txt    | Content summary for LLMs            | Complementary. llms.txt = read. skills.txt/agents.txt = act. |
| OpenAPI     | API schema for developers            | Skills MAY reference OpenAPI specs for detail. |
| MCP         | Runtime protocol for AI tools        | WSP is web-native discovery; MCP is runtime transport. |
| sitemap.xml | Page index for search engines        | skills.txt/agents.txt is a capability index for AI agents. |

## Project Structure

```
Web-Skills-Protocol/
├── README.md           ← You are here
├── README_ZH.md        ← 中文说明
├── SPEC.md             ← Formal protocol specification
├── skill/              ← Agent skill (install this to auto-discover web skills)
│   └── SKILL.md
└── examples/           ← Example implementations
    ├── bobs-store/     ← E-commerce example
    └── devtools-saas/  ← SaaS platform example
```

## Specification

See [SPEC.md](SPEC.md) for the complete protocol specification.

## Live Example

[**awesomeai.info**](https://www.awesomeai.info/) — A dashboard tracking 2800+ AI GitHub repositories and OpenClaw agent skills. This site has adopted WSP in production.

Try it yourself:

```bash
# 1. Discover what the site can do
curl https://www.awesomeai.info/skills.txt

# 2. Read a specific skill
curl https://www.awesomeai.info/skills/explore-ai-repos/SKILL.md

# 3. Call the API as the skill describes
curl "https://awesomeai.info/api/repos?q=llm&sort=stars&pageSize=5"
```

The site publishes two skills — both public, no auth required:

| Skill | Endpoint | What it does |
|-------|----------|--------------|
| [explore-ai-repos](https://www.awesomeai.info/skills/explore-ai-repos/SKILL.md) | `GET /api/repos` | Search/filter AI repositories by keyword, stars, AI score, growth trends |
| [explore-ai-skills](https://www.awesomeai.info/skills/explore-ai-skills/SKILL.md) | `GET /api/skills` | Search/browse OpenClaw agent skills by category, keyword, popularity |

This is what WSP looks like in the real world — a `skills.txt` file and a few `SKILL.md` files, and any AI agent can immediately understand and use the site.

## Examples

See [examples/](examples/) for reference implementations (fictional stores and SaaS platforms).

## Contributing

This is an early-stage open standard. Contributions welcome:

- **Spec feedback** — Open an issue to discuss protocol design
- **Reference implementations** — Add examples for different site types
- **Agent integrations** — Build skills.txt (or agents.txt) support into your AI agent
- **Adopt it** — Publish skills.txt (or agents.txt) on your website

## License

The Web Skills Protocol specification is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).

Example code and the agent skill are licensed under [MIT](https://opensource.org/licenses/MIT).


path: README_ZH.md
content: # Web Skills Protocol

Github: https://github.com/0xtresser/Web-Skills-Protocol

> **skills.txt** — 教 AI 智能体如何使用你的网站。

[English](README.md) | 中文

---

1994 年，`robots.txt` 告诉爬虫**不要**做什么。

2024 年，`llms.txt` 告诉大语言模型该**读**什么内容。

2026 年，`skills.txt`（或 `agents.txt`）教 AI 智能体如何去**操作**。

**Web Skills Protocol (WSP)** 是一个开放标准，让网站发布技能文件（skill files），教 AI 智能体如何与网站交互——包括 API 调用、操作流程和功能说明——而不是让 AI 去抓取 HTML 猜测。

**WSP 没有发明新格式。** AI 智能体技能（agent skill）——即包含 YAML 元数据和 Markdown 指令的文件，用于教 AI 如何执行任务——已经是 AI 智能体生态中的既有标准（被 Claude、OpenClaw 等广泛使用）。WSP 只是把这个已有的技能格式搬到了 Web 上，加了一层发现机制：一个 `skills.txt` 文件告诉智能体网站提供哪些技能，就像 `robots.txt` 告诉爬虫哪些页面不要访问一样。

## 问题

AI 智能体正在访问你的网站。它们解析 HTML、猜测按钮、通过抓包逆向你的 API。这种方式脆弱、低效、而且经常挂掉。

网站没有一种标准方式来告诉 AI：*「嘿，这才是正确使用我的方法。」*

## 解决方案

在网站根目录放一个 `skills.txt`（或 `agents.txt`）文件，列出你的能力，把技能定义发布在 `/skills/`（或 `/agents/`）目录下。搞定。

```
your-website.com/
├── skills.txt              ← 发现文件（或 agents.txt）
└── skills/                 ← 技能目录（或 /agents/）
    ├── search/
    │   └── SKILL.md        ← 「这是搜索商品的方法」
    └── order/
        └── SKILL.md        ← 「这是下单的方法」
```

WSP 同时支持**替代命名**：`agents.txt` 和 `/agents/`——同样的协议，同样的格式，不同的名字。用哪个都行，AI 智能体两个都会检查。

AI 智能体先检查 `skills.txt`（或 `agents.txt`），找到合适的技能，然后按你的说明操作——而不是自己瞎猜。

## 为什么不是新格式？

AI 智能体技能已经存在。数以千计的技能每天被 AI 智能体（如 Claude）发布和使用——每个技能就是一个简单的 `SKILL.md` 文件，包含 YAML frontmatter（name、description、version）和 Markdown 指令。这个格式已经被验证、被采纳、能工作。

WSP 原样继承了这个标准。唯一的新增是一个 **Web 发现机制**：

```
已有标准：  SKILL.md（YAML frontmatter + Markdown 指令）
WSP 新增：  skills.txt → 告诉智能体去哪找对应的 SKILL.md
```

换个比方：WSP 之于 agent skill，就像 RSS 之于 XML——不是新格式，而是在已有格式上加了一个约定的位置和发现方式。

## 演进历程

```
robots.txt (1994)  →  「亲爱的机器人，不要爬 /admin」          →  访问控制
llms.txt   (2024)  →  「亲爱的 LLM，这是我们的文档」          →  内容
skills.txt (2026)  →  「亲爱的智能体，这是调用 API 的方法」   →  能力
```

## 安装

一行命令为你的 AI 智能体添加 WSP 自动发现能力：

**OpenClaw**

```bash
mkdir -p ~/.openclaw/workspace/skills/web-skills-protocol && curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  -o ~/.openclaw/workspace/skills/web-skills-protocol/SKILL.md
```

**OpenCode**

```bash
mkdir -p ~/.claude/skills/web-skills-protocol && curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  -o ~/.claude/skills/web-skills-protocol/SKILL.md
```

**Claude Code**

```bash
mkdir -p ~/.claude/skills/web-skills-protocol && curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  -o ~/.claude/skills/web-skills-protocol/SKILL.md
```

**Codex (OpenAI)**

Codex 从 `AGENTS.md` 读取指令。将技能追加到你的项目：

```bash
curl -sL \
  https://raw.githubusercontent.com/0xtresser/Web-Skills-Protocol/main/skill/SKILL.md \
  >> AGENTS.md
```


## 快速开始

### 1. 创建 `/skills.txt`（或 `/agents.txt`）

```markdown
# Bob's Online Store

> 电子产品和数码配件的电商平台。

商品搜索无需认证。其他端点需要 API Key——在 https://bobs-store.com/developers 获取。

## Skills

- [Product Search](/skills/search/SKILL.md): 按关键词、分类或价格区间搜索商品
- [Place Order](/skills/order/SKILL.md): 添加购物车并通过 API 完成下单
```

### 2. 创建技能文件

`/skills/search/SKILL.md`（或 `/agents/search/SKILL.md`）:

```markdown
---
name: search
description: >
  Search and browse products in Bob's Online Store catalog.
  Use when the user wants to find products by keyword, category, price, or brand.
version: 1.0.0
auth: none
base_url: https://api.bobs-store.com/v1
---

# Product Search

## Endpoint

GET /products

## Parameters

| Parameter  | Type   | Required | Description                     |
|------------|--------|----------|---------------------------------|
| q          | string | yes      | Search query                    |
| category   | string | no       | Filter by category              |
| min_price  | number | no       | Minimum price                   |
| max_price  | number | no       | Maximum price                   |
| sort       | string | no       | Sort by: relevance, price, rating |
| page       | number | no       | Page number (default: 1)        |

## Example

Request:
​```
GET /products?q=wireless+headphones&sort=rating&max_price=100
​```

Response:
​```json
{
  "products": [
    {
      "id": "prod_8x7k",
      "name": "SoundWave Pro Wireless Headphones",
      "price": 79.99,
      "rating": 4.7,
      "in_stock": true
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}
​```
```

就这样。AI 智能体访问你的网站时会：

1. 获取 `/skills.txt`（或 `/agents.txt`）→ 发现可用技能
2. 匹配用户意图 → 选择合适的技能
3. 按照 SKILL.md 的说明 → 正确调用你的 API

## skills.txt 格式

发现文件有**固定的层级结构**——不是自由格式的 Markdown：

```
# {站点名称}                           ← H1：必须。恰好一个。

> {站点描述}                          ← 引用块：建议。

{通用信息：认证、频率限制...}       ← 正文：可选。

## Skills                              ← H2：必须。至少一个分组。

- [Skill Name](url): Description      ← 列表项：固定格式。
- [Another Skill](url): Description

## Optional                            ← H2 "Optional"：智能体可跳过。

- [Extra Skill](url): Description
```

**规则：**

| 元素 | 格式 | 是否必须 |
|------|------|---------|
| 站点名称 | `# 名称`（H1） | 是——恰好一个 |
| 描述 | `> 文本`（引用块） | 建议 |
| 正文 | 段落 | 否 |
| 技能分组 | `## 分组名`（H2） | 是——至少一个 |
| 技能条目 | `- [名称](path/SKILL.md): 描述` | 是——每个分组至少一个 |

H2 分组 `## Optional` 有特殊含义：智能体在上下文有限时可以跳过这些技能。其他 H2 分组均视为主要技能。

## SKILL.md 格式

每个技能文件是标准的 **AgentSkills** 文档——与 AI 智能体平台（Claude、OpenClaw 等）已在使用的 `SKILL.md` 格式完全一致。WSP 不修改这个格式。

- **YAML frontmatter**（`---`）：`name`、`description`、`version`（必填）+ 可选字段如 `auth`、`base_url`、`rate_limit`
  - `rate_limit` 是一个对象，包含两个可选子字段：`agent`（发布者建议的 AI 智能体频率限制，如 `20/minute`）和 `api`（实际 API 频率限制，如 `100/minute`）
- **Markdown 正文**：给智能体的指令——端点、参数、示例、工作流

如果你写过 agent skill，就已经知道怎么写 web skill 了。完整示例见 [examples/](examples/)。

## 双路径兼容

WSP 支持两种命名约定——选你喜欢的：

| 组件 | 主要约定 | 替代约定 |
|------|---------|---------|
| 发现文件 | `/skills.txt` | `/agents.txt` |
| 技能目录 | `/skills/` | `/agents/` |
| 技能文档 | `/skills/{name}/SKILL.md` | `/agents/{name}/SKILL.md` |

两种约定使用**完全相同的格式**。`skills.txt` 的视角是「网站能教什么」；`agents.txt` 沿用 `robots.txt` 的命名风格——「与智能体对话」。

**网站方：** 选一种约定，保持一致。
**AI 开发者：** 你的智能体必须两个都检查（先 `skills.txt`，再 `agents.txt`）。

## 适用场景

### 对网站主

**为什么要发布 skills？**

- **掌握主动权。** 定义 AI 智能体如何使用你的网站——别让它们瞎猜。
- **替代爬虫。** 结构化的 skill 比 HTML 解析更快、更可靠。
- **减少负载。** 一次 API 调用胜过 50 次页面抓取。
- **智能体流量变现。** 要求 API Key、追踪用量、提供付费层级。
- **渐进式接入。** 从一个 `skills.txt`（或 `agents.txt`）开始，逐步添加技能。

### 对 AI 开发者

**为什么要检查 skills？**

- **结构化指令**，不用解析不可预测的 HTML。
- **自动发现**——获取一次 `/skills.txt`（或 `/agents.txt`）就能知道所有能力。
- **可靠集成**——按照网站官方说明操作，而不是脆弱的 hack。
- **更好的结果**——API 返回结构化数据，而不是渲染后的网页。

安装 [web-skills-protocol 智能体技能](skill/SKILL.md)，让你的 AI 智能体自动发现和使用已发布的技能。

## 与其他标准的关系

| 标准          | 用途                   | 关系                                   |
|--------------|----------------------|----------------------------------------|
| robots.txt   | 爬虫访问控制            | WSP 不覆盖 robots.txt，两者共存。          |
| llms.txt     | 为 LLM 提供内容摘要     | 互补。llms.txt = 阅读，skills.txt/agents.txt = 操作。  |
| OpenAPI      | 面向开发者的 API 规范    | 技能可以引用 OpenAPI 规范来补充细节。        |
| MCP          | AI 工具的运行时协议      | WSP 是 Web 原生的发现标准；MCP 是运行时传输。 |
| sitemap.xml  | 搜索引擎的页面索引       | skills.txt/agents.txt 是面向 AI 智能体的能力索引。      |

## 项目结构

```
Web-Skills-Protocol/
├── README.md           ← English
├── README_ZH.md        ← 你在这里
├── SPEC.md             ← 正式协议规范
├── skill/              ← 智能体技能（安装后自动发现 web skills）
│   └── SKILL.md
└── examples/           ← 示例实现
    ├── bobs-store/     ← 电商示例
    └── devtools-saas/  ← SaaS 平台示例
```

## 规范

完整协议规范请参阅 [SPEC.md](SPEC.md)。

## 实际案例

[**awesomeai.info**](https://www.awesomeai.info/) — 追踪 2800+ 个 AI 相关 GitHub 仓库和 OpenClaw 智能体技能的数据看板。该网站已在生产环境采用 WSP。

亲自试试：

```bash
# 1. 发现网站能做什么
curl https://www.awesomeai.info/skills.txt

# 2. 查看具体技能
curl https://www.awesomeai.info/skills/explore-ai-repos/SKILL.md

# 3. 按照技能描述调用 API
curl "https://awesomeai.info/api/repos?q=llm&sort=stars&pageSize=5"
```

该网站发布了两个技能——均为公开接口，无需认证：

| 技能 | 接口 | 功能 |
|------|------|------|
| [explore-ai-repos](https://www.awesomeai.info/skills/explore-ai-repos/SKILL.md) | `GET /api/repos` | 按关键词、star 数、AI 评分、增长趋势搜索/筛选 AI 仓库 |
| [explore-ai-skills](https://www.awesomeai.info/skills/explore-ai-skills/SKILL.md) | `GET /api/skills` | 按分类、关键词、热度搜索/浏览 OpenClaw 智能体技能 |

这就是 WSP 在真实世界中的样子——一个 `skills.txt` 文件加几个 `SKILL.md`，任何 AI 智能体就能立即理解和使用这个网站。

## 示例

虚拟示例（电商和 SaaS 平台）请查看 [examples/](examples/) 目录。

## 参与贡献

这是一个早期阶段的开放标准，欢迎贡献：

- **规范反馈** — 提 issue 讨论协议设计
- **参考实现** — 为不同类型的网站添加示例
- **智能体集成** — 在你的 AI 智能体中加入 skills.txt（或 agents.txt）支持
- **采用它** — 在你的网站上发布 skills.txt（或 agents.txt）

## 许可证

Web Skills Protocol 规范采用 [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) 许可。

示例代码和智能体技能采用 [MIT](https://opensource.org/licenses/MIT) 许可。


path: SPEC.md
content: # Web Skills Protocol (WSP) — Specification v0.1

**Status:** Draft
**Date:** March 2026
**Author:** [To be assigned]
**URI:** `https://github.com/0xtresser/Web-Skills-Protocol`

---

## Abstract

The Web Skills Protocol (WSP) defines a standard mechanism for websites to publish structured skill files that teach AI agents how to interact with the site's capabilities. A website places a discovery file at `/skills.txt` (or alternatively `/agents.txt`) and individual skill definitions under a `/skills/` (or `/agents/`) directory. Each skill is a Markdown document containing metadata and instructions that enable AI agents to perform supported operations — such as searching products, placing orders, or deploying applications — through the site's official interfaces rather than through fragile HTML scraping.

Critically, WSP does not define a new skill document format. The `SKILL.md` format — YAML frontmatter with metadata plus Markdown body with instructions — is an existing standard already widely adopted in the AI agent ecosystem (Claude, OpenClaw, and others). WSP’s contribution is a **web discovery layer**: a well-known file (`skills.txt`/`agents.txt`) and directory convention (`/skills/`/`/agents/`) that allows websites to surface their capabilities to any conforming AI agent.

WSP supports **dual discovery paths** for maximum compatibility: both `skills.txt` and `agents.txt` are recognized as valid discovery files, and both `/skills/` and `/agents/` are recognized as valid skill directories. This allows publishers to choose the naming convention that best fits their mental model — whether "skills" (what the site can teach) or "agents" (who the site is talking to, mirroring `robots.txt`).

WSP is complementary to existing web standards: `robots.txt` governs access control, `llms.txt` provides content for reading, and `skills.txt`/`agents.txt` provides capabilities for action.

## 1. Introduction

### 1.1 Background

The web has evolved through three phases of machine interaction:

1. **Access control era (1994–):** `robots.txt` (RFC 9309) tells web crawlers which pages they may or may not access.
2. **Content era (2024–):** `llms.txt` provides curated, LLM-friendly content summaries for language models to read and understand.
3. **Capability era (2026–):** `skills.txt`/`agents.txt` teaches AI agents how to perform supported operations on a website.

As AI agents increasingly interact with websites on behalf of users, a gap exists between what a site offers and what an agent can reliably discover. Agents currently rely on HTML scraping, reverse-engineering network requests, or prompting users for manual steps. These methods are fragile, inefficient, and give website operators no control over how agents interact with their platforms.

### 1.2.1 What WSP Does NOT Do

WSP does not invent a new skill file format. The `SKILL.md` document format — consisting of YAML frontmatter (`name`, `description`, `version`, and optional fields) followed by a Markdown instruction body — is an existing, proven standard used by AI agent platforms. WSP inherits this format unchanged.

WSP’s sole innovation is the **discovery mechanism**: placing a `skills.txt` (or `agents.txt`) file at a website’s root to index available skills, analogous to how `robots.txt` indexes access rules and `sitemap.xml` indexes pages.

### 1.2 Problem Statement

- AI agents have no standard way to discover what operations a website supports.
- Websites have no standard way to communicate their capabilities to AI agents.
- HTML scraping is unreliable, resource-intensive, and breaks with UI changes.
- API documentation, when it exists, is designed for human developers — not for AI agents to consume at runtime.

### 1.3 Design Principles

1. **Inherit, don't invent.** The SKILL.md format is an existing standard. WSP reuses it unchanged and only adds a web discovery layer.
2. **Simplicity.** A single Markdown file at a well-known path is the minimum viable implementation.
3. **Progressive adoption.** Start with a single discovery file; add individual skill files as needed.
4. **Markdown-native.** Both discovery and skill files use Markdown, which is human-readable and LLM-friendly.
5. **CDN-friendly.** All files are static and independently cacheable.
6. **Composable.** WSP works alongside robots.txt, llms.txt, OpenAPI, and MCP without replacing any of them.
7. **Voluntary compliance.** Like robots.txt, WSP relies on good-faith adoption by both publishers and consumers.
8. **Dual-path compatibility.** Both `skills.txt`/`/skills/` and `agents.txt`/`/agents/` conventions are supported to maximize adoption.

## 2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

| Term | Definition |
|------|-----------|
| **Skill** | A structured document that teaches an AI agent how to perform a specific operation on a website. |
| **Discovery File** | A `skills.txt` or `agents.txt` file located at a website's root path, listing available skills. |
| **Skill Document** | An individual `SKILL.md` file containing metadata and instructions for one skill. |
| **Publisher** | The website or service that creates and hosts skill files. |
| **Consumer** | The AI agent or application that discovers and follows skill files. |
| **Skill Directory** | The `/skills/` or `/agents/` path on a website where individual skill subdirectories are organized. |

## 3. Discovery Mechanism

### 3.1 Discovery File Location

The discovery file MUST be located at one of the following root paths of the website's origin:

| Path | Convention | Notes |
|------|-----------|-------|
| `/skills.txt` | **Primary** | Describes what the site can teach. RECOMMENDED. |
| `/agents.txt` | **Alternative** | Mirrors `robots.txt` naming. Equally valid. |

Both paths follow the same format and are semantically equivalent. A publisher MUST serve at least one. A publisher MAY serve both (with identical content).

```
https://example.com/skills.txt    ← Primary convention
https://example.com/agents.txt    ← Alternative convention (same protocol)
```

A discovery file applies to a single origin. For websites with multiple subdomains, each subdomain MAY have its own discovery file.

#### Consumer Discovery Order

A conforming consumer MUST check for discovery files in the following order:

1. Fetch `{origin}/skills.txt`
2. If 404, fetch `{origin}/agents.txt`
3. If both return 404, the site does not support WSP

If a site serves both files, the consumer SHOULD use whichever it finds first (i.e., `skills.txt`).

### 3.2 Discovery File Format

The discovery file is a Markdown document with the following structure:

1. **H1 heading** (REQUIRED): The name of the site or service.
2. **Blockquote** (RECOMMENDED): A brief description of the site, containing key information for understanding the available skills.
3. **Prose sections** (OPTIONAL): Zero or more paragraphs providing general context — such as authentication overview, terms of use, or general notes.
4. **H2 sections** (REQUIRED): One or more sections containing skill lists.

Each skill list entry is a Markdown list item with the format:

```markdown
- [Skill Name](/skills/{skill-name}/SKILL.md): Brief description of the skill
```

Or, using the agents convention:

```markdown
- [Skill Name](/agents/{skill-name}/SKILL.md): Brief description of the skill
```

The link MUST be a relative or absolute URL pointing to the skill's `SKILL.md` file. The description after the colon SHOULD summarize what the skill does and when an agent should use it.

### 3.3 Special Sections

An H2 section titled "Optional" has special meaning: skills listed under this section MAY be skipped by consumers that need a shorter context or have limited capabilities. Publishers SHOULD use this section for secondary or advanced skills that are not essential for basic interaction.

### 3.4 Discovery File Examples

**Using the `/skills/` convention (skills.txt):**

```markdown
# Bob's Online Store

> Online store for electronics, gadgets, and accessories.

Product search is open (no auth required). All other endpoints require an API key. Get one at https://bobs-store.com/developers.
Rate limits: 100 requests/minute for search, 20 requests/minute for orders.

## Skills

- [Product Search](/skills/search/SKILL.md): Search and browse products by keyword, category, price range, or brand. Returns structured product data including prices, ratings, and availability.
- [Place Order](/skills/order/SKILL.md): Add items to cart, apply coupons, select shipping method, and complete checkout via API.
- [Track Order](/skills/tracking/SKILL.md): Check order status, estimated delivery, and tracking information.

## Optional

- [Product Reviews](/skills/reviews/SKILL.md): Read and submit product reviews and ratings.
- [Wishlist](/skills/wishlist/SKILL.md): Manage user wishlists.
```

**Using the `/agents/` convention (agents.txt):**

```markdown
# Bob's Online Store

> Online store for electronics, gadgets, and accessories.

Product search is open (no auth). API key required for other endpoints. Get one at https://bobs-store.com/developers.

## Skills

- [Product Search](/agents/search/SKILL.md): Search products by keyword, category, or price range.
- [Place Order](/agents/order/SKILL.md): Complete checkout via API.
```

Both formats are semantically identical — only the directory path differs.

### 3.5 Discovery Process

A consumer SHOULD follow this process when interacting with a website:

1. Fetch `{origin}/skills.txt`. If 404, fetch `{origin}/agents.txt`.
2. If the response status is 200 and the content is valid Markdown, parse the skill list.
3. If both return 404 or error, the site does not support WSP. The consumer SHOULD fall back to other interaction methods.
4. Match the user's intent against available skill descriptions.
5. Fetch the matching skill's `SKILL.md` file.
6. Follow the instructions in the skill document.

Consumers SHOULD cache the discovery file for the duration of a session or according to HTTP cache headers to avoid redundant fetches.

## 4. Skills Directory

### 4.1 Directory Location

Skills SHOULD be organized under one of the following paths at the website's origin:

| Path | Convention | Notes |
|------|-----------|-------|
| `/skills/` | **Primary** | RECOMMENDED. Consistent with `skills.txt`. |
| `/agents/` | **Alternative** | Consistent with `agents.txt`. Equally valid. |

The directory path SHOULD be consistent with the discovery file name:

- If using `skills.txt` → use `/skills/`
- If using `agents.txt` → use `/agents/`

However, the discovery file's skill entry links are authoritative — a consumer MUST follow the URLs specified in the discovery file regardless of which directory convention is used.

### 4.2 Directory Structure

Each skill occupies its own subdirectory:

```
/skills/ convention:                /agents/ convention:

/skills/                            /agents/
├── search/                         ├── search/
│   ├── SKILL.md        ← Required │   ├── SKILL.md        ← Required
│   ├── references/     ← Optional │   ├── references/     ← Optional
│   │   └── filters.md             │   │   └── filters.md
│   └── scripts/        ← Optional │   └── scripts/        ← Optional
│       └── bulk.py                 │       └── bulk.py
├── order/                          ├── order/
│   └── SKILL.md                    │   └── SKILL.md
└── tracking/                       └── tracking/
    └── SKILL.md                        └── SKILL.md
```

### 4.3 Subdirectory Naming

Skill subdirectory names MUST use kebab-case (lowercase with hyphens) and MUST match the `name` field in the skill's YAML frontmatter.

### 4.4 Auxiliary Files

Each skill subdirectory MAY contain additional resources:

| Directory      | Purpose                                       | Loaded by consumer? |
|---------------|-----------------------------------------------|---------------------|
| `references/` | Additional documentation, loaded on demand    | On demand           |
| `scripts/`    | Executable code for the agent to run          | On demand           |
| `assets/`     | Templates, images, and other output resources | As needed           |

Consumers SHOULD only fetch auxiliary files when explicitly referenced in the skill document.

## 5. Skill Document Format

### 5.1 File Name and Location

A skill document MUST be named `SKILL.md` and MUST be located in the skill's subdirectory:

```
/skills/{skill-name}/SKILL.md    ← Using /skills/ convention
/agents/{skill-name}/SKILL.md    ← Using /agents/ convention
```

The filename `SKILL.md` is the same regardless of which directory convention is used.

### 5.2 Structure

A skill document consists of two parts:

1. **YAML Frontmatter**: Metadata enclosed in `---` delimiters.
2. **Markdown Body**: Instructions for the AI agent.

### 5.3 YAML Frontmatter

#### Required Fields

| Field         | Type   | Description |
|--------------|--------|-------------|
| `name`       | string | Unique identifier for this skill. MUST be kebab-case. MUST match the subdirectory name. |
| `description`| string | A detailed description of what this skill does and when it should be triggered. This is the primary field consumers use to match user intent to skills. |
| `version`    | string | Semantic version of this skill (e.g., "1.0.0"). |

#### Optional Fields

| Field         | Type   | Description |
|--------------|--------|-------------|
| `author`     | string | Name of the publisher or organization. |
| `api_version`| string | Version of the underlying API this skill targets. |
| `auth`       | string | Authentication method: `none`, `api-key`, `bearer`, `oauth2`. |
| `rate_limit` | object | Rate limit information. Contains `agent` (recommended limit for AI agents) and/or `api` (underlying API rate limit). See below. |
| `base_url`   | string | Base URL for API calls, if different from the site origin. |
| `contact`    | string | Contact email or URL for skill-related issues. |

#### Example Frontmatter

```yaml
---
name: search
description: >
  Search and browse products in Bob's Online Store catalog.
  Use when the user wants to find products by keyword, category, price range,
  or brand. Returns structured product data including prices, ratings,
  and stock availability. Supports pagination and sorting.
version: 1.0.0
auth: none
rate_limit:
  agent: 20/minute
  api: 100/minute
base_url: https://api.bobs-store.com/v1
---
```

### 5.4 Markdown Body

The Markdown body contains instructions that teach the AI agent how to perform the skill. There is no required structure for the body, but the following sections are RECOMMENDED:

#### Recommended Sections

| Section              | Purpose                                         |
|---------------------|------------------------------------------------|
| Endpoint(s)         | HTTP method, path, and purpose of each endpoint |
| Parameters          | Request parameters with types and descriptions  |
| Request Examples    | Complete request examples with headers          |
| Response Format     | Response structure with field descriptions       |
| Error Handling      | Common error codes and how to handle them       |
| Workflow            | Multi-step processes with ordering              |
| Authentication      | How to authenticate (if not fully covered by frontmatter) |
| Notes / Constraints | Rate limits, pagination, special behaviors      |

#### Writing Guidelines

Publishers SHOULD follow these guidelines when writing skill documents:

1. **Be imperative.** Write instructions the agent can follow directly: "Send a GET request to..." not "The GET endpoint can be used to..."
2. **Use code blocks.** Show complete request/response examples.
3. **Only teach what's unique.** Do not explain HTTP, JSON, or general programming concepts. Focus on site-specific details.
4. **Keep it concise.** Aim for under 300 lines. Move detailed reference material to `references/`.
5. **Include error handling.** Show how to handle common errors (auth failures, rate limits, validation errors).
6. **Specify required vs optional parameters.** Use tables for clarity.

### 5.5 Description Field Guidelines

The `description` field is the most critical field in the frontmatter. It determines whether a consumer activates this skill for a given user request.

A good description MUST include:
- **What** the skill does (its primary function)
- **When** to use it (trigger conditions)
- **Specific scenarios** that should activate this skill

A good description SHOULD include:
- What the skill does **not** do (exclusion conditions)
- Key capabilities or limitations

Example of a good description:
```yaml
description: >
  Search and browse products in Bob's Online Store catalog. Use when the user
  wants to find products by keyword, category, price range, or brand.
  Returns structured product data including prices, ratings, and availability.
  Supports pagination and sorting. Do NOT use for order management or
  account operations — use the order or account skills instead.
```

Example of a bad description:
```yaml
description: Product search functionality.
```

## 6. Authentication and Authorization

### 6.1 Declaring Auth Requirements

Skills that require authentication MUST declare the auth method in the YAML frontmatter using the `auth` field.

| Auth Value  | Description                                             |
|-------------|---------------------------------------------------------|
| `none`      | No authentication required.                             |
| `api-key`   | Requires an API key, typically sent as a header or query parameter. |
| `bearer`    | Requires a Bearer token in the Authorization header.    |
| `oauth2`    | Requires OAuth 2.0 authentication flow.                |

### 6.2 Auth Details in Body

When `auth` is not `none`, the skill document body SHOULD include an "Authentication" section explaining:
- How to obtain credentials (link to developer portal, registration page)
- How to include credentials in requests (header name, parameter format)
- Token refresh procedures (for oauth2)

### 6.3 Security Requirements

Publishers MUST NOT embed actual credentials, API keys, or secrets in skill documents.

Consumers MUST NOT store or transmit credentials obtained through skill instructions without explicit user consent.

Consumers SHOULD prompt the user for credentials when a skill requires authentication, rather than attempting to bypass auth mechanisms.

## 7. Versioning

### 7.1 Skill Versioning

Individual skill documents MUST include a `version` field in the YAML frontmatter following Semantic Versioning (SemVer):

- **MAJOR** version: Incompatible changes to the skill's interface.
- **MINOR** version: Backward-compatible additions.
- **PATCH** version: Backward-compatible fixes.

### 7.2 Discovery File Versioning

The discovery file does not require a version field. Its content is implicitly versioned by the individual skill versions it references.

### 7.3 Change Notification

Publishers SHOULD update the `version` field in skill documents when making changes. There is no push notification mechanism; consumers discover changes by re-fetching skill documents.

## 8. Caching and Performance

### 8.1 Caching Behavior

All WSP files (discovery file and skill documents) are static resources and SHOULD be served with appropriate HTTP cache headers.

**Recommended cache durations:**

| Resource                  | Recommended Cache-Control          |
|--------------------------|-------------------------------------|
| skills.txt / agents.txt  | `public, max-age=3600` (1 hour)    |
| SKILL.md                 | `public, max-age=86400` (1 day)    |
| references/*             | `public, max-age=86400` (1 day)    |

### 8.2 Consumer Caching

Consumers SHOULD cache the discovery file for the duration of a user session. Within a single session, a consumer SHOULD NOT fetch `skills.txt`/`agents.txt` more than once for the same origin.

Consumers MAY cache individual skill documents across sessions, using standard HTTP caching mechanisms (ETag, Last-Modified).

### 8.3 File Size Limits

The discovery file SHOULD NOT exceed 50 KB.

Individual skill documents (`SKILL.md`) SHOULD NOT exceed 100 KB. For skill documents approaching this limit, publishers SHOULD move detailed content to `references/` files.

## 9. Relationship to Other Standards

### 9.1 robots.txt (RFC 9309)

WSP and robots.txt serve different purposes and MUST NOT conflict:

- `robots.txt` governs **access** — which paths crawlers may visit.
- `skills.txt`/`agents.txt` governs **capability** — how agents may interact with the site.

A website MAY publish both `robots.txt` and `skills.txt`/`agents.txt`. If `robots.txt` disallows access to `/skills/` or `/agents/`, consumers MUST respect that directive — the access control layer takes precedence.

### 9.2 llms.txt

WSP and llms.txt are complementary:

- `llms.txt` provides content for **reading** — documentation, explanations, context.
- `skills.txt`/`agents.txt` provides instructions for **acting** — API calls, workflows, operations.

A website MAY publish both. In fact, `llms.txt` can help an agent understand the site, while `skills.txt`/`agents.txt` enables the agent to operate on it.

### 9.3 OpenAPI / Swagger

Skills MAY reference OpenAPI specifications for detailed API schemas. WSP provides the "task workflow" layer above raw API documentation:

- OpenAPI describes endpoints, schemas, and parameters (the "what").
- WSP describes task workflows, decision logic, and best practices (the "how" and "when").

A skill document MAY include a reference to an OpenAPI spec:
```markdown
For complete API schema, see our [OpenAPI spec](https://api.example.com/openapi.json).
```

### 9.4 MCP (Model Context Protocol)

MCP is a runtime protocol for connecting AI agents to tools. WSP is a web-native discovery standard for publishing capabilities.

- WSP is **publisher-side** — the website defines its skills.
- MCP is **consumer-side** — the agent runtime connects to tool servers.

Skills published via WSP can be implemented as MCP tool servers, but WSP does not require MCP and functions independently.

### 9.5 sitemap.xml

`sitemap.xml` lists pages for search engine indexing. `skills.txt`/`agents.txt` lists capabilities for AI agent interaction. They serve different audiences and can coexist without conflict.

## 10. Conformance Requirements

### 10.1 Publisher Requirements

A conforming publisher:

- MUST serve the discovery file at `{origin}/skills.txt` and/or `{origin}/agents.txt` with a 200 status code and `text/plain` or `text/markdown` content type.
- MUST include at least one skill entry in the discovery file.
- MUST provide a valid `SKILL.md` file at the URL referenced in each skill entry.
- MUST include `name`, `description`, and `version` fields in each skill's YAML frontmatter.
- MUST ensure the `name` field matches the skill's subdirectory name.
- MUST NOT embed credentials or secrets in skill documents.
- SHOULD serve skill files with appropriate cache headers.
- SHOULD keep skill documents under 100 KB.

### 10.2 Consumer Requirements

A conforming consumer:

- MUST check for discovery files in order: `{origin}/skills.txt` first, then `{origin}/agents.txt`.
- MUST gracefully handle 404 responses (site does not support WSP).
- MUST respect `robots.txt` directives — if `/skills/` or `/agents/` is disallowed, do not fetch skill files.
- MUST validate YAML frontmatter before executing skill instructions.
- MUST NOT execute skill instructions that would bypass the site's stated authentication requirements.
- SHOULD cache the discovery file for the duration of a session.
- SHOULD match user intent against skill descriptions before fetching individual skill documents.
- SHOULD prefer skill-based interaction over HTML scraping when skills are available.

## 11. Security Considerations

### 11.1 Skill Injection

Skill documents contain instructions that AI agents follow. A compromised skill document could instruct an agent to:
- Exfiltrate user data to a third-party URL.
- Make unintended purchases or transactions.
- Bypass authentication or authorization controls.

Consumers SHOULD validate that skill documents only reference URLs within the publisher's origin or explicitly declared `base_url`. Consumers MUST prompt users before performing sensitive operations (payments, account changes, data deletion) regardless of skill instructions.

### 11.2 Content Integrity

Publishers MAY implement content integrity by serving skill files over HTTPS (RECOMMENDED) and providing checksums in the discovery file.

Consumers MUST fetch skill files over HTTPS in production environments. Consumers SHOULD warn users when fetching skills over plain HTTP.

### 11.3 Rate Limiting and Abuse

Skills MAY declare two types of rate limits in the `rate_limit` frontmatter field:

| Sub-field | Meaning |
|-----------|---------|
| `agent`   | The publisher's recommended rate limit for AI agents calling this skill. This is the limit agents SHOULD respect. It may be stricter than the API limit to prevent abuse or preserve resources for human users. |
| `api`     | The actual technical rate limit of the underlying API. If an agent exceeds this, requests will be rejected (HTTP 429). |

Consumers MUST NOT exceed `rate_limit.api` if declared. Consumers SHOULD NOT exceed `rate_limit.agent` if declared.

If only one sub-field is present, consumers SHOULD treat it as the effective limit. If both are present, `rate_limit.agent` takes precedence (it is typically the stricter of the two).

Publishers SHOULD implement server-side rate limiting in addition to declaring limits in skill documents, as consumer compliance is voluntary.

### 11.4 Scope Limitation

Skill documents describe supported operations. They do not grant additional permissions. A skill that describes an order API does not authorize the agent to place orders — the agent still needs valid credentials and user consent.

## 12. IANA Considerations

This section is reserved for future IANA registration if this specification progresses to an RFC.

Potential registrations:
- Well-Known URI: `/.well-known/skills` or `/.well-known/agents` (alternative discovery paths)
- Media Type: `text/markdown; profile="skill"` (skill-specific content type)

## 13. Examples

### 13.1 Minimal Discovery File

The simplest valid discovery file (as either `skills.txt` or `agents.txt`):

```markdown
# My Website

## Skills

- [Search](/skills/search/SKILL.md): Search site content
```

### 13.2 Complete skills.txt (using /skills/ convention)

```markdown
# DevTools Cloud

> Cloud deployment platform for web applications. Deploy from Git in seconds.
> Supports Node.js, Python, Go, and Rust.

Authentication via OAuth 2.0. Register at https://devtools.cloud/developers to obtain client credentials.

## Skills

- [Deploy Application](/skills/deploy/SKILL.md): Deploy web applications from Git repositories with automatic build detection and zero-downtime deployment.
- [Manage Domains](/skills/domains/SKILL.md): Add custom domains, configure DNS, and manage SSL certificates for deployed applications.
- [View Logs](/skills/logs/SKILL.md): Stream application logs, filter by severity, and search log history.

## Optional

- [Team Management](/skills/teams/SKILL.md): Invite team members, manage roles, and configure access permissions.
```

### 13.3 Complete agents.txt (using /agents/ convention)

```markdown
# DevTools Cloud

> Cloud deployment platform for web applications. Deploy from Git in seconds.

Auth: OAuth 2.0. Register at https://devtools.cloud/developers.

## Skills

- [Deploy Application](/agents/deploy/SKILL.md): Deploy web apps from Git with auto build detection.
- [Manage Domains](/agents/domains/SKILL.md): Custom domains, DNS, and SSL management.
- [View Logs](/agents/logs/SKILL.md): Stream and search application logs.
```

### 13.4 Complete SKILL.md

```markdown
---
name: deploy
description: >
  Deploy web applications to DevTools Cloud from Git repositories.
  Use when the user wants to deploy, ship, publish, or launch a web app.
  Supports Node.js, Python, Go, and Rust with automatic build detection.
  Handles zero-downtime deployments with automatic rollback on failure.
version: 2.1.0
auth: oauth2
rate_limit:
  agent: 5/minute
  api: 10/minute
base_url: https://api.devtools.cloud/v2
---

# Deploy Application

## Prerequisites

- OAuth 2.0 access token (see https://devtools.cloud/docs/oauth)
- A Git repository URL (GitHub, GitLab, or Bitbucket)

## Workflow

### Step 1: Create Application (if new)

POST /apps

```json
{
  "name": "my-app",
  "git_url": "https://github.com/user/repo",
  "branch": "main",
  "runtime": "nodejs"
}
```

Response (201 Created):
```json
{
  "id": "app_k8x7m",
  "name": "my-app",
  "status": "created",
  "url": "https://my-app.devtools.cloud"
}
```

### Step 2: Trigger Deployment

POST /apps/{app_id}/deployments

```json
{
  "branch": "main",
  "env_vars": {
    "NODE_ENV": "production"
  }
}
```

Response (202 Accepted):
```json
{
  "id": "deploy_9f3n",
  "status": "building",
  "started_at": "2026-03-04T10:30:00Z"
}
```

### Step 3: Check Deployment Status

Poll until status is "live" or "failed":

GET /apps/{app_id}/deployments/{deploy_id}

Response:
```json
{
  "id": "deploy_9f3n",
  "status": "live",
  "url": "https://my-app.devtools.cloud",
  "build_time_seconds": 47
}
```

Possible status values: building → deploying → live | failed

### Step 4: View Logs (if needed)

GET /apps/{app_id}/logs?lines=50&level=error

## Error Handling

| Code | Meaning                | Action                        |
|------|------------------------|-------------------------------|
| 400  | Invalid request        | Check required fields         |
| 401  | Auth failed            | Refresh OAuth token           |
| 404  | App not found          | Verify app_id                 |
| 409  | Deployment in progress | Wait for current deploy       |
| 429  | Rate limited           | Wait and retry after header   |
| 500  | Server error           | Retry with exponential backoff|

## Notes

- Deployments are atomic: if the build fails, the previous version stays live.
- Environment variables set in Step 2 persist across deployments.
- Build detection is automatic — the platform reads package.json, requirements.txt, go.mod, or Cargo.toml.
```

## Appendix A: Discovery File Grammar

```
discovery-file  = site-header [site-desc] [prose-sections] skill-sections
site-header     = "# " site-name NEWLINE
site-desc       = "> " description-text NEWLINE
prose-sections  = *(paragraph NEWLINE)
skill-sections  = 1*(section-header skill-list)
section-header  = "## " section-name NEWLINE
skill-list      = 1*(skill-entry NEWLINE)
skill-entry     = "- [" skill-name "](" skill-url ")" [":" skill-desc]
skill-name      = 1*VISIBLE-CHAR
skill-url       = relative-url / absolute-url  ; path under /skills/ or /agents/
skill-desc      = 1*UTF8-CHAR
```

## Appendix B: SKILL.md Frontmatter Schema

```yaml
# Required fields
name: string          # kebab-case identifier, matches directory name
description: string   # Trigger description (what, when, and for whom)
version: string       # Semantic version (MAJOR.MINOR.PATCH)

# Optional fields
author: string        # Publisher name or organization
api_version: string   # Version of the underlying API
auth: string          # One of: none, api-key, bearer, oauth2
rate_limit:              # Rate limit information (object)
  agent: string          # Recommended limit for AI agents (e.g., "20/minute")
  api: string            # Actual API rate limit (e.g., "100/minute")
base_url: string      # Base URL for API calls (if not site origin)
contact: string       # Contact for skill-related issues (email or URL)
```

## Appendix C: Content Types

| File                     | Recommended Content-Type              |
|-------------------------|---------------------------------------|
| skills.txt / agents.txt | `text/plain; charset=utf-8` or `text/markdown; charset=utf-8` |
| SKILL.md                | `text/markdown; charset=utf-8`        |

## Appendix D: Path Convention Summary

| Component       | Primary Convention | Alternative Convention |
|----------------|-------------------|----------------------|
| Discovery file | `/skills.txt`     | `/agents.txt`        |
| Skill directory| `/skills/`        | `/agents/`           |
| Skill document | `/skills/{name}/SKILL.md` | `/agents/{name}/SKILL.md` |

Publishers choose one convention. Consumers MUST support both.

## Appendix E: Changelog

### v0.1 (March 2026)
- Initial draft specification.
- Dual-path discovery: both `skills.txt` and `agents.txt` supported.
- Dual-path directories: both `/skills/` and `/agents/` supported.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)