skill.md

Mintlify 会在你项目的根目录托管一个 skill.md 文件，用于描述 AI agent 在你的产品中可以执行哪些操作。 skill.md 规范是一种结构化、机器可读的格式，它将产品的能力、必填输入以及约束条件显式列出。这样，agent 就能更可靠地使用这些产品。 Mintlify 会通过一个 agentic loop 分析你的文档，自动为你的项目生成一个 skill.md 文件。随着你更新文档，这个文件会自动保持最新且无需维护。你也可以选择在项目根目录添加一个自定义的 skill.md 文件，以覆盖自动生成的版本。

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

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

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

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

将 `skill.md` 文件与代理一起使用

如果你使用反向代理，请将其配置为将对 /skill.md、/.well-known/skills/* 和 /.well-known/agent-skills/* 路径的请求转发到你的 Mintlify 子域。有关目标路径和缓存策略，请参见路由配置。

当用户连接到你的 Model Context Protocol (MCP) 服务器时，他们的代理可以将你的 skill.md 文件作为 MCP 资源来发现和使用，无需单独安装这些 skills。要手动将你的 skills 添加到代理的上下文中，请使用 skills 命令行界面 (CLI)。

npx skills add https://your-docs-domain.com

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

将某个产品的 skill.md 文件安装到你的代理中。

在 Cursor 中打开

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

`skill.md` 的结构

Mintlify 会根据 agentskills.io 规范生成一个 skill.md 文件。生成的文件包括：

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

自定义 skill 文件

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

单个 skill 文件

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

多个 skill 文件

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

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

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

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

使用符号链接避免重复

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

# 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 符号链接都有效。

Frontmatter 字段

自定义 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	以空格分隔的、预先批准可供该技能使用的工具列表（实验性）。
`groups`	array	将技能限制为特定的已认证用户组。请参阅将技能限制为特定用户组。
`public`	boolean	当你的站点启用身份验证时，将该技能开放给公共搜索 MCP 服务器的未认证用户。请参阅在需要认证的站点上共享技能。

Example frontmatter

---
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"
---

将技能限制为特定用户组

如果你的文档启用了身份验证，你可以通过在 frontmatter 中添加 groups 数组，将某个技能限制为特定的用户组。用户组过滤的工作方式与页面可见性相同：技能仅对至少属于所列组之一的已认证用户开放。

SKILL.md

---
name: admin-tools
description: 面向管理员的内部操作。
groups: ["admin"]
---

按用户组限制的技能：

技能发现端点和 /skill.md 文件仅向组匹配的已登录访问者返回这些技能。其他访问者直接请求该技能的 URL 时会收到 404 响应。
仅作为MCP 资源向组匹配的已认证终端用户开放。不匹配的用户以及没有终端用户的机器对机器客户端只能看到未设置用户组的技能。

未设置 groups 字段的技能对所有人可见。如果你的文档启用了身份验证，未登录的访问者默认无法看到你的自定义技能。要与他们共享某个技能，请在其 frontmatter 中添加 public: true。

SKILL.md

---
name: getting-started
description: 设置 API 并发出你的第一个请求。
public: true
---

在启用身份验证的站点上：

未登录的访问者只能看到标记为 public: true 的技能。这适用于 /skill.md 文件、技能发现端点，以及在你的站点包含公开页面时位于 /mcp 的公共搜索 MCP 服务器。
已登录的访问者和连接到 /authed/mcp 的用户会根据其用户组看到相应技能。

Skills 发现端点

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

Agent-skills 发现（推荐）

/.well-known/agent-skills/ 端点遵循 agent-skills 0.2.0 发现规范，并包含内容完整性验证。 GET /.well-known/agent-skills/index.json 返回一个 JSON 清单，列出所有可用的 skills：

{
  "$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 文件。

Skills 索引

/.well-known/skills/ 端点是原始的发现格式。 GET /.well-known/skills/index.json 返回一个 JSON 清单，列出所有可用的 skills：

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

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

单个 skill 文件

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

Agent 卡片

Mintlify 在 /.well-known/agent-card.json 托管一个 Agent-to-Agent (A2A) agent card。agent card 是一个标准化的 JSON 文档，可帮助兼容 A2A 的代理在一次请求中发现你的文档站点和可用的 skills。 GET /.well-known/agent-card.json 返回一个符合 A2A agent card 0.3 规范的 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 子域名。

如果你使用反向代理，请将其配置为将 /.well-known/agent-card.json 转发到你的 Mintlify 子域名。

agent card 通过提供一个无需建立会话的轻量级发现层来补充 MCP。

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

将 `skill.md` 文件与代理一起使用

`skill.md` 的结构

自定义 skill 文件

单个 skill 文件

多个 skill 文件

使用符号链接避免重复

Frontmatter 字段

将技能限制为特定用户组

Skills 发现端点

Agent-skills 发现（推荐）

Skills 索引

单个 skill 文件

Agent 卡片

​将 skill.md 文件与代理一起使用

​skill.md 的结构

​自定义 skill 文件

​单个 skill 文件

​多个 skill 文件

​使用符号链接避免重复

​Frontmatter 字段

​将技能限制为特定用户组

​在需要认证的站点上共享技能

​Skills 发现端点

​Agent-skills 发现（推荐）

​Skills 索引

​单个 skill 文件

​Agent 卡片

将 `skill.md` 文件与代理一起使用

`skill.md` 的结构

自定义 skill 文件

单个 skill 文件

多个 skill 文件

使用符号链接避免重复

Frontmatter 字段

将技能限制为特定用户组

在需要认证的站点上共享技能

Skills 发现端点

Agent-skills 发现（推荐）

Skills 索引

单个 skill 文件

Agent 卡片