推荐这个项目，shadcn（shadcn/ui 作者）做了一个 Agent Skill——让最贵的模型做审计和规划，让便宜的模型写代码。这个想法本身不新，但 shadcn 把它做成了一个可安装、可编排、带执行闭环的系统，每个设计决策都很实用。

shadcn/improve：一个 Agent Skill，让最强模型做审计，让便宜模型写代码

核心理念：把智能会累积的那部分——理解代码库、判断什么值得做、写规格——交给最强的模型。执行交给便宜的模型。这个 skill 自己从来不实现任何东西。计划就是产品。

/improve → 全局审计 → 优先级排序的发现 → 计划

用法

/improve # 全局审计 /improve quick # 快速：热点 + 最高优先级 /improve deep # 详尽：每个包、每个类别 /improve security # 关注审计（还有 perf, tests, bugs…） /improve branch # 只看当前分支改了的部分 /improve next # 产品方向建议 /improve plan <描述> # 跳过审计，直接起草一个计划 /improve review-plan <文件> # 批判和收紧已有计划 /improve execute <计划> # 派便宜执行器，审查其工作 /improve reconcile # 刷新 backlog：验证、解锁、退役

内部流程

勘查。 映射仓库：技术栈、规范、准确的构建/测试/lint 命令——这些变成每个计划的验证门。同时读取设计文档（ADR、PRD、CONTEXT.md 等），让已决定的 tradeoff 不再被重新标记。

审计。 并行分派子 agent 跨 9 个类别：正确性、安全性、性能、测试覆盖、技术债务、依赖和迁移、DX、文档、方向。每个发现带 file:line 证据、影响、努力和置信度。

审查。 子 agent 会过度报告，所以 advisor 在给你看之前重新读每个引用的位置——假阳性被丢弃，错误归属被纠正，驳回被记录。

优先级排序。 发现按杠杆排序（影响 ÷ 努力，按置信度加权）。你选哪些变成计划。

计划化。 每个选中的发现一个文件，写入 plans/，带索引、优先级顺序和依赖图。

什么让这些计划可执行

计划是为最弱的合理执行者写的——一个从未见过 advisor 会话、可能小得多的模型。三个特性承载这一点：

自包含。所有上下文内联：精确文件路径、当前状态代码摘录、带示例文件的仓库规范、已验证的命令。没有“如上所述“。

验证门。每一步以命令及其预期输出结束。完成标准机器可检查。执行者永远不需要判断自己是否成功。

硬边界。明确的范围外列表，加上 STOP 条件——“如果 X，停止并报告”——而不是让小模型在现实不匹配计划时即兴发挥。

闭环

execute：派更便宜的执行器子 agent 在隔离 git worktree 里，把计划交过去，然后像 Tech Lead 一样审查——重新跑每个完成标准、检查范围合规、读 diff 对意图。通过（批准，合并始终由你决定）、退回修改（最多 2 轮）、或阻塞并精炼计划。

reconcile：验证 DONE 计划是否仍成立、调查 BLOCKED 计划并绕过障碍重写、刷新漂移的计划、退役独立修复了的发现。

–issues：把计划发布为 GitHub issues。

硬规则

从不修改源代码。唯一的写入到 plans/；执行器只在一次性 worktree 中编辑，合并始终是你的。从不运行会破坏你工作树的命令。从不复现密钥值。被要求实现？拒绝并指向计划（或提供 execute）。

项目: shadcn/improve https://github.com/shadcn/improve

#AgentSkills #CodeAudit #LLM架构

shadcn/improve

Source: https://github.com/shadcn/improve

improve

An agent skill that audits any codebase and writes implementation plans for other agents to execute.

The idea: use your most capable model for the part where intelligence compounds — understanding the codebase, judging what’s worth doing, writing the spec — and hand execution to cheaper models. The skill never implements anything itself. The plan is the product.

you          →  /improve                    (expensive model, advises)
plans/       →  001-fix-n-plus-one.md       (self-contained specs)
other agent  →  implements, tests, ships    (cheap model, executes)

Install

npx skills add shadcn/improve

Works in any agent that supports Agent Skills format. The plans it writes are plain markdown, so any agent (or human) can pick them up.

Usage

/improve                        full audit → prioritized findings → plans
/improve quick                  cheap pass: hotspots, top findings only
/improve deep                   exhaustive: every package, every category
/improve security               focused audit (also: perf, tests, bugs, ...)
/improve branch                 audit only what the current branch changes
/improve next                   feature suggestions — where to take the project
/improve plan <description>     skip the audit, spec one thing
/improve review-plan <file>     critique and tighten an existing plan
/improve execute <plan>         dispatch a cheaper executor, review its work
/improve reconcile              refresh the backlog: verify, unblock, retire
/improve ... --issues           also publish plans as GitHub issues

