# agent-skills: bộ quy trình kỹ sư cho AI viết code — hướng dẫn cài đặt và dùng

> agent-skills của Addy Osmani là bộ 25 skill dạng Markdown, cộng 9 lệnh slash và vài persona, dạy AI coding agent (Claude Code, Cursor, Codex, Gemini CLI...) làm theo quy trình phát triển phần mềm chuẩn. Mục tiêu là để AI viết code có kế hoạch, có test, có review thay vì làm bừa. Cài bằng một lệnh npx, nên không khó với người đã quen terminal.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-12 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/agent-skills-bo-quy-trinh-ky-su-cho-ai-viet-code

agent-skills là một bộ "kỹ năng" (skill) viết bằng Markdown, dạy các AI coding agent như Claude Code, Cursor, Codex hay Gemini CLI làm việc theo quy trình của kỹ sư phần mềm có kinh nghiệm. Tác giả mô tả ngắn gọn: kỹ năng kỹ thuật cấp production cho AI coding agent. Repo hiện có khoảng 116.957 sao và 12.224 fork, giấy phép MIT.

Vấn đề nó giải quyết rất quen thuộc. Bạn nhờ AI viết một tính năng, nó lao vào code ngay, không hỏi lại yêu cầu, không viết test, không chia nhỏ công việc. Kết quả chạy được nhưng khó kiểm tra và khó sửa. Bộ skill này ép AI đi theo từng giai đoạn: định nghĩa cái cần làm, lập kế hoạch, code từng lát nhỏ, kiểm chứng, review, rồi mới đưa lên chạy thật.

Nếu bạn là lập trình viên mới, người làm sản phẩm hoặc chủ doanh nghiệp nhỏ đang dùng AI để dựng website, công cụ nội bộ, thì đây là cách rẻ nhất để AI bớt làm ẩu. Điểm đáng giá nhất: bạn không phải tự học hết quy trình. Chỉ cần gõ lệnh như `/spec` hay `/plan`, đúng skill sẽ được kích hoạt.

```repo
- repo | addyosmani/agent-skills
- kind | Skill
- desc | Bộ 25 skill Markdown giúp AI coding agent làm việc theo quy trình của kỹ sư giỏi: spec, plan, build, test, review, ship.
- stars | 117k
- lang | JavaScript
- license | MIT
```

## agent-skills làm được gì

Nói gọn, repo cho bạn bốn thứ: lệnh slash, skill, persona và checklist.

### Chín lệnh slash theo vòng đời dự án

Mỗi lệnh ứng với một giai đoạn làm phần mềm:

- `/spec`: viết đặc tả trước khi code. Nguyên tắc là "spec before code".
- `/plan`: chia việc thành các task nhỏ, rõ ràng.
- `/build`: code từng lát một.
- `/test`: coi test là bằng chứng code chạy đúng.
- `/constraints`: đặt một lần mức chất lượng tối thiểu rồi áp dụng khắp nơi.
- `/review`: review trước khi merge.
- `/webperf`: đo hiệu năng web trước khi tối ưu.
- `/code-simplify`: làm code gọn, dễ đọc hơn.
- `/ship`: đưa lên production.

Lợi ích thực tế: bạn không cần nhớ quy trình. Gõ đúng lệnh ở đúng lúc là AI biết phải làm gì.

### Chế độ /build auto

Nếu đã có spec và muốn bớt thao tác, `/build auto` tạo kế hoạch rồi làm hết các task trong một lượt. Bạn duyệt kế hoạch một lần, sau đó nó tự chạy. Theo README, mỗi task vẫn làm theo kiểu test-driven và được commit riêng, và nó dừng lại khi gặp lỗi hoặc bước rủi ro. Tức là nó bỏ việc bạn phải bấm duyệt giữa các task, chứ không bỏ việc kiểm chứng.

### 25 skill

Bộ gồm 24 skill theo vòng đời cộng một skill "meta" tên `using-agent-skills` để chọn skill phù hợp. Skill cũng tự kích hoạt theo việc bạn đang làm: thiết kế API thì dùng `api-and-interface-design`, làm giao diện thì dùng `frontend-ui-engineering`. Vài skill đáng chú ý cho người mới:

