skill.md

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

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

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

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

在你的文档站点 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/* 路径的请求转发到你的 Mintlify 子域。

代理可以使用 skills 命令行界面 (CLI) 来处理你的 skill.md。

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.md 文件

在项目根目录添加一个 skill.md 文件，以覆盖自动生成的文件。若删除自定义文件，Mintlify 会重新生成一个 skill.md 文件。

当你希望对智能体如何与产品交互进行精细控制时，可以编写自定义文件。请遵循 agentskills.io 规范 以确保与智能体工具的兼容性。

​

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	以空格分隔的、预先批准可供该技能使用的工具列表 (实验性) 。

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/ 托管了一个 skills 目录，代理可以通过该目录以编程方式发现和获取你的 skill 文件。

​

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 文件。