AgentGrade
EnglishEspañol日本語中文
← 知识库

Skill 文件 (SKILL.md)

什么是 SKILL.md？

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

规范发布在 agentskills.io,并已被 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：

---
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服务有什么端点和 schema？JSON/YAML
MCP 清单MCP 服务器这个服务器通过 JSON-RPC 公开什么工具？JSON-RPC
ai-plugin.json服务ChatGPT 插件格式的元数据（遗留）JSON
llms.txt服务这个网站是什么,散文形式Markdown

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

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

Frontmatter 验证

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

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

谁采纳了 SKILL.md

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

由于格式只是带 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 规范的网站,为一无所知的代理做好了准备。

扫描器标记的常见错误

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）取代用于声明付费端点。AgentGrade 不再为 /skills.json 打分。

SKILL.md 文件应该放在哪里？

文档根的 /skill.md。一些代理也会探测 /.well-known/skill.md 作为后备。

一个网站可以有多个 SKILL.md 文件吗？

约定是每个源一个 /skill.md。

SKILL.md 取代 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 定义。被 Claude Code、OpenAI Codex、Cursor、GitHub Copilot 和 Microsoft Agent Framework 采纳。

了解更多

相关阅读：什么是 AI 智能体就绪？