> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# skill.md

> 通过自动生成的 skill.md 能力文件，让你的文档随时可供 AI 智能体使用，并向其描述产品可用的能力。

Mintlify 会在你项目的根目录托管一个 `skill.md` 文件，用于描述 AI agent 在你的产品中可以执行哪些操作。

[skill.md 规范](https://agentskills.io/specification) 是一种结构化、机器可读的格式，它将产品的能力、必填输入以及约束条件显式列出，从而让 agent 能更可靠地使用这些能力。

Mintlify 会通过一个 agentic loop 分析你的文档，自动为你的项目生成一个 `skill.md` 文件。随着你更新文档，这个文件会自动保持最新且无需维护。你也可以选择在项目根目录添加一个自定义的 `skill.md` 文件，以覆盖自动生成的版本。

<Note>生成或更新 `skill.md` 文件最多可能需要 24 小时。</Note>

在你的文档站点 URL 末尾追加 `/skill.md`，即可查看你的 `skill.md`。Mintlify 只会为公开的文档站点生成 `skill.md` 文件。

<PreviewButton href="https://mintlify.com/docs/skill.md">
  打开本站点的 skill.md。
</PreviewButton>

<Tip>
  `llms.txt` 和 `skill.md` 都帮助 agent 使用你的文档，但它们的作用不同。

  * `llms.txt` 是一个目录。它列出你所有的文档页面及其说明，让 agent 知道去哪里查找信息。
  * `skill.md` 是一个能力概览。它告诉 agent 使用你的产品可以完成什么、需要哪些输入，以及有哪些约束条件。
</Tip>

<div id="use-skillmd-files-with-agents">
  ## 将 `skill.md` 文件与代理一起使用
</div>

<Note>
  如果你使用[反向代理](/zh/deploy/reverse-proxy)，请将其配置为将对 `/skill.md`、`/.well-known/skills/*` 和 `/.well-known/agent-skills/*` 路径的请求转发到你的 Mintlify 子域。
</Note>

当用户连接到你的 MCP 服务器时，他们的代理可以将你的 `skill.md` 文件作为 [MCP 资源](/zh/ai/model-context-protocol#mcp-resources)来发现和使用，无需单独安装这些 skills。

要手动将你的 skills 添加到代理的上下文中，请使用 [skills 命令行界面 (CLI)](https://www.npmjs.com/package/skills)。

```bash theme={null}
npx skills add https://your-docs-domain.com
```

这会将你的产品功能添加到代理的 context 中，使其能够代表用户执行操作。

<Tip>
  向你的用户讲解如何将 `skill.md` 文件与代理配合使用，以便他们在结合你的产品使用 AI 工具时获得更好的效果。
</Tip>

<div id="skillmd-structure">
  ## `skill.md` 结构
</div>

Mintlify 会根据 [agentskills.io 规范](https://agentskills.io/specification) 生成一个 `skill.md` 文件。生成的文件包括：

* **Metadata**：项目名称、说明和版本。
* **Capabilities**：智能体可以通过你的产品完成的能力范围。
* **Skills**：按类别组织的具体操作。
* **Workflows**：常见任务的分步流程。
* **Integration**：支持的工具和服务。
* **Context**：与你产品架构相关的背景信息。

<div id="custom-skill-files">
  ## 自定义 skill 文件
</div>

添加自定义 skill 文件以覆盖自动生成的 `skill.md`。Mintlify 支持托管单个 skill 文件和用于多个 skill 的目录。如果你删除所有自定义 skill 文件，Mintlify 会重新生成一个 `skill.md` 文件。

<div id="single-skill-file">
  ### 单个 skill 文件
</div>

在项目根目录添加一个 `skill.md` 文件，以覆盖自动生成的文件。

<div id="multiple-skill-files">
  ### 多个 skill 文件
</div>

将多个 skill 文件添加到项目中的 `.mintlify/skills/` 目录。每个 skill 必须位于自己的子目录中，并包含一个 `SKILL.md` 文件：

```
.mintlify/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md
```

当你有多个 skill 时，`/skill.md` 端点会重定向到 `/.well-known/skills/index.json` 发现端点，该端点列出所有可用的 skill。发现端点使每个 skill 可以被单独访问。

<Note>
  你可以同时使用两种方式——在根目录放置一个 `skill.md` 文件，并使用 `.mintlify/skills/` 目录。发现索引会包含所有 skill。
</Note>

<div id="use-symlinks-to-avoid-duplication">
  ### 使用符号链接避免重复
</div>

如果你的 skill 文件位于仓库中的其他位置（例如 `plugins/` 或 `skills/` 目录），你可以将 `.mintlify/skills` 通过符号链接指向该位置，而无需复制文件：

```bash theme={null}
# Skills live in a top-level skills/ directory
ln -s ../skills .mintlify/skills
```

```
project/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md
  .mintlify/
    skills -> ../skills
  docs.json
```

Mintlify 会在部署时解析符号链接，因此 skill 文件会像直接位于 `.mintlify/skills/` 内一样被发现和提供。这对目录符号链接和单个 skill 符号链接都有效。

<div id="frontmatter-fields">
  ### Frontmatter 字段
</div>

自定义 `skill.md` 文件必须以 YAML frontmatter 开头。

| Field           | Type   | Description                                               |
| --------------- | ------ | --------------------------------------------------------- |
| `name`          | string | 该技能的名称。                                                   |
| `description`   | string | 该技能功能的简要说明。                                               |
| `license`       | string | 该技能的许可证（例如，`MIT`、`Apache-2.0`）。                           |
| `compatibility` | string | 运行要求或兼容性说明（例如，运行时依赖）。                                     |
| `metadata`      | object | 以字符串形式的 key-value 对提供的附加 metadata（例如，`author`、`version`）。 |
| `allowed-tools` | string | 以空格分隔的、预先批准可供该技能使用的工具列表（实验性）。                             |

```md Example frontmatter theme={null}
---
name: mintlify
description: 使用 Mintlify 构建和维护文档站点。用于创建文档页面、配置导航、添加组件或设置 API 参考。
license: MIT
compatibility: Requires Node.js for CLI. Works with any Git-based workflow.
metadata:
  author: mintlify
  version: "1.0"
---
```

<div id="skills-discovery-endpoints">
  ## Skills 发现端点
</div>

Mintlify 在 `/.well-known/skills/` 和 `/.well-known/agent-skills/` 托管了 skills 目录，代理可以通过这些目录以编程方式发现和获取你的 skill 文件。

<div id="agent-skills-discovery">
  ### Agent-skills 发现（推荐）
</div>

`/.well-known/agent-skills/` 端点遵循 [agent-skills 0.2.0 发现规范](https://schemas.agentskills.io/discovery/0.2.0/schema.json)，并包含内容完整性验证。

`GET /.well-known/agent-skills/index.json` 返回一个 JSON 清单，列出所有可用的 skills：

```json theme={null}
{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "my-product",
      "type": "skill-md",
      "description": "A brief description of what your skill does.",
      "url": "/.well-known/agent-skills/my-product/SKILL.md",
      "digest": "sha256:a1b2c3..."
    }
  ]
}
```

| 字段            | 描述                                                       |
| ------------- | -------------------------------------------------------- |
| `$schema`     | Agent-skills 0.2.0 发现规范的 schema URL。                     |
| `name`        | 一个 URL 安全的 slug，源自你 `skill.md` frontmatter 中的 `name` 字段。 |
| `type`        | Skill 格式，始终为 `skill-md`。                                 |
| `description` | 来自你 `skill.md` frontmatter 的简要描述，截断为 1024 个字符。           |
| `url`         | 获取完整 skill 文件的路径。                                        |
| `digest`      | Skill 文件内容的 `sha256` 哈希值，用于完整性验证。                        |

`GET /.well-known/agent-skills/{name}/SKILL.md` 返回通过索引中 slugified 名称标识的特定 skill 的 `skill.md` 文件。

<div id="skills-index">
  ### Skills 索引
</div>

`/.well-known/skills/` 端点是原始的发现格式。

`GET /.well-known/skills/index.json` 返回一个 JSON 清单，列出所有可用的 skills：

```json theme={null}
{
  "skills": [
    {
      "name": "my-product",
      "description": "A brief description of what your skill does.",
      "files": ["SKILL.md"]
    }
  ]
}
```

`name` 字段是一个 URL 安全的 slug，源自你 `skill.md` frontmatter 中的 `name` 字段。

<div id="individual-skill-files">
  ### 单个 skill 文件
</div>

`GET /.well-known/skills/{name}/skill.md` 返回通过索引中 slugified 名称标识的特定 skill 的 `skill.md` 文件。

<div id="agent-card">
  ## Agent 卡片
</div>

Mintlify 在 `/.well-known/agent-card.json` 托管一个 [Agent-to-Agent (A2A)](https://a2aproject.github.io/A2A/latest/) agent card。agent card 是一个标准化的 JSON 文档，可帮助兼容 A2A 的代理在一次请求中发现你的文档站点和可用的 skills。

`GET /.well-known/agent-card.json` 返回一个符合 [A2A agent card 0.3 规范](https://a2aproject.github.io/A2A/latest/specification/#agent-card) 的 JSON 文档。`skills` 数组中的每一项都对应于你 skills 发现端点中的一个 skill。

兼容 A2A 的代理通过获取 `/.well-known/agent-card.json` 按名称和描述发现你的站点，沿着 `documentationUrl` 检索人类可读的内容，并迭代 `skills` 来获取每个 `skill.md` 文件。该 card 还公开了一个 `supportedInterfaces` 数组，以便代理在发出请求前协商传输方式。

| 字段                    | 描述                                                             |
| --------------------- | -------------------------------------------------------------- |
| `protocolVersion`     | A2A 协议版本。始终为 `0.3`。                                            |
| `preferredTransport`  | 未协商的客户端使用的默认传输方式。始终为 `HTTP+JSON`。                              |
| `supportedInterfaces` | `{ url, protocolBinding, protocolVersion }` 条目数组，描述代理如何访问你的站点。 |
| `provider`            | 标识文档站点的 `{ url, organization }`。`organization` 是站点标题。          |
| `defaultInputModes`   | 代理接受的输入媒体类型。始终为 `["text/plain"]`。                              |
| `defaultOutputModes`  | 代理产生的媒体类型。始终为 `["text/plain"]`。                                |
| `capabilities`        | 功能标志。目前为 `{ streaming: false, pushNotifications: false }`。     |
| `skills`              | 在 `/.well-known/agent-skills/` 暴露的 skills。                     |

card 中的 URL（`url`、`documentationUrl`、`provider.url` 以及每个 skill URL）使用你配置的自定义域名，因此发布的 card 始终公布规范域名而不是 `*.mintlify.site` 子域名。

<Note>
  如果你使用[反向代理](/zh/deploy/reverse-proxy)，请将其配置为将 `/.well-known/agent-card.json` 转发到你的 Mintlify 子域名。
</Note>

agent card 通过提供一个无需建立会话的轻量级发现层来补充 [MCP](/zh/ai/model-context-protocol)。