- `interview-me`: AI hỏi bạn từng câu một để moi ra bạn thật sự muốn gì, cho đến khi đủ độ tin cậy. Hợp khi yêu cầu còn mơ hồ.
- `spec-driven-development`: viết PRD (mục tiêu, lệnh, cấu trúc, phong cách code, kiểm thử, ranh giới) trước khi viết code.
- `test-driven-development`: chu trình đỏ - xanh - refactor.
- `code-review-and-quality`: review năm trục trước khi merge.
- `security-and-hardening`: phòng các lỗi kiểu OWASP Top 10, quản lý secret.
- `debugging-and-error-recovery`: quy trình năm bước khi lỗi: tái hiện, khoanh vùng, thu gọn, sửa, chặn tái phát.
- `constraint-driven-development`: phỏng vấn bạn để đặt chuẩn chất lượng, ghi vào file CONSTRAINTS.md.

### Persona và checklist

Có bốn persona chuyên biệt: `code-reviewer`, `test-engineer`, `security-auditor` và `web-performance-auditor`. Ngoài ra thư mục `references/` có các checklist tham chiếu như definition-of-done, bảo mật, hiệu năng, khả năng tiếp cận, quan sát hệ thống (observability). Skill sẽ gọi đến khi cần.

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

Tư liệu repo không liệt kê yêu cầu hệ thống chi tiết. Những gì README có nói:

- Một AI coding agent đang dùng được: Claude Code (README khuyến nghị), Cursor, Codex, Gemini CLI, Antigravity CLI, GitHub Copilot, Kiro, OpenCode, Windsurf, Command Code... hoặc bất kỳ agent nào nhận system prompt / file hướng dẫn.
- Để dùng cách cài nhanh `npx skills`, bạn cần có Node.js (npx đi kèm Node). README không ghi phiên bản Node cụ thể.
- Để cài plugin Codex, README ghi Codex CLI phiên bản v0.122 trở lên.
- Muốn cài từ bản clone thì cần Git.
- README không nhắc API key riêng cho repo này. Tuy nhiên agent bạn dùng (Claude Code, Codex...) vẫn cần tài khoản hoặc key của chính nó.
- Không có yêu cầu GPU hay phần cứng đặc biệt trong tư liệu.

```note
Skill chỉ là file hướng dẫn cho AI, nhưng AI vẫn có quyền chạy lệnh và sửa file trong dự án của bạn. Hãy dùng trên dự án có Git, commit sạch trước khi chạy, và đọc kỹ kế hoạch trước khi duyệt, nhất là với /build auto.
```

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

README đưa ra rất nhiều cách cài, tuỳ agent. Mình tóm cách nhanh nhất và cách cho Claude Code.

```steps
- Mở terminal | Mở terminal ngay trong thư mục dự án mà bạn muốn AI làm việc
- Cài bằng npx skills | Một lệnh cài cả 25 skill vào agent bạn đang dùng
- Hoặc cài plugin Claude Code | Dùng /plugin marketplace add rồi /plugin install ngay trong Claude Code
- Khởi động lại agent | Mở lại phiên làm việc để agent nhận skill mới
- Gõ thử một lệnh | Thử /spec để xem skill có hoạt động không
```

### Cách nhanh nhất: npx skills

README giới thiệu công cụ skills CLI mã nguồn mở, cài được vào hơn 70 agent. Mở terminal (PowerShell hoặc Terminal), đứng trong thư mục dự án, rồi chạy:

```bash
npx skills add addyosmani/agent-skills            # install all 25 skills
npx skills add addyosmani/agent-skills --list     # browse before installing
```

Lệnh đầu cài hết 25 skill. Lệnh thứ hai chỉ liệt kê để bạn xem trước, chưa cài gì. Nếu chưa chắc cần skill nào, chạy lệnh `--list` trước.

Muốn cài lẻ từng skill:

```bash
npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me              # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development   # red-green-refactor, enforced
```

