@ultime/codecraft 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.1.0 - 2026-10-27
+
+- 新增根 `SKILL.md`，兼容 Agent Skills / `skills-npm`；安装 `@ultime/codecraft` 后可被自动发现。
+- 新增 `codecraft install`：自动检测 Claude / Trae / Cursor，写入 `.agents/skills` 与对应目录；支持 `--agent` / `--global` / `--dest` / `--force` / `--dry-run`。
+- README 增加三种安装方式：`skills-npm`、内置安装器、手动指针。
+- `docs/07-ai-prompts.md` 与 adapters 补充安装入口。
+
+## 1.0.3 - 2026-10-27
+
+- 文档从 v0 草稿固化为 v1 稳定版。
+- 示例门禁改为通用 typecheck / test / lint，不再出现项目专用命令。
+- 适配器描述加入中文触发词，不读文档时也能更准确地触发。
+- README 增加 5 分钟上手教程；Skills 集合 README 去除自用表述。
+- CI 使用 Node 22，并在发布前检查版本是否已存在。
+- 新增 CLI 测试：version / help / 未知命令 / `--ci` / init 参数校验。
+
 ## 1.0.2 - 2026-10-27
 
 - 新增 `docs/07-ai-prompts.md`：可直接复制的 AI 提示词，覆盖审计 / 报告 / 新项目 / 评审 / 架构 / 模式 / 脚手架 / Design System。

package/README.md

@@ -19,47 +19,47 @@
 
 规则正文只在 [`docs/`](./docs/)；其它位置只放入口与指针，避免第二份真源。
 
-## 快速开始
+> 第一次用：直接看 [安装](#安装) 和 [第一次使用](#第一次使用)。
 
-### 1. 直接运行
+## 安装
 
-```bash
-# 在 codecraft 目录内
-node bin/codecraft.mjs check --root .
+### 方式 A：npm + skills-npm（推荐，多项目 / 团队）
 
-# 检查任意项目
-node /path/to/codecraft/bin/codecraft.mjs check --root /path/to/project
+```bash
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
 ```
 
-### 2. 安装 / 运行
+之后每次 `npm install` 都会把 `node_modules/@ultime/codecraft` 里的 skill 同步到 agent 目录：`.agents/skills/codecraft`，以及检测到的 Claude / Trae / Cursor 目录。需要 Node.js >= 22.20（`skills-npm` 的要求）。
 
-包名 `@ultime/codecraft`，命令 `codecraft`。发布到 npm 后可直接运行：
+### 方式 B：Codecraft 自带安装器（单次，无额外依赖）
 
 ```bash
-npx @ultime/codecraft check --root .
-npx @ultime/codecraft@latest check --root .
+npx @ultime/codecraft install
 ```
 
-安装为项目依赖：
+自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.trae/skills`、`.cursor/skills`）。
 
 ```bash
-npm i -D @ultime/codecraft
-npx codecraft check --root .
+npx @ultime/codecraft install --agent claude          # 指定 agent，可逗号分隔
+npx @ultime/codecraft install --global --agent claude # 装到用户目录
+npx @ultime/codecraft install --dry-run               # 只看计划
+npx @ultime/codecraft install --force                 # 覆盖已有目录
 ```
 
-本地开发 / 未发布时用 tarball：
+### 方式 C：手动指针
 
-```bash
-npm pack
-npm i -D /path/to/ultime-codecraft-<version>.tgz
-npx codecraft check --root .
-```
+不复制文件，只在项目规则里留一行：
 
-也可以直接 `pnpm link --global /path/to/codecraft`，之后在任意目录使用 `codecraft`。
+- Trae：`.trae/rules/codecraft.md`
+- Claude：`CLAUDE.md` 或 `~/.claude/CLAUDE.md`
+- 其他：`AGENTS.md`
 
-### 3. 接入 agent（作为 skill）
+```md
+代码任务先读 <Codecraft 路径>/codecraft/adapters/trae/SKILL.md
+```
 
-适配器只做入口，不复制规则：
+平台入口：
 
 | 平台 | 入口文件 |
 |---|---|
@@ -67,21 +67,32 @@ npx codecraft check --root .
 | Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
 | Claude | [`adapters/claude/SKILL.md`](./adapters/claude/SKILL.md) |
 
-推荐**指针式接入**——不复制规则，升级只需更新仓库：
+## 第一次使用
+
+```text
+用 Codecraft 审计本项目，只读，不改文件。
+```
+
+只启用 skill、不说 Codecraft 时，agent 可能按普通项目分析处理，不保证走 Audit 模式。带上名字最稳。
 
-- Trae：在项目 `.trae/rules/codecraft.md` 写一行「代码任务先读 `<本仓库绝对路径>/adapters/trae/SKILL.md`」。
-- Claude：在 `~/.claude/CLAUDE.md` 或项目 `CLAUDE.md` 加同一行。
-- 其他 agent：在项目 `AGENTS.md` 加同一行。
+更多场景（只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System）见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)。
 
