# agent-skills: bộ kỹ năng kỹ sư phần mềm cho AI viết code — hướng dẫn cài đặt và dùng

> agent-skills là bộ 25 skill dạng Markdown của Addy Osmani, dạy AI viết code làm việc theo quy trình kỹ sư chuyên nghiệp: viết spec, chia việc nhỏ, test, review rồi mới ship. Bạn cài bằng một lệnh npx hoặc qua plugin của Claude Code, Codex... Cài khá dễ, chỉ cần một công cụ AI viết code có sẵn.

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

agent-skills là một bộ "kỹ năng" (skill) dành cho các trợ lý AI viết code như Claude Code, Cursor, Codex, Copilot hay Antigravity. Mỗi skill là một quy trình làm việc viết sẵn bằng Markdown, gồm các bước, các cổng kiểm tra chất lượng và các thói quen mà kỹ sư phần mềm giàu kinh nghiệm vẫn dùng. Tác giả mô tả repo là "production-grade engineering skills for AI coding agents", tức kỹ năng kỹ thuật cấp độ sản phẩm thật cho AI viết code.

Vấn đề repo giải quyết rất quen thuộc. Nếu bạn chỉ bảo AI "làm cho mình cái này", nó thường lao vào viết code ngay, bỏ qua bước hỏi lại yêu cầu, bỏ qua test, và đôi khi sửa luôn cho qua kiểm tra. Bộ skill này ép AI đi đúng trình tự: làm rõ ý tưởng, viết đặc tả, chia nhỏ việc, code từng lát, kiểm chứng, review, rồi mới đưa lên chạy thật.

Repo hợp với lập trình viên mới muốn có "người kèm" kỷ luật cho AI, và với người làm kinh doanh hay văn phòng đang nhờ AI dựng công cụ nội bộ nhưng chưa biết quy trình chuẩn. Điểm đáng giá nhất là bạn cài một lần, rồi chỉ cần gõ các lệnh ngắn như /spec, /plan, /build. Hiện repo có khoảng 116.700 sao và 12.200 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

```repo
- repo | addyosmani/agent-skills
- kind | Skill
- desc | Bộ 25 skill và 9 lệnh slash giúp AI viết code (Claude Code, Cursor, Codex...) 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ì

Bộ này gồm ba lớp: lệnh, skill và nhân vật chuyên gia. Bạn không cần dùng hết, chỉ cần hiểu từng lớp để chọn đúng cái cần.

### 9 lệnh theo vòng đời làm phần mềm

Mỗi lệnh ứng với một giai đoạn và tự kích hoạt đúng skill:

- `/spec`: định nghĩa cái cần làm, nguyên tắc là viết đặc tả trước khi viết code.
- `/plan`: chia việc thành các nhiệm vụ nhỏ, độc lập.
- `/build`: làm từng lát một.
- `/test`: coi test là bằng chứng chứng minh nó chạy được.
- `/constraints`: đặt thước chất lượng một lần rồi áp dụng khắp nơi.
- `/review`: xem xét trước khi gộp code.
- `/webperf`: đo hiệu năng web trước khi tối ưu.
- `/code-simplify`: làm code gọn, dễ hiểu hơn.
- `/ship`: đưa lên chạy thật.

Có thêm chế độ `/build auto`: bạn duyệt kế hoạch một lần, rồi AI tự lập kế hoạch và làm hết các nhiệm vụ. Theo README, chế độ này bỏ bước con người duyệt giữa các nhiệm vụ, nhưng không bỏ kiểm chứng: mỗi nhiệm vụ vẫn làm theo kiểu test trước và commit riêng, và nó dừng lại khi gặp lỗi hoặc bước rủi ro.

### 25 skill, tự kích hoạt theo việc đang làm

Gồm 24 skill vòng đời và một skill định hướng là `using-agent-skills`. Ví dụ, khi bạn thiết kế API thì skill `api-and-interface-design` tự bật, khi làm giao diện thì `frontend-ui-engineering` bật. Một số skill đáng chú ý cho người mới:

- `interview-me`: AI hỏi bạn từng câu một để moi ra điều bạn thật sự muốn, đến khi đủ tự tin (khoảng 95%).
- `spec-driven-development`: viết tài liệu yêu cầu (PRD) trước khi có dòng code nào.
- `test-driven-development`: vòng đỏ, xanh, tái cấu trúc, được ép thực hiện.
- `code-review-and-quality`: review theo năm trục chất lượng trước khi gộp.
- `security-and-hardening`: phòng các lỗi bảo mật phổ biến (OWASP Top 10), quản lý khóa bí mật.
- `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.
- `shipping-and-launch`: danh sách kiểm tra trước khi ra mắt, triển khai từng đợt, cách quay lui.

