Install.md 标准：让 LLM 自动执行安装脚本

安装软件是一类具体、重复性强的任务，而这正是 Agent 所擅长的。今天，我们提出 install.md，旨在规范开发者应该如何为 Agent 编写安装说明。目前，所有 Mintlify 站点都已启用这一功能，包括 Cerebras、Firecrawl 和 Langchain。

**已于 2026 年 1 月 21 日弃用：**我们已经迁移到 skill.md。这是一项面向 Agent Skill 的开放标准，可同时提供安装和使用相关知识。详情请参阅公告。

我们提议建立一项 /install.md 文件标准，用于提供可由 LLM 执行的安装说明。

Agent 能力的增长速度，已经超过软件开发者的适应速度。如今的产品文档主要面向人类，而不是 AI，这给自动化安装这类烦琐、需要不断处理枝节问题的任务带来了阻力。

两者之间的差异非常细微。Agent 需要以任务形式接收指令，例如：“我希望你帮我安装 Mintlify CLI。自主执行下面的所有步骤。”而人类可以根据更宽泛的文字说明，甚至是一段 bash 脚本完成操作。

今天，我们提出 install.md，旨在规范开发者应该如何为 Agent 编写安装说明。目前，所有 Mintlify 站点都已启用这一功能，包括 Cerebras、Firecrawl 和 Langchain。

在你的项目中添加一个 install.md Markdown 文件，并在其中编写可由 LLM 执行的安装说明。

用户可以把这个文件粘贴到 LLM 中，也可以通过 URL 直接将其传给 LLM。LLM 会读取说明、检测环境、适配当前配置并执行操作——也可以选择在每一步执行前请求批准。由于该文件对人类可读，用户在运行前就能准确了解将要发生什么。

与其在没有任何安全保障的情况下，把一个可执行文件通过管道传给 bash，而且还不能确定它能否适配你的 Arch Linux 环境，不如把 install.md 交给 Claude，相信 Opus 会替你处理好这些繁琐细节。

curl -fsSL https://www.anaconda.com/docs/install.md | claude

无论使用哪种语言或框架，也无论你的软件以二进制文件、package 还是脚本的形式分发，这种方式都适用。

作为开发者，你可以定义安装流程应该如何运行。你可以把各种边缘情况相关的知识编码到文件中——这些内容写进常规文档会显得杂乱，但在出现问题时又至关重要。

Mintlify 现在会自动检测所有这些信息，将其整合为一个专为 Agent 设计的版本，并托管在 https://<your-docs-url>/install.md。如果你的文档包含多个产品，例如一个 SDK 和一个 CLI，Mintlify 默认会为 CLI 生成 install.md。你可以在文档目录的根目录中添加自己的 install.md，覆盖自动生成的文件。如果你希望彻底禁用这项功能，请联系 support@mintlify.com。

如果你没有使用 Mintlify，也可以手动创建并托管这个文件。

install.md 采用结构化格式，并通过特定关键词引导 LLM 自主执行任务。

一份典型的 install.md 包含：

**Header：**以产品名称作为小写、连字符分隔的 H1 标题（例如 # claude-code）

**Description：**使用块引用描述产品（例如 > Documentation and setup instructions for product-name）

**Action prompt：**给 LLM 的直接指令（例如 “I want you to install [Product] for me. Execute all the steps below autonomously.”）

**OBJECTIVE：**安装应该实现的目标

**DONE WHEN：**明确的验证标准（例如执行某条命令后返回预期输出）

**TODO：**由 Markdown 复选框组成的待办步骤列表

**Step sections：**包含代码块的详细安装说明

**EXECUTE NOW：**引用 TODO 列表和目标的行动指令

这种格式很灵活——开发者可以自行定义成功完成安装所需的步骤。

# mintlify

> Documentation and setup instructions for mintlify

I want you to install Mintlify CLI for me. Execute all the steps below autonomously.

OBJECTIVE: Install the Mintlify CLI and set up a local documentation preview environment.

DONE WHEN: Local documentation server is running and accessible at http://localhost:3000.

## TODO

- [ ] Verify Node.js v20.17.0+ is installed
- [ ] Install the Mintlify CLI globally
- [ ] Create a new documentation project
- [ ] Start the local development server
- [ ] Verify the preview is accessible at localhost:3000

## Prerequisites

You need to have Node.js v20.17.0 or higher installed. Verify your Node.js version:

```bash
node --version

You must also have Git installed:

git --version

Install the CLI

You need to install the Mintlify CLI globally using npm or pnpm.

Using npm:

npm i -g mint

Using pnpm:

pnpm add -g mint

Verify the installation:

mint --version

Create a new documentation project

You must create a new documentation project using the CLI. This clones the starter kit into your specified directory:

mint new docs

The CLI will prompt you for a project name and theme. You can also specify these directly:

mint new docs --name my-project --theme linden

Navigate into your new project directory:

cd docs

Start the local preview server

You need to start the development server to preview your documentation locally:

mint dev

Your documentation preview is now available at http://localhost:3000.

If port 3000 is already in use, you can specify a custom port:

mint dev --port 3333

Alternatively, run without global installation using npx:

npx mint dev

Verify the preview

Open your browser and navigate to http://localhost:3000 to confirm the documentation site is running.

Update the CLI

If you need to update to the latest version:

mint update

Or reinstall with the latest version:

npm i -g mint@latest

Additional CLI commands

Check for broken links in your documentation:

mint broken-links

Check for accessibility issues:

mint a11y

Validate an OpenAPI specification:

mint openapi-check <openapi-file-or-url>

EXECUTE NOW: Complete the above TODO list to achieve: Local documentation server is running and accessible at http://localhost:3000.

这些说明描述的是目标结果，而不是需要执行的确切命令。LLM 会自行适配环境——无论使用 npm 还是 pnpm、macOS 还是 Linux、新项目还是现有代码库。

## 与 llms.txt 的关系

`install.md` 可以自然地与 `llms.txt` 配合使用。`llms.txt` 帮助 LLM 理解你的软件；`install.md` 则告诉它们如何安装。你的 `install.md` 可以链接到 `llms.txt`，这样 LLM 就能在排查问题、了解配置细节，或安装过程中需要额外上下文时查阅它。

## 对于发布软件的开发者

只需定义一次安装流程，它就能适配各种环境。你可以把边缘情况和故障排查知识编码进去，而不会让主要文档变得杂乱。你不需要构建或维护安装向导，同时还能准确控制 LLM 接收到哪些上下文。面向 Agent 的安装说明可以不同于公开文档，不必顾虑公司的行文风格或 Developer Experience 层面的润色。你是在直接为真正的用户编写内容，而这些用户就是 Agent。

## 对于安装软件的用户

只需一条命令即可安装软件，你也可以把文件粘贴到任意 LLM 中。这些说明对人类可读，因此你可以在执行前检查每一个步骤，并在必要时修改内容，以提升它在你的系统上的执行效果。LLM 会自动适配你的具体环境。由于文件是在运行时获取的，你永远不必面对过时的训练数据。

安装说明存放在一个固定、容易找到的位置。结构化格式提供了明确的成功标准，用于判断安装是否完成。文件采用 Markdown 而不是 HTML，这意味着可以为模型提供干净的输入。

这项规范已经开源：

GitHub：`github.com/mintlify/install-md`

在你的项目根目录或 `/docs` 目录中添加一个 `install.md`。就这么简单。

如果你使用 Mintlify 编写文档，系统会自动在 `yourdocs.com/install.md` 生成 `install.md`。

## PostHog 或 Sentry 这类产品的安装向导呢？

安装向导解决的是同一个问题：在不同环境中实现可靠安装。但构建和维护安装向导需要投入大量工程资源。PostHog 的安装向导由多个 LLM prompt 组成，用户必须审查代码仓库才能找到这些 prompt。`install.md` 是一种更轻量的替代方案——使用 Markdown 定义说明，由 LLM 负责适配。对于包含大量配置选项的复杂集成，专门的安装向导可能仍然是正确选择。但对大多数软件来说，`install.md` 能以小得多的成本带来其中的大部分收益。

## install.md 如何与我现有的 CLI 或脚本配合使用？

你可以在 `install.md` 中指示 LLM 运行你的 CLI、执行你的脚本，或者遵循现有的配置流程。可以把它理解为一个引导层，负责指导 LLM 使用你已经构建好的各种工具。

## 安全性怎么办？这不就是多了几个步骤的 curl | bash 吗？

这是一个合理的担忧。以下几点让 `install.md` 有所不同：

**从设计上就对人类可读。**用户可以在执行前检查说明。与经过混淆的脚本不同，它的意图非常清晰。

**逐步审批。**在 Agentic 场景中，可以将 LLM 配置为在运行命令前请求批准。用户能看到每项操作，也可以拒绝执行。

**没有隐藏行为。**`install.md` 使用自然语言描述目标结果。相比 shell 脚本，恶意意图更难隐藏。

`install.md` 并不能消除对信任的要求。用户应该只使用来自可信来源的 `install.md` 文件——这与其他安装方式并无不同。

## 版本管理怎么办？

默认情况下，`install.md` 适用于当前版本。如果不同版本的安装方式存在显著差异，你可以托管特定版本的文件（`/v2/install.md`），也可以直接在说明中加入版本检测逻辑。

## 如果 install.md 不适合我的使用场景怎么办？

这项规范已经开源。你可以提交 issue 或 PR——我们正在根据真实世界的反馈持续演进这项标准。

## 文档流量现状：2026 年中期报告

在 Mintlify 托管的文档所统计到的 Web 流量中，Agent 目前已经占到 66%。截至 7 月即将结束时，当月记录的 Agent Web 请求已超过 2.13 亿次，而人类页面加载量为 1.05 亿次。

## 文档 URL 基准测试：Markdown 与 llms.txt 优于 HTML

我们在 20 个 Mintlify 文档站点上进行了 2,400 次测试，对比了向 AI Agent 提供文档的四种方式：HTML、纯 Markdown、包含 `llms.txt` 链接的 Markdown，以及内联 `llms.txt` 内容的 Markdown。结果发现，只需提供一个指向 `llms.txt` 的链接，就能在不增加任何成本的情况下消除绝大多数 Agent 产生的 404。