-如果确实要把 `SKILL.md` 复制到 agent 的 skills 目录，必须让 `docs/`、`scenarios/`、`prompts/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
+需要本地检查时再装 CLI：
 
-### 4. 让 AI 怎么说
+```bash
+npx @ultime/codecraft check --root .
+npx codecraft check --root .        # 已安装为项目依赖时
+```
 
-可直接复制的提示词见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)：审计、只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System 审计。
+本地开发 / 未发布时用 tarball：
 
-提示词只负责「怎么说」；模式、范围和规则仍以 `docs/` 为准。
+```bash
+npm pack
+npm i -D /path/to/ultime-codecraft-<version>.tgz
+npx codecraft check --root .
+```
 
-## 三种模式
+## 模式
 
 | 模式 | 是否改文件 | 对应命令 |
 |---|---|---|
@@ -101,6 +112,7 @@ codecraft <command> [options]
 | `audit` | 内置规则 + `codecraft.config.json` 里的 gates，出只读报告 |
 | `plan` | 把 findings 转成只读升级计划；默认不跑 gates |
 | `init` | 生成 app / library 骨架；默认 dry-run |
+| `install` | 把 skill 安装到 agent skills 目录；默认写入，`--dry-run` 只看计划 |
 | `version` | 输出版本号 |
 
 ### 常用
@@ -115,6 +127,9 @@ codecraft audit --config codecraft.config.json --fail-fast
 codecraft plan --root . --with-gates
 codecraft init --root . --name demo              # dry-run
 codecraft init --root . --name demo --apply      # 写盘
+codecraft install                                # 自动检测并安装
+codecraft install --agent trae,claude --force
+codecraft install --dry-run
 ```
 
 ### 参数
@@ -132,13 +147,18 @@ codecraft init --root . --name demo --apply      # 写盘
 | `--with-gates` | — | 关 | `plan` 执行 gates |
 | `--name <name>` | 字符串 | — | `init` 的 app / package 名称；`--apply` 时必填 |
 | `--apply` | — | 关 | `init` 写盘；已存在路径跳过，不覆盖 |
+| `--agent <list>` | `auto` / `claude` / `trae` / `cursor` / `generic` | `auto` | `install` 目标，可逗号分隔 |
+| `--global` | — | 关 | `install` 写入用户目录 |
+| `--dest <path>` | 目录 | — | `install` 的显式目标 |
+| `--force` | — | 关 | `install` 覆盖已有 codecraft 目录 |
+| `--dry-run` | — | 关 | `install` 只输出计划，不写盘 |
 
 ### 退出码
 
 | 码 | 含义 |
 |---|---|
 | `0` | 通过；warning 不阻断 |
-| `1` | 有 error findings，或有 gate 失败 |
+| `1` | 有 error findings、install 失败，或有 gate 失败 |
 | `2` | 用法错误、root 不存在、配置非法 |
 
 ### 输出
@@ -174,7 +194,7 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
   "pack": "auto",
   "gates": [
     { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
-    { "name": "kit", "run": "pnpm kit:check", "timeoutMs": 120000 }
+    { "name": "test", "run": "pnpm test", "timeoutMs": 120000 }
   ]
 }
 ```
@@ -188,14 +208,16 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
 ## 目录
 
 ```text
+SKILL.md      标准 agent skill 入口（skills-npm / install 使用）
 docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI 提示词、门禁
 scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
-adapters/     generic / Trae / Claude 入口
+adapters/     generic / Trae / Claude 手动指针
 prompts/      输出格式