### Nhân vật chuyên gia và danh sách kiểm tra

Repo có bốn "persona" để AI đóng vai: `code-reviewer`, `test-engineer`, `security-auditor` và `web-performance-auditor`. Ngoài ra thư mục `references/` chứa các checklist như definition-of-done, bảo mật, hiệu năng, trợ năng, quan sát hệ thống để skill lấy ra dùng khi cần.

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

Theo README, bạn cần ít nhất một công cụ AI viết code đã cài sẵn, ví dụ Claude Code, Cursor, Codex, Gemini CLI, Antigravity CLI, GitHub Copilot, Windsurf, OpenCode, Kiro hoặc Command Code. Bản thân repo chỉ là tập tệp Markdown và cấu hình, không bán dịch vụ riêng.

- Cách nhanh nhất dùng lệnh `npx`, nên máy bạn cần có Node.js (npx đi kèm Node.js). README không nêu phiên bản Node cụ thể.
- Với Codex, README ghi rõ cần Codex CLI phiên bản v0.122 trở lên.
- Với cách cài local ở Claude Code bạn cần Git để tải repo về.
- README không nói gì về yêu cầu GPU hay phần cứng riêng, và không nói repo cần API key. Tuy nhiên công cụ AI bạn dùng (Claude Code, Codex...) có thể cần tài khoản riêng của nó.

README không nêu hệ điều hành yêu cầu. Trong phần xử lý lỗi, nó có nhắc tới Windows và macOS, nên cả hai đều có người dùng.

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

```steps
- Chọn cách cài | Dùng lệnh npx cho mọi AI, hoặc cài plugin riêng nếu bạn dùng Claude Code, Codex, Gemini CLI, Antigravity
- Chạy lệnh cài | Mở terminal và dán lệnh tương ứng
- Xem trước nếu muốn | Dùng --list để duyệt các skill trước khi cài
- Cài lẻ từng skill | Chỉ lấy skill bạn cần bằng --skill
- Mở AI và thử lệnh | Gõ /spec hoặc nhắc tên skill để xem nó phản hồi
```

### Cách nhanh nhất: lệnh npx cho mọi AI

README giới thiệu công cụ skills CLI mã nguồn mở, cài được vào hơn 70 trợ lý AI khác nhau. Bạn mở terminal (trên Windows là PowerShell hoặc Terminal, trên Mac là Terminal), 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
```

Dòng đầu cài cả 25 skill. Dòng sau chỉ liệt kê để bạn xem trước, chưa cài gì. Phần sau dấu # là chú thích, bạn không cần gõ.

Nếu chỉ muốn vài 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
```

```note
Cài lẻ từng skill chỉ chép thư mục skills/<tên>. Thư mục references/ dùng chung (các checklist) không đi kèm, nên skill vẫn chạy nhưng các đường dẫn tới checklist bổ sung sẽ không dùng được. Muốn đầy đủ, hãy cài cả repo hoặc clone repo về.
```

### Claude Code: cài qua marketplace (README khuyên dùng)

Mở Claude Code, rồi gõ hai lệnh sau ngay trong khung chat của nó (không phải trong terminal thường):

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

Chỗ người mới hay vấp: marketplace tải repo qua SSH. Nếu bạn chưa thiết lập khóa SSH với GitHub, hãy dùng địa chỉ HTTPS đầy đủ:

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

Nếu vẫn báo lỗi `git@github.com: Permission denied (publickey)` trên Windows hoặc macOS, README đề xuất cấu hình Git một lần để đổi địa chỉ SSH của GitHub sang HTTPS:

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

