shadcn/improve · 上手攻略
- 仓库：shadcn/improve
- 链接：https://github.com/shadcn/improve
- 分类：AI Agent Skill（代码审计 / 任务编排）
- 作者：Jay
- 更新：2026-07-05
它是什么
shadcn/improve 是一个 AI Agent Skill（技能包），用于对任意代码仓库进行系统性审计，并生成可交给其他 Agent 执行的具体实施方案。它的核心哲学是：用最强大的模型做判断，把执行交给更便宜的模型。
传统做法是一个模型既分析又执行，成本高且容易出错。improve 的思路是解耦这两步：
你（昂贵模型，顾问）
↓ 发现问题 → 写规格说明书
plans/001-fix-xxx.md（Markdown 格式的行动计划）
↓ 交给其他 Agent 或你自己执行
更便宜模型 / 人工 → 实施、测试、合并
这个 Skill 本身不修改任何源代码，只会生成 Markdown 格式的「计划文件」，由其他 Agent 或人类负责实施。合并代码的决策权始终在人类手中。
定位：不是通用编程助手，而是代码质量审计 + 行动规划器，属于 Agent 生态中的「规划层」工具。
解决什么问题
- 代码仓库缺乏系统性审计，靠人工 code review 效率低
- AI 编码助手（Cursor、Claude Code 等）往往缺乏对项目整体架构的理解，容易「只见树木」
- 团队希望用 AI 做代码改进，但不想把所有权限交给强模型（成本、安全风险）
- 想让便宜模型也能执行复杂重构，只需要一份清晰的可执行计划
快速安装
前置要求
需要一个支持 Agent Skills 格式的 AI 编码环境。常见支持平台：
- agentskills.io 生态（如 Claude Code、v0、Cursor 等）
- 任何实现了 Agent Skills Spec 的 Agent
⚠️ 注意：improve 是实验性项目（成熟度：experimental），生产使用前请充分测试。
安装命令
在项目根目录下执行：
npx skills add shadcn/improve
或通过 explainx.ai 平台安装（需验证发布者信誉）：
npx skills add explainx.ai/shadcn-improve
安装后，Skill 会在当前仓库创建 plans/ 目录存放生成的行动计划文件。
核心用法
基本命令（斜杠指令）
在支持 Skills 的 Agent 中，通过 /improve 调用：
| 命令 | 作用 |
|---|---|
/improve |
全量审计：扫描整个代码库，输出问题发现列表 |
/improve quick |
快速扫描：只输出最高优先级问题，控制成本 |
/improve deep |
深度审计：穷举所有包、所有分类（安全/性能/测试/技术债务等） |
/improve security |
专注安全审计（也可指定 perf/tests/bugs/tech-debt） |
/improve branch |
仅审计当前分支相对于主干的变更 |
/improve next feature |
基于代码现状提出下一个功能方向建议 |
/improve plan <描述> |
跳过审计，直接为指定需求写计划 |
/improve review-plan <文件> |
审查并优化已有的计划文件 |
/improve execute <计划文件> |
派发执行器运行计划，并在独立 git worktree 中工作 |
/improve reconcile |
刷新 backlog：验证已完成计划、重新刷新漂移计划 |
--issues 标志 |
将生成的计划发布为 GitHub Issues |
完整工作流示例
第一步：运行审计
你：在支持 Skills 的 Agent 界面，进入目标仓库根目录
输入：/improve quick
Agent 会并行扫描代码，输出如下格式的问题表：
| # | 发现 | 分类 | 投入 | 置信度 |
|---|---|---|---|---|
| 1 | shadow-config 在 search.ts/view.ts 重复且已漂移 | tech-debt | M | HIGH |
| 2 | O(n²) icon 迁移逻辑 | perf | S | HIGH |
第二步：生成计划
你：plan 1, 3 and 5
Agent 为选中的问题在 plans/ 目录生成 Markdown 计划文件，每个文件包含：
- 当前代码摘录
- 精确修改步骤
- 验证命令（如 npm test 应输出 PASS）
- 终止条件（如果 X 情况出现，停止并报告）
第三步：执行
你：implement plans/001-extract-shadow-config-resolution.md
派发给便宜模型在独立 worktree 中执行，顾问模型审查结果，人类决定是否合并。
典型适用场景
- 代码质量摸底：接手陌生代码库，快速了解主要技术债务和风险点
- PR 前自检：用
/improve branch只看当前分支改动，提前发现问题 - 多 Agent 协作：用昂贵模型规划 + 便宜模型执行，降低 AI 使用成本
- 团队代码规范落地：结合 ADRs、PRDs 等文档，让审计结果与产品意图对齐
- 安全/性能专项检查：不想做全量审计时，用
/improve security等专项命令
坑与注意
| 坑 | 说明 |
|---|---|
| 实验性项目 | 成熟度标注为 experimental，不建议直接在生产核心代码库使用 |
| 仅读不写 | Skill 本身不会修改源码，但 execute 会派发子 Agent 在 worktree 中编辑 |
| 假阳性 | 审计子 Agent 会过度报告，顾问会二次核实并丢弃假阳性，但首次运行可能信息过载 |
| 依赖文档 | 如项目有 ADRs/PRDs/CONTEXT.md 等文档，审计质量更高；空项目效果有限 |
| Agent 兼容性 | 需确认你的编码 Agent 支持 Agent Skills Spec 格式 |
| 计划质量依赖模型 | 生成的计划质量与使用的模型能力强相关，弱模型可能生成不可执行计划 |
| Secret 不泄露 | 审计不会重现实际密钥值，只报告位置和类型，但建议配合旋转策略 |
与同类对比
| 工具 | 类型 | 定位 | vs improve |
|---|---|---|---|
| shadcn/improve | Agent Skill | 规划层：审计+生成可执行计划 | 本工具 |
| Cursor / Claude Code | AI 编码助手 | 执行层：直接写代码 | 这些是执行者，improve 是规划者和审计者 |
| GitHub Copilot | 补全工具 | 单点代码补全 | 无系统性规划能力 |
| CodeRabbit | Code Review AI | PR 层面审查 | 面向 PR，improve 面向整个代码库审计 |
| Snyk / SonarQube | 静态分析 | 规则驱动扫描 | 规则固定，improve 由 LLM 驱动更灵活但更慢 |
improve 的差异化在于：它是目前少有的专注于「生成计划而非直接修改」的 Agent Skill，适合搭建「规划 Agent + 执行 Agent」的分层架构。
一句话推荐结论
如果你在使用多 Agent 协作或想让 AI 做代码改进但不想让它直接改代码，shadcn/improve 是目前将「智能审计 → 可执行计划」闭环做得最干净的 Agent Skill，直接加到工作流里就能用。
来源
- GitHub README（https://github.com/shadcn/improve）
- agentskills.io 规范文档
- explainx.ai Skill 页面
- shadcn/ui March 2026 CLI v4 更新博客
- Web 搜索：shadcn improve agent skill 用法（2026-07）