-src/ + bin/   CLI
+src/ + bin/   CLI（含 install）
 tests/        node:test 用例
 templates/    init --apply 的 app / library 骨架
 evals/        golden tasks（人工回归）
+ROADMAP.md    后续版本计划与交接说明
 ```
 
 ## 版本与稳定承诺
@@ -203,6 +225,7 @@ evals/        golden tasks（人工回归）
 - semver；当前版本见 [VERSION](./VERSION)。
 - 规则 ID `A1–A21` 稳定；增删规则属于 minor 以上的变更。
 - 报告始终携带版本号；跨版本对比以 JSON 为准。
+- 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/codecraft/ROADMAP.md)。
 
 ## 边界
 

package/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: codecraft
+description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
+---
+
+# Codecraft（代码手艺）
+
+## 先读
+
+1. 项目 `AGENTS.md` / `rules/`
+2. `docs/00-constitution.md`
+3. 只读相关族卡：`docs/01-family-cards.md`
+4. 设计架构时：`docs/06-architecture.md`
+5. 需要选型时：`docs/05-patterns.md`
+6. 选一个场景：`scenarios/`
+7. 按 `docs/02-ai-contract.md` 执行
+8. 按 `prompts/output.md` 输出
+9. 不知道怎么说时：`docs/07-ai-prompts.md`
+
+## 模式
+
+- **Audit（审计）**：只读，出报告。
+- **Plan（计划）**：只读，出架构 / 升级计划。
+- **Apply（执行）**：改代码 + 跑门禁。
+
+## 工作流
+
+1. 判定任务属于哪个场景。
+2. 只读相关族卡，不要一次加载全部。
+3. 先出计划；Apply 前确认范围。
+4. 跑项目验证命令；不能跑要说明原因。
+5. 按 `prompts/output.md` 输出。
+
+## 禁止
+
+- Audit / Plan 模式改文件。
+- 把业务逻辑放进 Transport 或 Page。
+- 内部代码 import `external/` 或生成类型。
+- 手改生成物。
+- 写敏感信息；发现即停止、脱敏、提示轮换。
+- 安全红线登记例外。
+
+规则正文只在 `docs/`；本文件只做入口。

package/VERSION

@@ -1 +1 @@
-1.0.2
+1.1.0

package/adapters/README.md

@@ -9,4 +9,6 @@ Core 是 `docs/` + `scenarios/` + `scripts/`；adapters 只做入口，不复制
 
 规则：adapter 只写“读什么、按什么流程、输出什么”，规则正文留在 `docs/`。
 
+包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills-npm` / `codecraft install` 使用）；本目录的平台文件用于手动指针接入。两者二选一，不要同时维护两套正文。
+
 使用者提示词（怎么对 AI 说）：[`../docs/07-ai-prompts.md`](../docs/07-ai-prompts.md)。

package/adapters/claude/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codecraft
-description: Language-agnostic code standard for designing, auditing, reviewing, and refactoring code. Use when the user asks to design a project architecture, audit an existing project, produce a code review, or scaffold code under a project's code constitution.
+description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
 ---
 
 # Codecraft（代码手艺）

package/adapters/trae/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codecraft
-description: Language-agnostic code standard for designing, auditing, reviewing, and refactoring code. Use when the user asks to design a project architecture, audit an existing project, produce a code review, or scaffold code under a project's code constitution.
+description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
 ---
 
 # Codecraft（代码手艺）

package/codecraft.config.example.json

@@ -7,8 +7,8 @@
       "timeoutMs": 120000
     },
     {
-      "name": "kit",
-      "run": "pnpm kit:check",
+      "name": "test",
+      "run": "pnpm test",
       "timeoutMs": 120000
     }
   ]

package/docs/00-constitution.md

@@ -1,7 +1,7 @@
-# 代码宪法 v0（语言无关）
+# 代码宪法 v1（语言无关）
 
-> 2026-10-26 · v0 草稿，等确认后固化为 v1。
-> 用途：给人和 AI 的共同约束；语言无关，具体语法见《代码族卡 v0》。
+> 2026-10-27 · v1 稳定版。
+> 用途：给人和 AI 的共同约束；语言无关，具体语法见《代码族卡 v1》。
 > 读者：团队 / AI（Design Specification）。
 > 术语：English（中文）。
 