Sau khi cài, một số lệnh trùng tên lệnh có sẵn của Claude Code, như `/review`. Khi đó dùng dạng có tên plugin: `/agent-skills:review`.

### Claude Code: cài từ bản clone trên máy

Cách này hợp khi bạn muốn tải repo về xem hoặc tự chỉnh:

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

Dòng đầu tải repo về thư mục `agent-skills`. Ở dòng hai, bạn thay `/path/to/agent-skills` bằng đường dẫn thật tới thư mục vừa tải.

### Codex

Cần Codex CLI v0.122 trở lên:

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

Lệnh đầu đăng ký marketplace, lệnh sau cài plugin. Cài xong, bạn gọi skill trong chat bằng dấu `@`, ví dụ `@spec-driven-development`. README trỏ tới docs/codex-setup.md nếu cần cài local hoặc sửa lỗi.

### Antigravity CLI

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

Hoặc từ bản clone:

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

README cảnh báo: ở một số bản Antigravity CLI, các lệnh dạng wrapper không hiện ra. Khi đó hãy gọi thẳng tên skill. Chi tiết ở docs/antigravity-setup.md.

### Gemini CLI

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

Hoặc từ bản clone:

```bash
gemini skills install ./agent-skills/skills/
```

Chi tiết ở docs/gemini-cli-setup.md.

