# shadcn/improve: kiểm tra code, viết kế hoạch cho model rẻ làm — hướng dẫn cài đặt và dùng

> shadcn/improve là một skill (kỹ năng) cho AI agent. Nó dùng model mạnh nhất của bạn để kiểm tra codebase, rồi viết các bản kế hoạch bằng markdown để model rẻ hơn hoặc người khác làm theo. Cài chỉ bằng một lệnh npx, nhưng cần có sẵn một AI agent hỗ trợ định dạng Agent Skills.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-16 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/shadcn-improve-kiem-tra-code-viet-ke-hoach-cho-ai-agent

shadcn/improve là một skill cho AI agent. Bạn gõ `/improve` trong repo của mình, nó đọc toàn bộ codebase, tìm ra những chỗ đáng sửa, rồi viết thành từng bản kế hoạch (plan) chi tiết. Skill này không tự sửa code. Sản phẩm của nó là bản kế hoạch.

Ý tưởng khá thực tế: phần khó nhất là hiểu code, cân nhắc việc nào đáng làm và viết rõ yêu cầu. Phần này nên giao cho model thông minh nhất, dù tốn tiền hơn. Phần thực thi, tức là gõ code theo kế hoạch, thì giao cho model rẻ hơn. Một model nhỏ làm rất tốt nếu được đưa một bản hướng dẫn đủ rõ.

Nếu bạn là lập trình viên mới, chủ một dự án nhỏ, hay người quản lý một nhóm dùng AI để viết code, repo này đáng thử. Hiện có khoảng 11.508 sao và 466 fork, giấy phép MIT. Điểm đáng giá nhất là các bản kế hoạch được viết để "model yếu nhất cũng làm theo được": có đoạn code hiện tại, các bước cụ thể, lệnh kiểm tra và điều kiện dừng.

```repo
- repo | shadcn/improve
- kind | Skill
- desc | Skill cho AI agent: dùng model mạnh nhất kiểm tra codebase và viết kế hoạch chi tiết, để model rẻ hơn thực hiện.
- stars | 12k
- license | MIT
```

## improve làm được gì

### Kiểm tra cả codebase theo nhiều nhóm

Skill chạy nhiều subagent song song để soi chín nhóm: lỗi logic (correctness), bảo mật, hiệu năng, độ phủ test, nợ kỹ thuật, phụ thuộc và nâng cấp, trải nghiệm lập trình viên (DX), tài liệu, và hướng phát triển (gợi ý tính năng). Mỗi phát hiện đều ghi rõ `file:dòng`, mức tác động, công sức và độ tin cậy. Bạn không phải nghe một nhận xét chung chung kiểu "code nên tốt hơn".

### Tự kiểm tra lại trước khi báo cho bạn

Các subagent hay báo thừa. Vì vậy model chính đọc lại từng vị trí được trích dẫn trước khi cho bạn xem. Phát hiện sai bị loại, gán nhầm thì được sửa, và lý do loại được ghi lại để lần sau không nhắc lại. Điều này tiết kiệm thời gian cho bạn, vì khỏi phải đi kiểm chứng những "lỗi" không có thật.

### Hiểu bối cảnh dự án

Bước đầu tiên là "recon": skill xem repo dùng công nghệ gì, quy ước ra sao, và lệnh build, test, lint chính xác là gì. Các lệnh này được đưa vào mỗi kế hoạch làm cổng kiểm tra. Nếu repo có tài liệu thiết kế như ADR (`docs/adr/`), PRD, `CONTEXT.md`, `DESIGN.md`, `PRODUCT.md`, skill đọc luôn. Nhờ đó những quyết định đã chốt không bị báo lại thành lỗi.

### Bảng ưu tiên và kế hoạch dạng file

Các phát hiện được xếp theo "đòn bẩy" (tác động chia công sức, có tính độ tin cậy). Bạn chọn cái nào muốn lập kế hoạch. Mỗi cái thành một file trong thư mục `plans/`, kèm một file chỉ mục có thứ tự đề xuất và quan hệ phụ thuộc giữa các kế hoạch.

### Kế hoạch đủ rõ để model nhỏ làm theo

- **Tự chứa đủ thông tin:** có đường dẫn file, đoạn code hiện tại, quy ước của repo và lệnh đã được xác minh. Không có kiểu "như đã nói ở trên".
- **Cổng kiểm tra:** mỗi bước kết thúc bằng một lệnh và kết quả mong đợi, nên người thực thi không phải tự phán đoán đã xong hay chưa.
- **Ranh giới cứng:** có danh sách việc không được làm và điều kiện DỪNG ("nếu gặp X thì dừng và báo"), thay vì để model nhỏ tự ứng biến.

Mỗi kế hoạch còn ghi mã commit git lúc được viết, để người thực thi kiểm tra xem code đã đổi nhiều chưa trước khi bắt tay làm.

