feat: skill

.changeset/ai-infra-p0-no-release.md

@@ -0,0 +1,6 @@
+---
+---
+
+chore(ai-infra): repo-level AI coding agents infrastructure (AGENTS.md / CLAUDE.md, skills docs, AI Coding Agents guide).
+
+No package release needed: this PR only adds repo-level files and docs content; it makes no change to any published package's runtime (`@modern-js/create` has zero net diff). Empty changeset added to satisfy the changeset bot without triggering a version bump.

.gitignore

@@ -56,5 +56,5 @@ playground/
 .swe
 .cursor
 .claude
-AGENTS.md
+.agents/
 .specify/

AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md — Modern.js monorepo
+
+> 给在本仓库工作的 AI Agent（Claude Code / Cursor 等）的常驻指引。保持精简：只放命令、约束、路由。详细知识查文档与 llms.txt，复杂流程走 `skills/`。
+
+## 这是什么仓库
+- Modern.js：基于 React 的渐进式 Web 框架（当前主仓为 **v3**）。
+- pnpm + nx monorepo。包的划分见 `pnpm-workspace.yaml`，主要分区：
+  - `packages/solutions/app-tools` — 应用工程方案（高风险区）
+  - `packages/cli/*` — 构建器与 CLI 插件（builder 等，高风险区）
+  - `packages/runtime/*` — 运行时（高风险区）
+  - `packages/server/*` — 服务端 / BFF（高风险区）
+  - `packages/toolkit/*` — 工具库（含 `create` 脚手架）
+  - `packages/document` — 文档站（rspress，产出 llms.txt）
+
+## 常用命令
+- 安装依赖：`pnpm install`
+- 构建单包：`pnpm --filter <pkg> build`
+- 跑测试：`pnpm --filter <pkg> test`（或包内 `rstest`）
+- 代码风格：`biome`（见 `biome.json`），提交前跑 lint。
+- 变更需 changeset：`pnpm change`（影响发布的改动必须加）。
+
+## 禁改区（除非任务明确要求并人工确认）
+- 不手改 `pnpm-lock.yaml`、`dist/`、`node_modules/`、各包 `CHANGELOG.md`。
+- 不改框架运行时语义而不加测试。
+- 不提交 secret / token。
+
+## 查文档（知识检索）
+- API / 配置 / 概念问题优先查 llms.txt：https://modernjs.dev/llms.txt
+- 全文（体积大，按需取片段）：https://modernjs.dev/llms-full.txt
+- 回答须匹配仓库当前版本，勿用更新版本未发布的特性。
+
+## 复杂流程（走 Skills）
+- 两类 Skill 分两处源，别混（详见 `skills/README.md`）：
+  - **用户向**（服务「用 Modern.js 开发应用」的 agent）：唯一手写源是仓库根 `skills/<name>/`（带 SKILL.md 的目录），遵循 Agent Skills 开放标准，用户用标准 `npx skills add web-infra-dev/modern.js --skill <name>` 安装（锁版本加 `#<tag>`）。已落地 `modernjs-migrate-to-v3`、`modernjs-feature-enable`。
+  - **维护者向**（服务「开发 Modern.js 仓库」的 agent）：唯一手写源是 `scripts/skills/<name>/`，**不放在根 `skills/`**（避免被对外 `skills` CLI 默认发现）；`.claude/skills`、`.agents/skills`、`.cursor/skills` 只是 `pnpm sync:skills` 生成的镜像（派生物，已 gitignore）。已落地 `dependency-audit`；规划中（P1+）`modernjs-issue-triage`、`modernjs-pr-review`。
+- Skills 默认不强装、不隐式安装；只在多步骤 + 可验证 + 高频场景才做成 Skill，其余沉淀进本文件或文档。
+
+## AGENTS / llms.txt / Skills 边界（一句话）
+- llms.txt = 知识（厚、自动生成）；AGENTS.md = 约束与路由（薄、常驻）；Skills = 可验证的多步骤流程（带脚本/状态）。

CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+本仓库的 AI Agent 指引统一维护在 [`AGENTS.md`](./AGENTS.md)，请以该文件为准。
+
+Claude Code 会自动加载本文件；这里只做指向，避免两份内容漂移。

biome.json