### 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
```

### Cursor, Windsurf, OpenCode, Copilot, Kiro

Các công cụ này cài thủ công, không có một lệnh duy nhất. README chỉ hướng dẫn tóm tắt. Với Cursor, đặt skill vào `.cursor/skills/` và các chính sách ngắn vào `.cursor/rules/*.mdc`; repo không có sẵn thư mục `.cursor/`. Với OpenCode, chép skill vào `.opencode/skills/`. Với Kiro, skill nằm trong `.kiro/skills/`. Windsurf và Copilot thì thêm nội dung skill vào cấu hình rules hoặc `.github/copilot-instructions.md`. Mỗi công cụ có tệp hướng dẫn riêng trong thư mục docs/ của repo (ví dụ docs/cursor-setup.md, docs/windsurf-setup.md, docs/opencode-setup.md, docs/copilot-setup.md), bạn nên đọc đúng tệp đó.

Với các AI không có trong danh sách, README nói skill chỉ là Markdown thường nên dùng được với bất kỳ AI nào nhận system prompt hoặc tệp hướng dẫn. Xem docs/getting-started.md và docs/other-hosts.md.

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

README không đưa ra một lệnh kiểm tra duy nhất, nhưng có vài dấu hiệu bạn có thể dựa vào:

- Với `npx skills add ... --list`, bạn sẽ thấy danh sách skill của repo. Sau khi cài, mở AI viết code của bạn và hỏi nó đang có những skill nào.
- Với Claude Code, gõ `/spec` và xem lệnh có xuất hiện, có chạy không. Nếu bị trùng tên lệnh có sẵn thì thử dạng `/agent-skills:review`.
- Với Codex, gõ `@spec-driven-development` trong chat. Với Command Code, skill đã cài sẽ hiện trong menu slash của giao diện, ví dụ `/spec-driven-development`.
- Với Copilot, các lệnh vòng đời như `/spec` không xuất hiện; bạn gọi skill theo tên, ví dụ `/spec-driven-development`.

Nếu AI không phản hồi theo quy trình, hãy thử nhắc tên skill trực tiếp, vì skill cũng có thể được gọi bằng tên.

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

Bộ skill này không phải phần mềm có giao diện. Nó thay đổi cách AI làm việc với bạn. Dưới đây là vài tình huống bám sát khả năng có trong README.

### Chủ shop muốn dựng công cụ quản lý đơn hàng nhưng chưa rõ mình cần gì

Bạn có ý tưởng mơ hồ: "làm cái trang theo dõi đơn hàng cho shop". Thay vì để AI đoán, hãy dùng skill `interview-me`. Bạn gõ trong AI viết code:

```
interview me về công cụ theo dõi đơn hàng cho shop của mình
```

AI sẽ hỏi từng câu một về người dùng, dữ liệu, các trường hợp đặc biệt, cho đến khi hiểu đủ. Sau đó chạy `/spec` để nó viết thành tài liệu yêu cầu. Kết quả là một bản đặc tả rõ ràng bạn đọc được bằng tiếng thường, thay vì một đống code bạn không kiểm chứng nổi.

> Cài một lần, AI đỡ làm bừa: hỏi trước, chia nhỏ, test rồi mới ship.
>
> — Ông T

### Lập trình viên mới cần làm một tính năng nhỏ mà không biết bắt đầu từ đâu

Bạn đã có spec. Chạy `/plan` để AI chia thành các nhiệm vụ nhỏ có tiêu chí hoàn thành và thứ tự phụ thuộc, rồi `/build` để làm từng lát một: viết, test, kiểm chứng, commit. Cách này giúp bạn học theo, vì mỗi bước đều nhỏ và có lý do. Nếu tin kế hoạch, bạn thử `/build auto` để duyệt một lần rồi để AI chạy hết, nhưng nhớ rằng nó dừng khi gặp lỗi hoặc bước rủi ro, nên bạn vẫn cần theo dõi.

### Nhân viên văn phòng nhờ AI đọc lại code trước khi gửi cho đội kỹ thuật

Bạn nhờ AI viết một script tự động hóa báo cáo và muốn chắc chắn nó an toàn. Chạy `/review` (hoặc `/agent-skills:review` nếu bị trùng tên) để AI review theo năm trục chất lượng, có gắn nhãn mức độ như Nit, Optional, FYI. Nếu script đụng đến dữ liệu khách hàng hay mật khẩu, nhờ persona `security-auditor` rà soát lỗ hổng. Bạn nhận được danh sách vấn đề đã phân loại, dễ chuyển cho đội kỹ thuật xử lý.

### Dev trong nhóm nhỏ muốn đặt chuẩn chất lượng chung

Nhóm chưa có quy chuẩn viết ra giấy, AI lại viết code nhiều hơn người đọc kịp. Chạy `/constraints`: skill `constraint-driven-development` phỏng vấn bạn về thước chất lượng, đề xuất ngưỡng mặc định hợp lý, ghi vào tệp CONSTRAINTS.md và chọn nơi đặt từng kiểm tra theo chi phí. README cũng nói skill này bắt được trường hợp AI tắt kiểm tra hoặc bỏ test cho xanh. Kết quả là một tệp chuẩn chất lượng mà cả người lẫn AI cùng theo.

Nếu bạn đã có dự án cũ, README có phần Adoption Guide (hướng dẫn áp dụng) nói về việc triển khai từng bước, ưu tiên kiểm chứng, thay vì dùng đủ vòng đời ngay từ đầu.

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

### Lỗi Permission denied (publickey) khi cài plugin Claude Code

Đây là lỗi chính chính README nhắc. Nguyên nhân là marketplace tải repo qua SSH mà máy bạn chưa có khóa SSH GitHub. Cách xử lý an toàn: dùng địa chỉ HTTPS đầy đủ ở bước thêm marketplace, hoặc chạy lệnh `git config --global url...insteadOf` ở phần cài đặt bên trên để Git tự đổi SSH sang HTTPS. Lệnh này sửa cấu hình Git toàn máy, nên bạn chỉ chạy nếu chắc chắn muốn.

### Gõ /review nhưng chạy nhầm lệnh có sẵn

Claude Code đã có lệnh `/review` riêng. Hãy dùng dạng có tên plugin: `/agent-skills:review`. Các lệnh khác nếu trùng tên cũng xử lý tương tự.

### Cài lẻ một skill nhưng thiếu checklist đi kèm

Khi cài từng skill bằng npx, chỉ thư mục skills/<tên> được chép, thư mục references/ không có. Skill vẫn chạy nhưng không dẫn tới được các checklist dùng chung. Cách khắc phục theo README: cài theo kiểu tích hợp cả repo, clone repo về, hoặc chép checklist cần dùng vào một thư mục references/ bên trong skill đã cài.

### Lệnh /spec, /plan không hiện trong Copilot hay Antigravity

Các lệnh vòng đời là lệnh của Claude Code. Trong Copilot chúng không xuất hiện, bạn gọi skill theo tên như `/spec-driven-development`. Ở một số bản Antigravity CLI, lệnh wrapper không tìm thấy được, nên gọi thẳng skill có namespace.

### Codex không nhận lệnh plugin

README yêu cầu Codex CLI từ v0.122 trở lên. Nếu lệnh `codex plugin` báo không có, hãy kiểm tra phiên bản và cập nhật Codex, rồi xem docs/codex-setup.md để cài local và sửa lỗi.

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

Điểm mạnh lớn nhất là tính kỷ luật. Bộ skill buộc AI hỏi kỹ, chia nhỏ, test và review, những việc bạn rất dễ bỏ qua khi vội. Nó dùng được trên rất nhiều công cụ, giấy phép MIT, và vì chỉ là Markdown nên bạn đọc, sửa, bớt hay thêm skill được. Số sao rất lớn cho thấy cộng đồng quan tâm, nhưng đó không phải bằng chứng nó hợp với dự án của bạn.

Giới hạn cũng rõ. Đây không phải phần mềm tự chạy; hiệu quả phụ thuộc vào AI bạn dùng có làm theo skill hay không. Cách cài khác nhau theo từng công cụ, và với Cursor, Windsurf, OpenCode, Copilot bạn phải tự chép tệp. Phần ví dụ test trong checklist nghiêng về JavaScript và TypeScript. Quy trình đầy đủ (spec, plan, test, review) sẽ chậm hơn so với việc nhờ AI sửa nhanh một dòng, nên với việc nhỏ xíu bạn không cần dùng hết.

Nếu bạn chỉ muốn thử, hãy bắt đầu bằng `--list` để xem rồi cài lẻ vài skill như `interview-me` và `test-driven-development`. Nếu bạn không dùng AI viết code, hoặc chỉ cần một đoạn lệnh mẫu một lần, bộ này chưa cần thiết.

## 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 bạn dùng và chỉnh sửa tự do. README không nhắc tới phí của chính repo. Tuy nhiên công cụ AI bạn dùng cùng với nó (Claude Code, Codex...) có thể có chi phí riêng, và README chưa nói về điều này.

### Cài agent-skills có khó không?

Cách dễ nhất là một lệnh: npx skills add addyosmani/agent-skills. Với Claude Code, bạn gõ hai lệnh plugin trong chat. Một số công cụ như Cursor, Windsurf hay OpenCode cần chép tệp thủ công và đọc hướng dẫn riêng trong thư mục docs/.

### Có cần GPU hoặc cấu hình máy mạnh không?

README không nêu yêu cầu GPU hay phần cứng riêng. Repo chủ yếu là các tệp Markdown và cấu hình, nên việc tính toán do công cụ AI bạn dùng đảm nhiệm.

### Dùng được trên Windows không?

README không ghi rõ danh sách hệ điều hành hỗ trợ. Có nhắc cách xử lý lỗi cài plugin trên Windows và macOS, nên cả hai đều có người dùng. Bạn nên chạy lệnh trong PowerShell hoặc Terminal có sẵn Node.js và Git.

### agent-skills dùng được với những AI nào?

README liệt kê Claude Code, Cursor, Codex, Copilot, Cline, Gemini CLI, Antigravity CLI, Windsurf, OpenCode, Kiro và Command Code. Công cụ skills CLI cài được vào hơn 70 trợ lý. Với AI khác, vì skill là Markdown thường nên bạn có thể đưa vào system prompt hoặc tệp hướng dẫn.

### Skill khác gì lệnh slash?

Lệnh slash (như /spec, /plan, /build) là điểm vào theo từng giai đoạn làm phần mềm, và mỗi lệnh tự kích hoạt đúng skill. Skill là quy trình chi tiết bên dưới, cũng tự bật theo việc bạn đang làm hoặc gọi trực tiếp theo tên.

### Dữ liệu và code của mình có an toàn không?

README không có phần riêng về quyền riêng tư dữ liệu. Skill chỉ là chỉ dẫn cho AI, còn code và dữ liệu của bạn được xử lý bởi công cụ AI bạn chọn, nên bạn cần xem chính sách của công cụ đó. Repo có skill về bảo mật và quản lý khóa bí mật để AI viết code an toàn hơn.