package/docs/01-family-cards.md

@@ -1,7 +1,7 @@
-# 代码族卡 v0（11 个环节）
+# 代码族卡 v1（11 个环节）
 
-> 2026-10-26 · v0 草稿。
-> 用途：把《代码宪法 v0》落到每个代码族（环节）；不同族可以不同形状，族内必须同形。
+> 2026-10-27 · v1 稳定版。
+> 用途：把《代码宪法 v1》落到每个代码族（环节）；不同族可以不同形状，族内必须同形。
 > 术语：English（中文）。
 
 ## 0. 卡模板
@@ -72,7 +72,7 @@
   - UI 类型（`XxxProps / XxxEmits`）放组件目录或 `types/<domain>`。
 - **项目决策**：`shared` 不是强制层；后端非 TS 时用 external + Wrapper；只有一个消费者时不建 shared。
 - **特殊**：`shared/types/` 不能变成杂物间；跨应用业务类型用 `packages/domain-<x>`。
-- **命名**：按《代码宪法 v0》§3.1（外部保持原名；通用中性；业务后缀角色；不用 `I` / `model_xxx`）；本卡不重复全表。
+- **命名**：按《代码宪法 v1》§3.1（外部保持原名；通用中性；业务后缀角色；不用 `I` / `model_xxx`）；本卡不重复全表。
 - **依赖**：General ← Business；Business 不 import External；UI 只消费 Business / General。
 - **契约**：外部类型只被 Wrapper import；页面 / 组件 / 行为层只用内部类型。
 - **状态与错误**：类型里不允许不可能组合；互斥状态用联合类型。

package/docs/02-ai-contract.md

@@ -1,13 +1,13 @@
-# AI 生成契约 v0
+# AI 生成契约 v1
 
-> 2026-10-26 · v0 草稿。
-> 用途：所有模型 / agent 生成或修改代码前先读；与《代码宪法 v0》《代码族卡 v0》配套。
+> 2026-10-27 · v1 稳定版。
+> 用途：所有模型 / agent 生成或修改代码前先读；与《代码宪法 v1》《代码族卡 v1》配套。
 > 术语：English（中文）。
 
 ## 1. 先读
 
-1. 《代码宪法 v0》
-2. 相关《代码族卡 v0》
+1. 《代码宪法 v1》
+2. 相关《代码族卡 v1》
 3. 设计架构时：`06-architecture.md`（档位 / 七步法 / 边界 / ADR）
 4. 需要选型时：`05-patterns.md`（按力选，不按名字选）
 5. 项目覆盖：`AGENTS.md` / `rules/` / `README`
@@ -23,7 +23,7 @@
 - 禁止手改生成物。
 - 禁止空 catch / 静默失败。
 - 禁止跨族复制而不登记母版与分叉点。
-- 禁止复制项目门禁（如 `kit:check`）；只通过 config 调用。
+- 禁止复制项目门禁（如 typecheck / lint / test）；只通过 config 调用。
 - 禁止在 Plan 模式改文件；只输出计划。
 - 禁止把密码 / 密钥 / 令牌 / AK/SK / 连接串 / 客户隐私写进代码、文档、示例或提示词；发现即脱敏并提醒。
 - 禁止外部文档引用内部文档 / 内部路径 / 内部主机名。

package/docs/04-gates.md

@@ -6,8 +6,8 @@
 
 | 层 | 负责 | 例子 | 是否内置 |
 |---|---|---|---|
-| **Universal（通用）** | Codecraft | A2 / A4 / A11 / A17、密钥扫描、文档路径 | 是 |
-| **Business（业务）** | 项目 | typecheck、单测、`kit:check`、契约测试、视觉回归、迁移检查 | 否，通过 config 调用 |
+| **Universal（通用）** | Codecraft | A2 / A11 / A17、密钥扫描、文档路径 | 是 |
+| **Business（业务）** | 项目 | typecheck、单测、lint、契约测试、视觉回归、迁移检查 | 否，通过 config 调用 |
 
 原则：**通用规则内置，业务门禁编排。** 不复制项目门禁，避免第二套实现。
 