@@ -116,7 +116,8 @@
       "packages/runtime/plugin-runtime/static/**",
       "packages/cli/flight-server-transform-plugin/tests/fixture/**/*",
       "**/@mf-types/**",
-      "packages/toolkit/create/template/**/*"
+      "packages/toolkit/create/template/**/*",
+      "tests/skill/fixtures/**/*"
     ]
   }
 }

package.json

@@ -37,6 +37,7 @@
     "update:lockfile": "pnpm install --lockfile-only",
     "check-changeset": "cd ./scripts/check-changeset && pnpm start",
     "check-dependencies": "node ./scripts/check-dependencies.js",
+    "sync:skills": "node ./scripts/sync-skills.mjs",
     "update-rspress": "npx taze major --include /rspress/ -w -r -l",
     "update-rsbuild": "npx taze major --include /rsbuild/ -w -r -l",
     "gen:docs": "rm -rf doc_output && mkdir doc_output && cp -r ./packages/document/doc_build/* ./doc_output",

packages/document/docs/en/guides/get-started/_meta.json

@@ -1 +1,8 @@
-["introduction", "quick-start", "upgrade", "glossary", "tech-stack"]
+[
+  "introduction",
+  "quick-start",
+  "upgrade",
+  "glossary",
+  "tech-stack",
+  "ai-coding-agents"
+]

packages/document/docs/en/guides/get-started/ai-coding-agents.mdx