Chỗ dễ vấp: README cảnh báo cài lẻ từng skill chỉ chép thư mục `skills/<tên>/`, không chép thư mục `references/` dùng chung. Skill vẫn chạy, nhưng các đường dẫn tới checklist bổ sung sẽ không có. Muốn đủ bộ, hãy cài cả repo, hoặc clone repo, hoặc chép checklist cần dùng vào thư mục `references/` bên trong skill đã cài.

### Cài vào Claude Code bằng plugin

Đây là cách README khuyến nghị. Mở Claude Code rồi gõ hai lệnh sau (gõ trong khung chat của Claude Code, không phải terminal thường):

```
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
```

Lệnh đầu đăng ký kho plugin, lệnh sau cài plugin. Sau khi cài, các lệnh slash sẽ có dạng plugin. Với lệnh trùng tên lệnh có sẵn (như `/review`), hãy dùng dạng có tiền tố: `/agent-skills:review`.

Nếu gặp lỗi SSH, README giải thích rằng marketplace clone repo qua SSH. Nếu chưa cài khoá SSH trên GitHub, dùng URL HTTPS đầy đủ:

```bash
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills
```

Nếu `/plugin install` vẫn báo `git@github.com: Permission denied (publickey)` trên Windows hoặc macOS, README khuyên cấu hình Git một lần để đổi địa chỉ SSH của GitHub sang HTTPS. Chạy lệnh này trong terminal thường:

```bash
git config --global url."https://github.com/".insteadOf git@github.com:
```

### Chạy thử từ bản clone (cho người muốn xem tận nơi)

Cách này hợp khi bạn muốn đọc file skill hoặc tự chỉnh. Thay `/path/to/agent-skills` bằng đường dẫn thật tới thư mục vừa clone:

```bash
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills
```

### Cài cho các agent khác

Mỗi agent có cách riêng. Dưới đây là các lệnh có trong README:

Antigravity CLI:

```bash
agy plugin install https://github.com/addyosmani/agent-skills.git
```

Gemini CLI:

```bash
gemini skills install https://github.com/addyosmani/agent-skills.git --path skills
```

Codex (cần Codex CLI v0.122 trở lên). Lệnh đầu đăng ký marketplace, lệnh sau cài plugin:

```bash
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills
```

Command Code:

```bash
cmd skills add addyosmani/agent-skills            # pick skills to install (project)
cmd skills add addyosmani/agent-skills --global   # install for all projects (~/.commandcode/skills/)
cmd skills add addyosmani/agent-skills -s spec-driven-development  # install a specific skill
```

Với Cursor, Windsurf, OpenCode, GitHub Copilot và Kiro, README mô tả cách chép file skill vào đúng thư mục của từng công cụ chứ không có một lệnh cài duy nhất. Hướng dẫn chi tiết nằm trong thư mục `docs/` của repo (ví dụ `docs/cursor-setup.md`, `docs/copilot-setup.md`, `docs/opencode-setup.md`, `docs/windsurf-setup.md`). Với agent không có trong danh sách, xem `docs/getting-started.md`.

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

Cách đơn giản nhất là thử gọi một lệnh hoặc một skill trong agent.

- Với Claude Code: gõ `/spec`. Nếu plugin đã cài, agent sẽ bắt đầu quy trình viết đặc tả. Với lệnh trùng tên có sẵn như `/review`, thử `/agent-skills:review`.
- Với Codex: trong khung chat, gõ `@spec-driven-development` để gọi skill theo tên.
- Với Command Code: skill đã cài sẽ xuất hiện trong menu slash của giao diện TUI, ví dụ `/spec-driven-development`.
- Với `npx skills`: chạy lại `npx skills add addyosmani/agent-skills --list` để xem danh sách. README không mô tả kết quả hiển thị chính xác của lệnh này.

Nếu agent trả lời kiểu "không biết lệnh này", hãy khởi động lại phiên làm việc rồi thử lại. Nếu vẫn không được, xem phần lỗi hay gặp bên dưới.

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

Dưới đây là bốn tình huống bám đúng những gì bộ skill làm được.

### Chủ shop muốn dựng trang đặt hàng đơn giản