### Khép vòng: thực thi, đối chiếu, xuất issue

`/improve execute` gọi một model rẻ hơn làm trong một worktree git tách biệt, rồi kiểm tra kết quả như một tech lead. Skill chạy lại các tiêu chí hoàn thành, kiểm tra việc có làm ngoài phạm vi không và đọc diff so với mục đích. `/improve reconcile` dọn lại danh sách việc ở phiên sau. `--issues` đăng kế hoạch lên GitHub issue.

## Cần chuẩn bị gì

Tư liệu của repo nói rất ít về yêu cầu hệ thống, nên mình chỉ nêu những gì có thật:

- **Một AI agent hỗ trợ định dạng Agent Skills.** README ghi skill chạy được ở bất kỳ agent nào hỗ trợ định dạng này. README không liệt kê tên agent cụ thể.
- **Một repo code để kiểm tra.** Bạn mở agent ngay trong thư mục dự án cần audit.
- **Lệnh `npx`** để cài. README không nói rõ phiên bản Node.js nào. Thường `npx` đi kèm Node.js, nhưng bạn nên xem lại tài liệu trong repo nếu gặp lỗi.
- **Git.** Chế độ `execute` dùng worktree git và kế hoạch ghi mã commit, nên dự án của bạn nên là một repo git. README không nói thẳng điều này, đây là suy ra từ cách skill hoạt động.
- **Tài khoản GitHub** chỉ cần nếu bạn dùng cờ `--issues`. README không nói chi tiết cách xác thực.

README không nói gì về hệ điều hành, phần cứng hay API key riêng của skill. Chi phí chủ yếu đến từ model mà agent của bạn đang dùng.

## Cài đặt từng bước

```steps
- Mở terminal | Mở terminal bình thường trên máy của bạn
- Cài skill | Chạy một lệnh npx để thêm skill vào agent
- Vào repo cần audit | Mở agent trong thư mục dự án của bạn
- Chạy thử | Gõ /improve quick để xem bản audit nhẹ
```

### Mở terminal

Trên Windows bạn có thể mở PowerShell hoặc Terminal. Trên Mac hoặc Linux thì mở Terminal. Lúc cài skill, thư mục hiện tại không quá quan trọng, nhưng bạn nên quen với việc mở terminal ngay trong thư mục dự án để tiện bước sau.

### Cài skill

README chỉ có một lệnh cài:

```bash
npx skills add shadcn/improve
```

Lệnh này tải skill `shadcn/improve` và thêm vào agent của bạn. Chỗ người mới hay vấp là gõ lệnh trong ô chat của agent. Thực ra đây là lệnh terminal, nên bạn gõ vào cửa sổ terminal. Nếu máy báo không tìm thấy `npx`, nghĩa là máy chưa có Node.js.

Repo có thư mục `.claude-plugin/`, nhưng README không ghi cách cài theo kiểu plugin. Nếu muốn thử đường đó, bạn xem trực tiếp thư mục này trong repo.

### Vào repo cần audit

Bạn dùng lệnh phổ thông để vào thư mục dự án, rồi mở agent ở đó. Ví dụ:

```bash
cd duong-dan/toi/du-an-cua-ban
```

Đổi `duong-dan/toi/du-an-cua-ban` thành đường dẫn thật. Skill đọc code ở thư mục hiện tại, nên mở agent sai thư mục là nó audit sai chỗ. Cách khởi động agent tuỳ loại agent bạn dùng, README không nói.

### Chạy thử lần đầu

Trong agent, gõ:

```
/improve quick
```

Đây là chế độ rẻ: chỉ xét các điểm nóng và báo những phát hiện hàng đầu. Chạy `/improve` đầy đủ sẽ tốn nhiều lượt gọi model hơn.

```note
Skill chạy model mạnh nên có thể tốn token. Lần đầu hãy dùng /improve quick. Skill cam kết không chép giá trị bí mật (key, mật khẩu) vào kết quả, chỉ ghi vị trí và loại thông tin, kèm khuyến nghị đổi key. Dù vậy, bạn vẫn nên xem lại các file trong plans/ trước khi đưa cho người khác.
```

## Kiểm tra đã chạy được chưa

Bạn biết skill cài thành công khi gõ `/improve` trong agent mà agent nhận ra lệnh này, không báo "lệnh không tồn tại". Nếu chưa nhận, hãy thử mở lại agent sau khi cài.

Sau khi chạy `/improve quick`, kết quả mong đợi theo README là:

1. Skill lập bản đồ repo, rồi audit.
2. Nó trả về một bảng phát hiện có các cột: số thứ tự, mô tả phát hiện, nhóm (ví dụ `perf`, `tech-debt`), công sức (S, M…) và độ tin cậy (HIGH…).
3. Bạn trả lời những mục muốn lập kế hoạch, ví dụ "plan 1, 3 and 5". Sau đó thư mục `plans/` xuất hiện trong dự án, mỗi phát hiện một file kèm một file chỉ mục.

Thấy thư mục `plans/` có file là bạn đã dùng được skill. README không đưa ra một lệnh "kiểm tra phiên bản" riêng.

## Dùng vào việc thật

### Lập trình viên mới nhận một dự án cũ

Bạn vừa nhận một codebase mà chẳng ai còn nhớ rõ. Bạn mở agent trong thư mục dự án và chạy:

```
/improve quick
```

Skill đọc repo và trả về bảng phát hiện, mỗi dòng có `file:dòng` để bạn tự mở ra xem. Bạn chọn vài việc nhỏ, rõ, ví dụ "plan 1 and 2". Kết quả là các file như `plans/001-...md` có đoạn code hiện tại, các bước sửa và lệnh kiểm tra. Bạn vừa có danh sách việc cần làm, vừa hiểu thêm về dự án nhờ đọc những kế hoạch này.

### Trước khi mở pull request

Bạn đã sửa xong một nhánh và muốn rà lại trước khi nhờ người khác review. Bạn chạy:

```
/improve branch
```

Skill chỉ audit những gì nhánh hiện tại thay đổi, nên nhanh và gọn hơn audit cả repo. Kết quả vẫn là bảng phát hiện kèm lý do, để bạn sửa sớm những chỗ dễ bị góp ý. Nếu bạn muốn tập trung vào một mảng, README cho biết có chế độ audit tập trung như `/improve security` (và các nhóm khác như `perf`, `tests`, `bugs`).

> Phần đắt giá nhất là suy nghĩ và viết rõ yêu cầu. Còn gõ code theo yêu cầu đó thì model rẻ cũng làm được.
>
> — Ông T

### Giao việc cho model rẻ và duyệt kết quả

Bạn đã có `plans/001-*.md` và muốn tiết kiệm. Có hai cách. Cách thứ nhất là đưa kế hoạch cho bất kỳ agent nào, ví dụ nhắn:

```
implement plans/001-*.md
```

Cách thứ hai là để skill tự điều phối:

```
/improve execute 001
```

Skill gọi một model rẻ hơn làm trong worktree tách biệt, nên thư mục làm việc chính của bạn không bị đụng. Xong, model mạnh kiểm tra lại: chạy lại tiêu chí hoàn thành, soát phạm vi, đọc diff. Bạn nhận một phán quyết: duyệt, gửi lại để sửa (tối đa 2 vòng), hoặc chặn và làm rõ lại kế hoạch. Việc merge luôn do bạn quyết định.

### Dọn danh sách việc sau vài ngày và đưa lên GitHub

Sang phiên làm việc sau, code đã đổi, có kế hoạch đã xong, có cái bị kẹt. Bạn chạy:

```
/improve reconcile
```

Skill kiểm tra lại những kế hoạch đã xong, tìm hiểu cái bị kẹt và viết lại cho vòng qua trở ngại, làm mới kế hoạch đã lệch, bỏ những phát hiện đã được sửa theo cách khác. Nếu nhóm bạn quản lý việc trên GitHub, thêm cờ `--issues` vào lệnh audit hoặc lập kế hoạch để kế hoạch được đăng thành GitHub issue, nội dung tự chứa đủ để người hoặc agent khác nhặt lên làm.

## Lỗi hay gặp và cách xử lý

### Gõ `npx skills add shadcn/improve` mà báo không có `npx`

Máy chưa có Node.js hoặc terminal chưa nhận đường dẫn. Cài Node.js từ trang chính thức, đóng và mở lại terminal rồi chạy lại. Đây là lỗi môi trường chung chứ không riêng skill này.

### Gõ `/improve` mà agent không nhận

Có thể agent của bạn chưa hỗ trợ định dạng Agent Skills, hoặc agent cần khởi động lại sau khi cài. README chỉ nói skill chạy với agent hỗ trợ định dạng này. Hãy kiểm tra tài liệu của agent bạn đang dùng, và thử mở lại agent trong đúng thư mục dự án.

### Bảng phát hiện có vẻ quá chung chung hoặc sai

Skill đã tự đọc lại các vị trí được trích dẫn để loại phát hiện sai, nhưng không có công cụ nào hoàn hảo. Bạn hãy mở `file:dòng` được trích ra xem thật. Chỉ chọn lập kế hoạch cho những mục có độ tin cậy cao và bạn thấy hợp lý. Ngoài ra, các phát hiện bị bác sẽ được ghi lại kèm lý do.

### Thực thi xong nhưng kết quả không như mong muốn