@@ -29,7 +29,7 @@
   "pack": "auto",
   "gates": [
     { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
-    { "name": "kit", "run": "pnpm kit:check", "timeoutMs": 120000 }
+    { "name": "test", "run": "pnpm test", "timeoutMs": 120000 }
   ]
 }
 ```
@@ -44,7 +44,7 @@
 |---|---|---|
 | **App** | A17 / A21（A4 人工评审） | typecheck、单测、e2e、视觉回归 |
 | **Library** | A2 / A11 / A21 | build、单测、exports 检查、依赖对账 |
-| **Design System** | A2 / A11 / A21 | `kit:check`、契约快照、视觉回归、a11y |
+| **Design System** | A2 / A11 / A21 | 构建、契约快照、视觉回归、a11y |
 | **Docs** | A21 | 死链、三线头、交付白名单 |
 
 ### 4.1 内置规则

package/docs/07-ai-prompts.md

@@ -6,7 +6,22 @@
 
 ## 1. 先让 AI 找到 Codecraft
 
-在项目的 agent 入口里留一条指针，不要复制规则：
+最快的方式：
+
+```bash
+npx @ultime/codecraft install
+```
+
+或走 npm 同步：
+
+```bash
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
+```
+
+装好后项目里会有 `.agents/skills/codecraft/SKILL.md`（以及检测到的 agent 目录）。
+
+也可以手动在 agent 入口里留一条指针，不要复制规则：
 
 - Trae：项目 `.trae/rules/codecraft.md`
 - Claude：`CLAUDE.md`

package/evals/golden-tasks.md

@@ -97,7 +97,7 @@
 
 - 输入：`packages/` 下的 UI 包，README 引用了内部 `docs/开发计划/...`，`dist/tokens.css` 缺标记。
 - 模式：Audit（`--pack design-system`）。
-- 期望：命中 A11 / A21；不重复实现 `kit:check`；给出改为自洽文档的最小改法。
+- 期望：命中 A11 / A21；不重复实现项目的 typecheck / lint / test 门禁；给出改为自洽文档的最小改法。
 - 失败信号：只报 library 规则；把内部文档路径当正常引用；建议复制项目门禁。
 
 ## 15. 密钥扫描
@@ -107,6 +107,13 @@
 - 期望：命中 A21；只报文件与行号，不回显密钥；提示轮换。
 - 失败信号：漏报；把密钥原文打印到报告；把普通变量名误报为密钥。
 
+## 16. 安装到 agent
+
+- 输入：空项目，无 agent 配置目录。
+- 命令：`codecraft install --root . --agent generic`；再执行一次；最后 `--force`。
+- 期望：生成 `.agents/skills/codecraft/SKILL.md`、`docs/`、`scenarios/`、`prompts/`；第二次 skip；`--force` 覆盖。
+- 失败信号：复制到错误目录；覆盖用户已有内容；`SKILL.md` 引用断链。
+
 ## 评分
 
 - 每条任务：pass / fail。

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Language-agnostic code standard as an installable skill package.",
   "keywords": [
     "ai",
     "code-standard",
     "lint",
-    "skill"
+    "skill",
+    "audit",
+    "architecture",
+    "review",
+    "scaffold",
+    "agent-skills"
   ],
+  "author": "UltimeLam",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,6 +31,7 @@
     "codecraft": "bin/codecraft.mjs"
   },
   "files": [
+    "SKILL.md",
     "bin",
     "src",
     "docs",

package/src/cli.mjs

@@ -4,6 +4,7 @@ import { check } from './check.mjs'
 import { loadConfig, runGates } from './gates.mjs'
 import { buildPlan, summarizePlan } from './plan.mjs'
 import { applyInitPlan, buildInitPlan } from './init.mjs'
+import { applyInstallPlan, buildInstallPlan, parseAgents } from './install.mjs'
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 const VERSION = PACKAGE.version
@@ -15,12 +16,18 @@ Commands:
   audit       check + configured gates; read-only report
   plan        Read-only upgrade plan from findings
   init        Scaffold an app or package (dry-run unless --apply)
+  install     Install the skill into agent skills directories
   version     Print version
 
 Options:
   --root <path>            Project root (default: cwd)
   --pack app|library|design-system|auto  Rule pack (default: auto)
   --config <path>          Config file (default: codecraft.config.json)
+  --agent auto|claude|trae|cursor|generic  Install target, comma-separated (default: auto)
+  --global                 Install into the home directory
+  --dest <path>            Explicit destination (relative to root / home)
+  --force                  Replace an existing codecraft skill directory
+  --dry-run                Show the install plan without writing
   --no-gates               Skip gates in audit / plan
   --with-gates             Run configured gates in plan
   --fail-fast              Stop gates after the first failure
@@ -51,7 +58,7 @@ export function main(argv) {
   }
 
   const command = args.command || 'check'
-  if (!['check', 'audit', 'plan', 'init'].includes(command)) {
+  if (!['check', 'audit', 'plan', 'init', 'install'].includes(command)) {
     console.error(`codecraft: unknown command "${command}"`)
     return 2
   }
@@ -62,6 +69,42 @@ export function main(argv) {
     return 2
   }
 
+  if (command === 'install') {
+    let agents
+    try {
+      agents = parseAgents(args.agent)
+    } catch (error) {
+      console.error(`codecraft: ${error.message}`)
+      return 2
+    }
+    try {
+      const plan = buildInstallPlan(root, { agents, global: args.global, dest: args.dest })
+      const applied = args.dryRun ? null : applyInstallPlan(plan, { force: args.force })
+      const meta = {
+        version: VERSION,
+        mode: 'install',
+        root,
+        scope: args.global ? 'global' : 'project',
+        agent: args.agent,
+        dest: args.dest || null,
+        dryRun: args.dryRun,
+        targets: plan.length,
+        created: applied?.created.length ?? 0,
+        replaced: applied?.replaced.length ?? 0,
+        skipped: applied?.skipped.length ?? 0,
+      }
+      if (args.format === 'json') {
+        console.log(JSON.stringify({ ...meta, plan, applied }, null, 2))
+      } else {
+        console.log(formatInstall(meta, plan, applied))
+      }
+      return plan.length ? 0 : 1
+    } catch (error) {
+      console.error(`codecraft: ${error.message}`)
+      return 1
+    }
+  }
+
   let config
   try {
     config = loadConfig(root, args.config)
@@ -180,6 +223,11 @@ function parseArgs(argv) {
     failFast: false,
     name: '',
     apply: false,
+    agent: 'auto',
+    global: false,
+    dest: '',
+    force: false,
+    dryRun: false,
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -196,7 +244,12 @@ function parseArgs(argv) {
     else if (arg === '--with-gates') args.withGates = true
     else if (arg === '--fail-fast') args.failFast = true
     else if (arg === '--apply') args.apply = true
+    else if (arg === '--global') args.global = true
+    else if (arg === '--force') args.force = true
+    else if (arg === '--dry-run') args.dryRun = true
     else if (arg === '--name') args.name = argv[++i] ?? ''
+    else if (arg === '--agent') args.agent = argv[++i] ?? 'auto'
+    else if (arg === '--dest') args.dest = argv[++i] ?? ''
     else if (arg === '--root') args.root = argv[++i] ?? '.'
     else if (arg === '--pack') args.pack = argv[++i] ?? 'auto'
     else if (arg === '--config') args.config = argv[++i] ?? ''
@@ -329,6 +382,49 @@ function formatInit(meta, plan, applied) {
   return lines.filter((line, index) => !(line === '' && lines[index - 1] === '')).join('\n')
 }
 
+function formatInstall(meta, plan, applied) {
+  const lines = [
+    '# Codecraft Install',
+    '',
+    `- Version: ${meta.version}`,
+    `- Mode: install`,
+    `- Scope: ${meta.scope}`,
+    `- Agent: ${meta.agent}`,
+    `- Root: ${meta.root}`,
+    `- Dest: ${meta.dest ?? '（auto）'}`,
+    `- Dry run: ${meta.dryRun}`,
+    `- Targets: ${meta.targets}`,
+  ]
+
+  if (applied) {
+    lines.push(
+      `- Created: ${meta.created}`,
+      `- Replaced: ${meta.replaced}`,
+      `- Skipped: ${meta.skipped}`,
+    )
+  }
+
+  if (!plan.length) {
+    lines.push('', '未找到可安装的目标；请用 `--agent` 指定，或先创建 agent 配置目录。')
+  } else {
+    lines.push('', '## Plan', '', '| Agent | Target | Action |', '|---|---|---|')
+    for (const entry of plan) {
+      lines.push(`| ${entry.agent} | ${entry.target} | ${entry.action} |`)
+    }
+  }
+
+  lines.push(
+    '',
+    '## Next',
+    '',
+    meta.dryRun
+      ? '- Re-run without `--dry-run` to write the skill.'
+      : '- Restart the agent or reload skills；然后说：`用 Codecraft 审计本项目，只读，不改文件。`',
+  )
+
+  return lines.join('\n')
+}
+
 function header(meta) {
   return [
     `# Codecraft ${title(meta.mode)}`,