How to use

A typical first run, start to finish:

1. Open your agent in the repo and run /improve (or /improve quick to keep it cheap).
2. It maps the repo, audits it, and comes back with a findings table. Reply with the ones you want planned — “plan 1, 3 and 5”.
3. Plans land in plans/ — one file each, plus an index with the recommended order. Read them; they’re meant to be reviewed.
4. Hand a plan to any agent (“implement plans/001-*.md”), or let the skill run it: /improve execute 001. It dispatches a cheaper model in an isolated worktree, reviews the diff against the plan, and reports back with a verdict. Merging stays up to you.
5. Next session, run /improve reconcile to clean up the backlog: verify what landed, refresh what drifted, unblock what got stuck.

Before a PR, /improve branch does the same thing scoped to just what your branch changes.

Example

A run against shadcn/ui came back with findings like:

| # | Finding                                        | Category  | Effort | Confidence |
|---|------------------------------------------------|-----------|--------|------------|
| 1 | shadow-config duplicated in search.ts/view.ts, | tech-debt | M      | HIGH       |
|   | copies already drifted (TODO at search.ts:31)  |           |        |            |
| 2 | O(n²) icon migration (migrate-icons.ts:168)    | perf      | S      | HIGH       |

…and rejected a few, with reasons recorded so they don’t come back next run:

- [SEC-01] https_proxy env var "SSRF": by-design — standard proxy convention,
  every CLI honors it. Not a finding.

Picking #1 produced this plan — current code excerpted, exact steps, the repo’s own test/lint commands as verification gates, and STOP conditions for when reality doesn’t match.

How it works

Recon. Maps the repo: stack, conventions, and the exact build/test/lint commands — these become verification gates in every plan. It also ingests intent and design docs when present — ADRs (docs/adr/), PRDs, CONTEXT.md, DESIGN.md, PRODUCT.md — so decided tradeoffs aren’t re-flagged as findings, direction suggestions stay grounded in stated product intent, and plans speak the repo’s own vocabulary. Composes with any repo that already maintains these docs.

Audit. Fans out parallel subagents across nine categories: correctness, security, performance, test coverage, tech debt, dependencies & migrations, DX, docs, and direction (feature suggestions — every one must cite evidence from the repo itself, no generic idea-slop). Every finding carries file:line evidence, impact, effort, and confidence.

Vet. Subagents over-report, so the advisor re-reads every cited location itself before showing you anything — false positives get dropped, wrong attributions get corrected, rejections get recorded.

Prioritize. Findings land in a table ordered by leverage (impact ÷ effort, weighted by confidence). You pick what becomes plans.

Plan. One file per selected finding, written into plans/ with an index, priority order, and dependency graph.

What makes the plans executable

Plans are written for the weakest plausible executor — a model that has never seen the advisor session and may be much smaller. Three properties carry that:

• Self-contained. All context is inlined: exact file paths, current-state code excerpts, repo conventions with an exemplar file, verified commands. No “as discussed above.”
• Verification gates. Every step ends with a command and its expected output. Done criteria are machine-checkable. The executor never has to judge whether it succeeded.
• Hard boundaries. Explicit out-of-scope lists, and STOP conditions — “if X, stop and report” — instead of letting a small model improvise when reality doesn’t match the plan.

Each plan also stamps the git commit it was written against, so executors run a mechanical drift check before touching anything.

Closing the loop

Plans aren’t fire-and-forget:

• execute <plan> spawns a cheaper executor subagent in an isolated git worktree, hands it the plan, then reviews the result like a tech lead — re-runs every done criterion, checks scope compliance, reads the diff against intent. Verdict: approve (merging stays your call), send back for revision (max 2 rounds), or block and refine the plan.
• reconcile processes what happened since: verifies DONE plans still hold, investigates BLOCKED ones and rewrites around the obstacle, refreshes drifted plans, retires findings that got fixed independently.
• --issues publishes plans as GitHub issues — same self-contained body, so any agent or human can pick them up where work already lives.

Hard rules

• Never modifies source code itself. The only writes go to plans/; executors edit only in disposable worktrees, and merging is always yours.
• Never runs commands that mutate your working tree — read, search, and read-only analysis only.
• Never reproduces secret values. Locations and credential types only, rotation always recommended.
• Asked to implement? It declines and points at the plan (or offers execute).

License

MIT © shadcn