agent-skills: bộ quy trình kỹ sư cho AI viết code — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về addyosmani/agent-skills — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: agent-skills: bộ kỹ năng kỹ thuật chuẩn production cho AI viết code — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
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.
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.
addyosmani/agent-skills
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.
I.agent-skills làm được gì
Nói gọn, repo cho bạn bốn thứ: lệnh slash, skill, persona và checklist.
A.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ì.
B.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.
C.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.
D.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.
II.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.
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.
III.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.
- Mở terminalMở terminal ngay trong thư mục dự án mà bạn muốn AI làm việc
- Cài bằng npx skillsMột lệnh cài cả 25 skill vào agent bạn đang dùng
- Hoặc cài plugin Claude CodeDùng /plugin marketplace add rồi /plugin install ngay trong Claude Code
- Khởi động lại agentMở lại phiên làm việc để agent nhận skill mới
- Gõ thử một lệnhThử /spec để xem skill có hoạt động không
A.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:
npx skills add addyosmani/agent-skills # install all 25 skills
npx skills add addyosmani/agent-skills --list # browse before installingLệ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:
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, enforcedChỗ 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.
B.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-skillsLệ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 đủ:
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skillsNế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:
git config --global url."https://github.com/".insteadOf git@github.com:C.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:
git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skillsD.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:
agy plugin install https://github.com/addyosmani/agent-skills.gitGemini CLI:
gemini skills install https://github.com/addyosmani/agent-skills.git --path skillsCodex (cần Codex CLI v0.122 trở lên). Lệnh đầu đăng ký marketplace, lệnh sau cài plugin:
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skillsCommand Code:
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 skillVớ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.
IV.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ạinpx 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.
V.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.
A.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
B.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.
C.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.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".
VI.Lỗi hay gặp và cách xử lý
A.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:.
B.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.
C.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.
D.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.
E.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.
VII.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
npxlà 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,/testrồ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.


