跳转到主要内容
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 子域。
当用户连接到你的 MCP 服务器时，他们的代理可以将你的 skill.md 文件作为 MCP 资源来发现和使用，无需单独安装这些 skills。 要手动将你的 skills 添加到代理的上下文中，请使用 skills 命令行界面 (CLI)。 
npx skills add https://your-docs-domain.com
这会将你的产品功能添加到代理的 context 中，使其能够代表用户执行操作。
向你的用户讲解如何将 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 开头。
FieldTypeDescription
namestring该技能的名称。
descriptionstring该技能功能的简要说明。
licensestring该技能的许可证（例如，MIT、Apache-2.0）。
compatibilitystring运行要求或兼容性说明（例如，运行时依赖）。
metadataobject以字符串形式的 key-value 对提供的附加 metadata（例如，author、version）。
allowed-toolsstring以空格分隔的、预先批准可供该技能使用的工具列表（实验性）。
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"
---

​
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..."
    }
  ]
}
字段描述
$schemaAgent-skills 0.2.0 发现规范的 schema URL。
name一个 URL 安全的 slug，源自你 skill.md frontmatter 中的 name 字段。
typeSkill 格式，始终为 skill-md。
description来自你 skill.md frontmatter 的简要描述，截断为 1024 个字符。
url获取完整 skill 文件的路径。
digestSkill 文件内容的 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 数组，以便代理在发出请求前协商传输方式。
字段描述
protocolVersionA2A 协议版本。始终为 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.app 子域名。
如果你使用反向代理，请将其配置为将 /.well-known/agent-card.json 转发到你的 Mintlify 子域名。
agent card 通过提供一个无需建立会话的轻量级发现层来补充 MCP。