package/src/install.mjs

@@ -0,0 +1,100 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url))
+const SKILL_FILES = ['SKILL.md']
+const SKILL_DIRS = ['docs', 'scenarios', 'prompts']
+
+const AGENT_DIRS = {
+  claude: '.claude/skills',
+  trae: '.trae/skills',
+  cursor: '.cursor/skills',
+  generic: '.agents/skills',
+}
+
+const AGENT_MARKERS = {
+  claude: ['.claude', 'CLAUDE.md'],
+  trae: ['.trae'],
+  cursor: ['.cursor'],
+  generic: ['.agents'],
+}
+
+export const AGENTS = Object.keys(AGENT_DIRS)
+
+export function parseAgents(value) {
+  if (!value || value === 'auto') return []
+  const agents = [...new Set(value.split(',').map((item) => item.trim()).filter(Boolean))]
+  const invalid = agents.filter((agent) => !AGENTS.includes(agent))
+  if (invalid.length) {
+    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：auto, ${AGENTS.join(', ')}）`)
+  }
+  return agents
+}
+
+export function buildInstallPlan(root, options = {}) {
+  const base = options.global ? os.homedir() : path.resolve(root)
+  const explicit = options.agents ?? []
+  const invalid = explicit.filter((agent) => !AGENTS.includes(agent))
+  if (invalid.length) {
+    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：${AGENTS.join(', ')}）`)
+  }
+
+  const agents = explicit.length ? explicit : detectAgents(base, options.global)
+  const destinations = options.dest
+    ? [{ agent: 'custom', dir: path.resolve(base, options.dest) }]
+    : agents.map((agent) => ({ agent, dir: path.join(base, AGENT_DIRS[agent]) }))
+
+  assertSource()
+
+  return destinations.map(({ agent, dir }) => {
+    const target = path.join(dir, 'codecraft')
+    const exists = fs.existsSync(target)
+    return { agent, target, exists, action: exists ? 'exists' : 'create' }
+  })
+}
+
+export function applyInstallPlan(plan, options = {}) {
+  const created = []
+  const skipped = []
+  const replaced = []
+
+  for (const entry of plan) {
+    if (entry.exists && !options.force) {
+      skipped.push(entry.target)
+      continue
+    }
+    if (entry.exists) {
+      fs.rmSync(entry.target, { recursive: true, force: true })
+      replaced.push(entry.target)
+    }
+
+    fs.mkdirSync(entry.target, { recursive: true })
+    for (const file of SKILL_FILES) {
+      fs.copyFileSync(path.join(PACKAGE_ROOT, file), path.join(entry.target, file))
+    }
+    for (const dir of SKILL_DIRS) {
+      fs.cpSync(path.join(PACKAGE_ROOT, dir), path.join(entry.target, dir), { recursive: true })
+    }
+    created.push(entry.target)
+  }
+
+  return { created, skipped, replaced }
+}
+
+function detectAgents(base, global) {
+  const found = AGENTS.filter((agent) =>
+    AGENT_MARKERS[agent].some((marker) => fs.existsSync(path.join(base, marker))),
+  )
+  if (global) return found.length ? found : ['generic']
+  return [...new Set([...found, 'generic'])]
+}
+
+function assertSource() {
+  for (const file of SKILL_FILES) {
+    if (!fs.existsSync(path.join(PACKAGE_ROOT, file))) {
+      throw new Error(`skill source is incomplete: missing ${file}`)
+    }
+  }
+}