@@ -0,0 +1,48 @@
+---
+title: AI Tools
+sidebar_position: 6
+---
+
+# Modern.js For AI
+
+Modern.js provides a toolkit for AI agents that helps developers use AI to efficiently complete feature development, dependency upgrades, and version migration for Modern.js applications.
+
+## llms.txt
+
+Modern.js docs follow the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms), accessible via `/llms.txt` or `/llms-full.txt`:
+
+- Index: [`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
+- Full text: `https://modernjs.dev/llms-full.txt` (large — fetch on demand)
+
+Most "what is this API / config" questions can be answered from llms.txt. Just let your agent retrieve it on demand; no need to copy docs into your project.
+
+## Skills
+
+Skills are on-demand AI capabilities following the [Agent Skills open standard](https://github.com/vercel-labs/skills). User-facing Skills:
+
+| Skill | Identifier | Description |
+|---|---|---|
+| Upgrade to v3 | `modernjs-migrate-to-v3` | Migrate a v2 app to v3: safe rewrites + manual checklist + migration report |
+| Enable features | `modernjs-feature-enable` | Enable BFF / SSG / styled-components for v3 apps, and scaffold Tailwind CSS / custom Web Server |
+
+> Skills are not force-installed or implicitly installed — you install them explicitly. RSC and micro-frontend setups are configuration or architecture decisions, not one-click `modernjs-feature-enable` actions.
+
+## Installing Skills
+
+Modern.js user-facing Skills live in the repo's root `skills/` directory and follow the [Agent Skills open standard](https://github.com/vercel-labs/skills). The recommended way is the standard `skills` CLI, installing straight from GitHub:
+
+```bash
+# List installable Skills
+npx skills add web-infra-dev/modern.js --list
+
+# Install a single Skill into your agent directory (--agent: claude-code / codex / cursor / ...)
+npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
+```
+
+It installs the entire Skill directory (`SKILL.md` + `scripts/` + `references/`) into the corresponding agent directory, ready to trigger there.
+
+> To pin a specific version, append `#<ref>` (a tag, branch, or commit) to the repo — it installs the Skill as of that ref (replace `<tag>` with a release tag that contains this Skill):
+>
+> ```bash
+> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
+> ```

packages/document/docs/zh/guides/get-started/_meta.json

@@ -1 +1,8 @@
-["introduction", "quick-start", "upgrade", "glossary", "tech-stack"]
+[
+  "introduction",
+  "quick-start",
+  "upgrade",
+  "glossary",
+  "tech-stack",
+  "ai-coding-agents"
+]

packages/document/docs/zh/guides/get-started/ai-coding-agents.mdx

@@ -0,0 +1,48 @@
+---
+title: AI 工具
+sidebar_position: 6
+---
+
+# Modern.js For AI
+
+Modern.js 为 AI Agent 提供了一套工具套件，帮助开发者利用 AI 高效完成 Modern.js 应用的功能开发、依赖升级与版本迁移工作。
+
+## llms.txt
+
+Modern.js 文档遵循 [llms.txt 规范](https://llmstxt.org/)，由 [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) 自动生成，可通过 `/llms.txt` 或 `/llms-full.txt` 供 AI 工具检索：
+
+- 索引：[`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
+- 全文：`https://modernjs.dev/llms-full.txt`（体积较大，按需取片段）
+
+大部分「这个 API / 配置是什么」类问题，靠 llms.txt 即可解决。让你的 Agent 按需检索它即可，不必把文档复制进项目。
+
+## 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
+> ```

scripts/skills/dependency-audit/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: dependency-audit
+description: 审计 Modern.js 仓库依赖健康度，默认直接扫描整仓并从维护者与 Modern 用户 app 两个视角输出报告，覆盖幽灵依赖、循环依赖、重复多版本、安装体积与安装耗时。在「review 依赖改动、pnpm 严格模式报错、构建变慢、包边界不清」时使用。
+user-invocable: true
+---
+
+# dependency-audit
+
+依赖健康体检 + 优化建议，面向**开发 Modern.js 仓库的维护者**。
+
+> 状态：P1 进行中。`scripts/audit.mjs` 默认可直接扫描整个 Modern.js 仓库并输出双视角报告；仍支持显式传入单个包目录做聚焦分析。
+
+## 何时触发
+- `import` 的包在 pnpm 严格模式下报 "module not found"（疑似幽灵依赖）
+- 构建/安装变慢、产物体积上涨，想定位归因
+- review 一个改 `package.json` / 新增依赖的 PR
+- 检查高风险包是否把运行时依赖误放到 `devDependencies`
+- 例行依赖体检
+
+## SOP
+1. **直接跑整仓报告**（在仓库根执行）：
+   ```bash
+   node scripts/skills/dependency-audit/scripts/audit.mjs
+   ```
+   默认输出：
+   - **维护者视角**：整仓 package manifest、源码依赖、lockfile 重复多版本、已安装体积；安装耗时默认不推断，可用 `--measure-install` 实测。
+   - **Modern 用户 app 视角**：默认从 create 模板生成一个 user app fixture，并在该 fixture 内独立 install，输出用户应用依赖问题、重复版本、安装耗时和落盘体积；fixture 默认复用 `.agents/runs/dependency-audit/user-app-fixture`，需要保留当次现场时显式加 `--keep-user-app-fixture`，需要跳过 install 时显式加 `--skip-user-app-install`。
+2. **按需聚焦单包**：
+   ```bash
+   node scripts/skills/dependency-audit/scripts/audit.mjs packages/solutions/app-tools
+   ```
+3. **机器可读 / CI**：
+   ```bash
+   node scripts/skills/dependency-audit/scripts/audit.mjs --json
+   node scripts/skills/dependency-audit/scripts/audit.mjs --fail-on-findings
+   node scripts/skills/dependency-audit/scripts/audit.mjs --skip-user-app-install
+   node scripts/skills/dependency-audit/scripts/audit.mjs --keep-user-app-fixture
+   ```
+4. **解读 & 给修复**：
+   - 幽灵依赖 → 补 `package.json` 声明，或移除多余 import；**不手改 lockfile**。
+   - 循环依赖 → 给最短断环建议。
+   - 重复多版本 → `pnpm dedupe` 视角收敛。
+5. **验证**：修完跑 `pnpm install` + `pnpm --filter <pkg> build` / `pnpm --filter <pkg> test`，确认不回归。
+
+## 安全红线
+- 只读分析 + 给建议；**不自动改 lockfile / dist / node_modules**。
+- 改 `package.json` 前先展示 diff、让人确认。
+
+## 能力 roadmap
+- [x] 幽灵依赖（import 的外部包未在 deps/devDeps/peerDeps/optionalDeps 声明）
+- [x] 循环依赖（相对 import 构图找环 + 断环建议）
+- [x] 重复多版本（读 `pnpm-lock.yaml`，找多版本包 + `pnpm dedupe`/overrides 建议）
+- [x] 安装体积归因（`size-audit.mjs`，数据优先：无 node_modules 不推断）
+- [ ] 安装耗时归因（需实测 install）
+- [ ] peer/dev/prod 放置校验、`exports`/`types` 正确性
+- [ ] 接 AST（替换正则提取，消除 codegen 模板字符串误报）