Đừng merge ngay. Chế độ `execute` làm việc trong worktree tách biệt và việc merge luôn là của bạn. Hãy đọc báo cáo phán quyết và diff. Nếu cần, để skill gửi lại sửa (tối đa 2 vòng) hoặc dùng `/improve review-plan <file>` để chỉnh lại kế hoạch trước.

### Chi phí token cao hơn dự tính

Chạy `/improve deep` sẽ soát từng package, từng nhóm, nên tốn nhiều hơn hẳn. Hãy bắt đầu bằng `/improve quick`, hoặc audit hẹp như `/improve security` và `/improve branch`. README không đưa con số chi phí cụ thể, nên bạn tự theo dõi mức dùng trên tài khoản model của mình.

## Có nên dùng không

**Điểm mạnh.** Skill tách rõ hai việc: suy nghĩ (model mạnh) và thực thi (model rẻ). Mỗi phát hiện đều có bằng chứng `file:dòng`, được vet lại, và kế hoạch có cổng kiểm tra cùng điều kiện dừng. Quy tắc cứng cũng đáng yên tâm: skill không tự sửa mã nguồn, chỉ ghi vào `plans/`, không chạy lệnh làm thay đổi cây làm việc của bạn, không chép giá trị bí mật, và nếu bạn bảo nó "làm luôn đi" thì nó từ chối và chỉ sang kế hoạch hoặc lệnh `execute`. Giấy phép MIT nên dùng tự do.

**Giới hạn.** Bạn cần một agent hỗ trợ định dạng Agent Skills, và bạn vẫn phải tự đọc, duyệt kế hoạch. Chất lượng phụ thuộc vào model bạn dùng. README không cho biết hiệu quả trên codebase rất lớn hay trên ngôn ngữ cụ thể nào. Nếu bạn không viết code hoặc không có repo, skill này không phục vụ được gì.

**Khi nên chọn cách khác.** Nếu chỉ cần sửa nhanh một lỗi nhỏ mà bạn đã biết rõ, nhờ agent sửa thẳng sẽ nhanh hơn việc chạy audit. Nếu bạn cần một công cụ phân tích tĩnh chạy tự động trong CI mà không cần AI, skill này cũng không thay thế được. Còn nếu bạn hay giao việc cho AI nhưng kết quả hay lạc đề, hoặc muốn xem trước và duyệt kế hoạch trước khi code bị đụng đến, improve là lựa chọn hợp lý.

## Câu hỏi thường gặp

### shadcn/improve có miễn phí không?

Repo dùng giấy phép MIT, nên bạn dùng và sửa tự do. Skill chạy trên AI agent và model của bạn, nên chi phí nằm ở lượt dùng model. README không đưa con số chi phí cụ thể.

### Cài shadcn/improve bằng lệnh nào?

README ghi một lệnh: npx skills add shadcn/improve. Skill hoạt động trong bất kỳ agent nào hỗ trợ định dạng Agent Skills. Sau khi cài, bạn gõ /improve trong agent, đang mở ở thư mục dự án.

### Skill này có tự sửa code của tôi không?

Không. README nói skill không bao giờ tự sửa mã nguồn, chỉ ghi các file kế hoạch vào thư mục plans/. Nếu bạn nhờ nó implement, nó từ chối và chỉ sang kế hoạch hoặc lệnh execute. Khi chạy execute, model rẻ hơn làm trong worktree tách biệt và việc merge luôn do bạn quyết định.

### Có cần GPU hay chạy được trên Windows không?

Tư liệu không nhắc tới GPU hay hệ điều hành cụ thể. Skill chạy bên trong agent của bạn, nên điều kiện thực tế phụ thuộc vào agent đó. Bạn nên xem tài liệu của agent đang dùng.

### Dữ liệu và bí mật trong code có an toàn không?

README ghi skill không chép giá trị bí mật vào kết quả, chỉ nêu vị trí và loại thông tin xác thực, đồng thời khuyến nghị đổi key. Còn việc code của bạn được gửi tới model nào thì phụ thuộc vào agent bạn dùng, README không nói chi tiết phần này.

### Các chế độ /improve quick, deep và branch khác nhau thế nào?

quick là lượt nhẹ, chỉ xét điểm nóng và các phát hiện hàng đầu. deep là kiểm tra toàn diện từng package và từng nhóm. branch chỉ audit những gì nhánh hiện tại thay đổi, hợp để chạy trước khi mở PR.

### Kế hoạch skill viết ra có dùng được với agent khác không?

Có. README nói kế hoạch là file markdown thuần, nên bất kỳ agent nào hoặc người đều nhặt lên làm được. Mỗi kế hoạch chứa đủ ngữ cảnh, lệnh kiểm tra và điều kiện dừng, không phụ thuộc vào phiên chat đã viết ra nó.