Bạn có ý tưởng "một trang để khách đặt bánh theo ngày" nhưng chưa rõ cần những gì. Mở Claude Code trong thư mục dự án rồi gõ `/spec`. Skill `spec-driven-development` sẽ giúp viết đặc tả: mục tiêu, cấu trúc, cách kiểm thử, ranh giới. Nếu bạn thấy yêu cầu còn mù mờ, hãy nói "interview me" để skill `interview-me` hỏi từng câu một.

Kết quả: một bản đặc tả rõ ràng trước khi có dòng code nào. Sau đó gõ `/plan` để chia thành các task nhỏ, rồi `/build` để làm từng lát.

> Giao việc cho AI mà không có spec thì giống nhờ thợ xây nhà không đưa bản vẽ.
>
> — Ông T

### Dev mới muốn AI làm tính năng có test

Bạn đang học lập trình và hay bị AI trả về code không có test. Dùng `/test`, hoặc gọi skill `test-driven-development`, để AI đi theo chu trình đỏ - xanh - refactor: viết test thất bại trước, viết code cho test qua, rồi dọn lại. Khi có lỗi, skill `debugging-and-error-recovery` đưa AI qua quy trình tái hiện, khoanh vùng, thu gọn, sửa và chặn tái phát thay vì sửa mò.

Kết quả: mỗi thay đổi đều có test đi kèm, bạn có căn cứ để biết code còn đúng sau khi sửa.

### Trưởng nhóm cần review trước khi merge

Trước khi gộp một nhánh, chạy `/review` (hoặc `/agent-skills:review` trong Claude Code). Skill `code-review-and-quality` review theo năm trục và gắn nhãn mức độ như Nit, Optional, FYI. Bạn cũng có thể dùng persona `code-reviewer` hoặc `security-auditor` để có góc nhìn chuyên biệt hơn, nhất là khi code đụng đến đăng nhập hay dữ liệu người dùng.

Kết quả: một bản nhận xét có phân loại, giúp bạn biết chỗ nào phải sửa ngay, chỗ nào để sau.

### Dự án đã chạy lâu, muốn dùng AI mà không phá

README có mục Adoption dành cho codebase đã có sẵn: triển khai từng bước, ưu tiên kiểm chứng. Thay vì bật hết mọi thứ, bạn bắt đầu bằng `/constraints` để đặt chuẩn chất lượng (skill ghi vào CONSTRAINTS.md), rồi dùng `/code-simplify` cho những đoạn code chạy được nhưng khó đọc. Skill này giữ nguyên hành vi khi làm gọn code.

Kết quả: AI làm việc trong khuôn khổ bạn đã đặt, và bị chặn kiểu "tắt kiểm tra cho xanh".

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

### Lỗi SSH khi cài plugin Claude Code

Báo `git@github.com: Permission denied (publickey)`: do marketplace clone qua SSH mà máy bạn chưa có khoá SSH trên GitHub. Cách xử lý theo README: dùng URL HTTPS đầy đủ ở bước thêm marketplace, hoặc chạy một lần lệnh `git config --global url."https://github.com/".insteadOf git@github.com:`.

### Gõ /review nhưng chạy lệnh có sẵn của Claude Code

Vì tên trùng, bạn thấy hành vi khác với mong đợi. Dùng dạng có tiền tố: `/agent-skills:review`.

### Skill chạy nhưng báo thiếu file checklist

Thường do bạn cài lẻ từng skill bằng `npx skills add ... --skill ...`. Cách này chỉ chép thư mục của skill, không chép `references/`. Cài cả bộ, clone repo, hoặc tự chép checklist cần dùng vào thư mục `references/` trong skill. README ghi đây là hạn chế đang được theo dõi.

### Lệnh slash không hiện trong Antigravity hoặc Copilot

Với Antigravity CLI, README cho biết ở một số bản, lệnh bọc dạng TOML được báo là đã chuyển đổi nhưng không tìm thấy được. Cách xử lý là gọi thẳng skill theo tên. Với Copilot, các lệnh vòng đời như `/spec` là lệnh của Claude Code nên không xuất hiện. Hãy gọi skill theo tên, ví dụ `/spec-driven-development`.

### Lệnh codex plugin không nhận

