> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# Modern.js For AI

Modern.js 为 AI Agent 提供了一套工具套件，让项目开箱即为 agent-ready，帮助你更准确、高效地用 AI 完成 Modern.js 应用的开发、升级与迁移。

## 随包文档

Modern.js 把与你安装版本一致的英文文档随 `@modern-js/app-tools` 一起分发。安装或升级后，文档即位于 `node_modules/@modern-js/app-tools/docs/`，离线可用、无需额外配置。

AI Agent 由此获取与当前框架版本严格匹配的 API、配置与约定，而不是依赖可能过时的训练数据。

## AGENTS.md

`AGENTS.md` 是给 AI 编码助手的项目指引，告诉它在动手前先阅读随包文档、并遵循 Modern.js 的约定。

- **新建项目**：`npx @modern-js/create` 默认生成 `AGENTS.md`，加 `--no-agents-md` 可跳过。
- **已有项目**：在项目根运行 `npx @modern-js/create --agents-md-only` 生成或更新 `AGENTS.md`，可随时重复运行，你添加的自定义内容会被保留。

Modern.js 只维护 `AGENTS.md` 中 `<!-- BEGIN:modernjs-agent-rules -->` 标记内的内容，标记之外你写的内容不会被改动。

## llms.txt

llms.txt 是遵循 [llms.txt 规范](https://llmstxt.org/) 的在线文档索引，由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成，供 AI 工具在线检索完整文档：

- 索引：[`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
- 全文：[`https://modernjs.dev/llms-full.txt`](https://modernjs.dev/llms-full.txt)（体积较大，按需取片段）

当需要查阅随包文档之外的内容时，让 Agent 在线检索它即可，不必把文档复制进项目。典型场景包括：查阅其他框架版本、随包未包含的章节，或在 Modern.js 项目之外获取信息（例如尚未创建项目、或独立查阅资料时）。

## Skills

Skills 是按需触发的 AI 辅助能力，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。用户向 Skills：

| Skill  | 标识                        | 说明                                                                          |
| ------ | ------------------------- | --------------------------------------------------------------------------- |
| 升级到 v3 | `modernjs-migrate-to-v3`  | v2 应用迁移到 v3：安全改写 + 复杂项人工清单 + 迁移报告                                           |
| 启用特性   | `modernjs-feature-enable` | 为 v3 应用启用 BFF / SSG / styled-components，并脚手架化 Tailwind CSS / 自定义 Web Server |

> Skills 默认不强装、不隐式安装，由你显式安装。RSC、微前端等属于配置或架构决策，不是 `modernjs-feature-enable` 的一键启用项。

## 安装 Skills

Modern.js 的用户向 Skill 就放在仓库根 `skills/` 目录，遵循 [Agent Skills 开放标准](https://github.com/vercel-labs/skills)。推荐用标准的 `skills` CLI 直接从 GitHub 安装：

```bash
# 列出可安装的 Skills
npx skills add web-infra-dev/modern.js --list

# 安装单个 Skill 到你的 Agent 目录（--agent 可选 claude-code / codex / cursor 等）
npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
```

它会把整个 Skill 目录（`SKILL.md` + `scripts/` + `references/`）安装到对应 Agent 目录，随后即可在该 Agent 里触发。

> 需锁定到某个版本时，在仓库后加 `#<ref>`（ref 可为 tag / 分支 / commit），即安装该版本上的 Skill（把 `<tag>` 换成含本 Skill 的发布 tag）：
>
> ```bash
> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
> ```