## 什么是 SKILL.md？

SKILL.md 是一个单独的 Markdown 文件——通常在 `/skill.md` 提供——告诉 AI 代理如何使用你的服务。文件以声明两个字段（`name` 和 `description`）的 YAML frontmatter 开头，然后是记录端点、认证模型和代理需要采取行动的请求形式的自由格式 Markdown。

规范发布在 [agentskills.io](https://agentskills.io/specification),并已被 Anthropic 的 Claude Code、OpenAI Codex、Cursor、GitHub Copilot 和 Microsoft 的 Agent Framework 采纳为跨厂商约定。SKILL.md 文件是让代理从"我找到了这个网站"到"我知道如何调用它"的最小可能产物。

## 为什么 SKILL.md 重要

LLM 代理面临与人类相同的入门成本：弄清楚陌生服务的用途以及如何正确调用。对人类你写一个快速入门指南;对代理你写一个 SKILL.md。frontmatter 的 `name` 给代理一个稳定的内部注册标识符;`description` 是出现在工具列表和代理规划器中的内容;正文是操作手册。

替代方案——代理读取你完整的文档站点、OpenAPI 模式和首页以重建相同信息——既慢、昂贵又有损耗。SKILL.md 将入门步骤压缩为一次 fetch 和几百个 token。

## SKILL.md 如何工作

没有协议握手。代理请求 `/skill.md`，解析 YAML frontmatter 中的 `name` 和 `description`，根据规范的正则表达式验证名称,并将 Markdown 正文作为指令读取。

最小有效的 SKILL.md：

```markdown
---
name: scan-url
description: 扫描任何 URL 的 AI 代理就绪度并返回 0-100 的分数。在用户询问网站的代理就绪度或想要跨网站比较协议支持时使用。
---

# Agent Readiness Scan

使用 `GET /api/v1/scan?url={url}` 获取代理友好的 JSON 响应。

## 端点

- `GET /api/v1/scan?url={url}` — 代理用的扁平 JSON
- `GET /api/scan?url={url}` — 完整 HTML 报告（人类用）
- `GET /api/badge?url={url}` — SVG 徽章

## 认证

无。免费。

## 示例

`curl https://agentgrade.com/api/v1/scan?url=https://example.com`
```

这就是整个表面。找到这个文件的代理知道足够多的信息,可以在第一次尝试时正确调用你的服务。

## SKILL.md 与其他代理可读文件

| 文件 | 谁提供 | 回答什么 | 格式 |
|---|---|---|---|
| **SKILL.md** | 服务 | *如何使用这个服务？* | Markdown + frontmatter |
| **[OpenAPI](/kb/zh/openapi)** | 服务 | *有什么端点和 schema？* | JSON/YAML |
| **[MCP](/kb/zh/mcp) 清单** | MCP 服务器 | *这个服务器通过 JSON-RPC 公开什么工具？* | JSON-RPC |
| **`ai-plugin.json`** | 服务 | *ChatGPT 插件格式的元数据（遗留）* | JSON |
| **[llms.txt](/kb/zh/llms-txt)** | 服务 | *这个网站是什么,散文形式* | Markdown |

SKILL.md 是"操作手册"层,OpenAPI 是"模式"层。两者可以组合：SKILL.md 告诉代理调用哪些端点何时调用;OpenAPI 提供正式的参数 schema。

`ai-plugin.json` 早于 SKILL.md,与 OpenAI 已废弃的原始 ChatGPT 插件格式绑定。SKILL.md 是现代的、跨厂商的继任者。

## Frontmatter 验证

agentskills.io 规范对两个字段严格：

- **`name`** — 1 到 64 字符,小写字母数字带单个连字符。必须匹配 `^[a-z0-9]+(-[a-z0-9]+)*$`。不能有前导、尾随或连续的连字符。
- **`description`** — 1 到 1024 字符。以代理应执行的动词开头。描述出现在工具选择器和规划器推理中。

符合规范的代理和扫描器会拒绝 frontmatter 格式错误的文件。

## 谁采纳了 SKILL.md

规范在 2025 年从单一厂商约定演变为可互操作的标准：

- **Claude Code** ([docs.claude.com/en/docs/claude-code/skills](https://docs.claude.com/en/docs/claude-code/skills)) — Anthropic 的编码代理从本地目录加载 SKILL.md 文件。
- **OpenAI Codex** — 为代理技能定义采纳了相同的格式。
- **Cursor** — 从项目工作区读取 SKILL.md 用于代理的内联指导。
- **GitHub Copilot** — 为仓库级代理指令遵守相同的 frontmatter 约定。
- **Microsoft Agent Framework** — 跨厂商实现遵循 agentskills.io 规范。

由于格式只是带 YAML frontmatter 的 Markdown,采纳成本几乎为零。

## 如何将 SKILL.md 添加到你的网站

1. **选择名称。** 一个动词-名词短语,小写连字符,少于 64 字符。
2. **撰写描述。** 两句话。句 1：代理实现什么。句 2：何时使用。
3. **撰写正文。** 带 HTTP 动词的端点、认证模型、一个可粘贴的 curl 示例。保持在一屏文本内。
4. **在 `/skill.md` 提供。** 静态文件。`Content-Type: text/markdown`。
5. **从 llms.txt 或 `/.well-known/` 链接。** 可选但推荐。

具有有效 SKILL.md 和 [OpenAPI](/kb/zh/openapi) 规范的网站,为一无所知的代理做好了准备。

## 扫描器标记的常见错误

- **缺少 frontmatter 分隔符** — 文件不以 `---` 开头。
- **无效的 `name`** — 大写、下划线或前导/尾随连字符。最常见的失败。
- **描述太短** — 少于 1 字符（空）或太短以至于代理没有信号。目标是 80-200 字符。
- **描述太长** — 超过 1024 字符。将细节移到正文。
- **路径错误** — 在 `/skills.md`（复数）、`/.well-known/skill.md` 或 `/skill/index.md` 提供。规范是文档根的 `/skill.md`。
- **内容类型错误** — 由于 CMS 自动渲染 Markdown 而作为 `text/html` 提供。提供原始的 `text/markdown` 或 `text/plain`。

## FAQ

**SKILL.md 与 Anthropic 的"Claude Skills"相同吗？**
磁盘上的格式相同。"Claude Skills"是 Anthropic 消费 SKILL.md 文件的功能的产品名称;格式本身是跨厂商的 agentskills.io 规范。

**我需要同时使用 SKILL.md 和 OpenAPI 吗？**
如果你有 API,两个都提供。SKILL.md 用散文回答"如何使用？";OpenAPI 正式回答"确切的 schema 是什么？"。

**什么取代了 `/skills.json`？**
`/skills.json` 是先于任何标准的早期手工清单格式。它被 SKILL.md 取代用于"如何使用"层,并被 OpenAPI 的 `x-payment-info`（见 [OpenAPI](/kb/zh/openapi)）取代用于声明付费端点。AgentGrade 不再为 `/skills.json` 打分。

**SKILL.md 文件应该放在哪里？**
文档根的 `/skill.md`。一些代理也会探测 `/.well-known/skill.md` 作为后备。

**一个网站可以有多个 SKILL.md 文件吗？**
约定是每个源一个 `/skill.md`。

**SKILL.md 取代 [MCP](/kb/zh/mcp) 吗？**
不——它们回答不同的问题。SKILL.md 告诉代理如何通过现有端点使用你的 HTTP 服务。MCP 定义了一个 JSON-RPC 接口,代理在持久连接上将你的服务器作为工具调用。

**AgentGrade 会惩罚发布 SKILL.md 但没有 OpenAPI 的网站吗？**
不会。SKILL.md 本身是一个积极信号。

**代理真的会读这个文件吗？**
Claude Code、Codex、Cursor 和 Copilot 今天就在其工作区中读取 SKILL.md 文件。浏览代理越来越多地将 `/skill.md` 作为发现握手的一部分进行探测,与 `/llms.txt` 和 `/openapi.json` 并列。

## 规范成熟度

**跨厂商标准。** 在 [agentskills.io](https://agentskills.io/specification) 定义。被 Claude Code、OpenAI Codex、Cursor、GitHub Copilot 和 Microsoft Agent Framework 采纳。

## 了解更多

- [agentskills.io](https://agentskills.io/specification) — 规范
- [Claude Code skills 文档](https://docs.claude.com/en/docs/claude-code/skills) — Anthropic 的采纳
- [OpenAPI](/kb/zh/openapi) — 配套的 schema 层
- [MCP](/kb/zh/mcp) — JSON-RPC 工具服务器的替代方案