README yêu cầu Codex CLI từ v0.122 trở lên. Nếu bản của bạn cũ hơn, cập nhật Codex trước. Mục xử lý sự cố chi tiết nằm trong `docs/codex-setup.md`.

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

Điểm mạnh:

- Miễn phí, giấy phép MIT, chỉ là file Markdown nên dễ đọc, dễ sửa.
- Dùng được trên nhiều agent. Một lệnh `npx` là cài xong.
- Bao phủ cả vòng đời phần mềm, từ ý tưởng đến deploy, với lệnh slash dễ nhớ.
- Repo còn được cập nhật trong vài tháng gần đây.

Giới hạn:

- Đây không phải ứng dụng chạy độc lập. Bạn vẫn cần một AI coding agent, và chi phí dùng agent đó vẫn do bạn chịu.
- Skill chỉ định hướng cách AI làm việc. Nó không đảm bảo code đúng, bạn vẫn phải đọc kết quả.
- Bộ khá lớn (25 skill, 9 lệnh, 4 persona). Người mới dễ choáng. Gợi ý của mình: bắt đầu với `/spec`, `/plan`, `/build`, `/test` rồi mở rộng dần.
- Một số tính năng tuỳ agent. Lệnh slash chủ yếu dành cho Claude Code, các agent khác có thể phải gọi skill theo tên.
- Checklist trong `references/` nghiêng về JavaScript/TypeScript (ví dụ phần testing-patterns), nên với ngôn ngữ khác bạn cần điều chỉnh.

Nếu bạn chỉ cần AI viết một đoạn script ngắn dùng một lần, bộ này hơi nặng, nhắc trực tiếp là đủ. Nhưng nếu bạn làm dự án nghiêm túc, nhiều người cùng đụng vào, hoặc đang để AI viết nhiều code hơn mức bạn kịp đọc, thì đây là bộ khung đáng thử.

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

### agent-skills có miễn phí không?

Repo dùng giấy phép MIT nên tải và dùng miễn phí. Tuy nhiên bạn vẫn cần một AI coding agent như Claude Code, Codex hay Cursor, và chi phí của các công cụ đó là chuyện riêng. README không nói gì về phí của repo này.

### Cài agent-skills nhanh nhất bằng cách nào?

Mở terminal trong thư mục dự án và chạy `npx skills add addyosmani/agent-skills`. Lệnh này cài cả 25 skill vào agent bạn đang dùng. Muốn xem trước thì thêm `--list`.

### Dùng được với Claude Code không, và cài thế nào?

Được, README còn khuyến nghị Claude Code. Trong Claude Code gõ `/plugin marketplace add addyosmani/agent-skills` rồi `/plugin install agent-skills@addy-agent-skills`. Nếu báo lỗi SSH, dùng URL HTTPS đầy đủ như README hướng dẫn.

### Ngoài Claude Code còn dùng được với công cụ nào?

README liệt kê Cursor, Codex, Gemini CLI, Antigravity CLI, GitHub Copilot, Kiro, OpenCode, Windsurf và Command Code. Skill là file Markdown thuần nên cũng dùng được với agent nào nhận system prompt hoặc file hướng dẫn. Mỗi công cụ có cách cài riêng, xem thư mục docs/ trong repo.

### Có cần GPU hay API key riêng không?

Tư liệu không nhắc yêu cầu GPU hay API key riêng cho repo này, vì skill chỉ là file hướng dẫn. Agent bạn dùng (Claude Code, Codex...) thì có yêu cầu tài khoản hoặc key của nó.

### Chạy trên Windows được không?

README không có mục riêng về hệ điều hành. Nó có nhắc xử lý lỗi SSH trên Windows và macOS khi cài plugin, nên cách cài này dùng được trên cả hai. Phần chi tiết hơn về Windows chưa có trong tư liệu mình đọc.

### Cài lẻ một skill có chạy đủ không?

Skill vẫn chạy, nhưng cài lẻ bằng npx chỉ chép thư mục của skill đó, không chép thư mục references/ dùng chung. Nên các đường dẫn tới checklist bổ sung sẽ không có. Muốn đủ, hãy cài cả bộ hoặc clone repo rồi chép checklist cần dùng.
