Agent Skills là gì? Viết SKILL.md một lần, dùng cho mọi agent
Agent skills giúp bạn dặn AI coding agent một lần dùng mãi. Skill đặt ở đâu để Copilot, Claude Code, Cursor, Codex cùng đọc và cách viết SKILL.md đầu tiên.
Trong bài này
- 15 phút đọc
- 12 phần
- 5 mẫu sao chép được
- 2 bảng tra cứu
Cách bài viết này được thực hiện: bài dựa trên hướng dẫn “Build once, run on any agent” của GitHub Blog (12/11/2026), tài liệu chính thức của GitHub Copilot và Cursor về agent skills, kiểm tra ngày 13/11/2026. Skill mẫu trong bài do mmo.vn viết để minh hoạ, bạn nên thử trên một repo thử nghiệm trước khi dùng cho dự án thật.
Bạn có bao giờ phải dặn đi dặn lại AI coding agent cùng một việc? “Nhớ chạy test trước khi commit”, “đừng commit file .env”, “viết lời nhắn commit bằng tiếng Việt”. Hôm nay dặn Claude Code, mai mở Cursor lại dặn từ đầu, sang GitHub Copilot lại gõ thêm lần nữa. Agent skills sinh ra để chấm dứt việc đó.
Ngày 12/11/2026, GitHub đăng bài hướng dẫn thực hành về agent skills với thông điệp “build once, run on any agent”: viết kỹ năng một lần, dùng được trên nhiều agent khác nhau. Bài này giải thích skill là gì, đặt ở đâu để Copilot, Claude Code, Cursor, Codex cùng đọc được, và hướng dẫn bạn viết skill đầu tiên chỉ với một file Markdown.
Câu trả lời ngắn: Agent skill là một thư mục chứa file SKILL.md, mô tả khi nào và làm một việc lặp lại như thế nào. Agent chỉ đọc phần tên và mô tả lúc đầu, khi yêu cầu của bạn khớp mới nạp toàn bộ hướng dẫn. Đặt skill trong .agents/skills/ hoặc .claude/skills/ của repo là nhiều agent dùng chung được.
Tóm tắt nhanh
- Skill là hướng dẫn đóng gói thành thư mục, trung tâm là file SKILL.md có hai trường bắt buộc: name và description.
- Skill không cấp quyền: công cụ, mật khẩu, quyền truy cập vẫn do agent đang chạy quyết định.
- Copilot đọc skill trong
.github/skills,.claude/skills,.agents/skills; Cursor đọc cả bốn thư mục kiểu này.- GitHub khuyên: mỗi skill một việc, cấu hình để ngoài skill, có bước kiểm tra và người duyệt.
- GitHub không kiểm duyệt skill của người khác, hãy xem trước rồi mới cài.
Nội dung chính:
- Agent skills là gì
- Vì sao một skill chạy được trên nhiều agent
- Đặt skill ở thư mục nào
- Cấu trúc file SKILL.md
- Hướng dẫn viết skill đầu tiên
- Bài học từ hai demo của GitHub
- Bảy nguyên tắc thiết kế skill
- Khi nào không nên dùng skill
- Dùng skill an toàn
- Hiểu lầm phổ biến
- Câu hỏi thường gặp
- Kết luận
Agent skills là gì
Theo GitHub, agent skill là một thư mục có quản lý phiên bản, xoay quanh một file tên SKILL.md. File này nói cho agent biết khi nào cần làm một việc lặp lại và làm như thế nào. Thay vì mỗi lần mở phiên mới bạn lại gõ một đoạn dặn dò dài, bạn viết đoạn dặn dò đó thành skill, để trong repo, và agent tự lấy ra khi cần.
Có thể hình dung skill giống một tờ quy trình dán trên tường xưởng. Thợ mới vào không cần ai kèm, nhìn tờ quy trình là biết bước nào làm trước. Agent cũng vậy: nó không nhớ gì giữa các phiên, nhưng đọc được tờ quy trình bạn để sẵn.
Một điểm GitHub nhấn mạnh: skill không cấp quyền. Skill có thể mô tả cách truy vấn cơ sở dữ liệu, nhưng không tự cho agent quyền vào cơ sở dữ liệu đó. Công cụ, thông tin đăng nhập, ngữ cảnh dự án và quyền hạn vẫn nằm ở phía chương trình đang chạy skill, tức Copilot, Claude Code, Cursor hay Codex trên máy bạn.
Vì sao một skill chạy được trên nhiều agent
SKILL.md đi theo một đặc tả mở tại agentskills.io. Tài liệu của GitHub dẫn tới đặc tả này và lệnh gh skill publish dùng nó để kiểm tra skill trước khi xuất bản. Vì cùng một định dạng, file bạn viết cho Copilot cũng đọc được bởi Cursor, Claude Code hay Codex, miễn là đặt đúng thư mục mà công cụ đó tìm.
Điều khiến skill không làm “phình” ngữ cảnh là cơ chế nạp dần (progressive disclosure). Lúc bắt đầu phiên, agent chỉ đọc tên và mô tả của mọi skill. Khi yêu cầu của bạn khớp với một mô tả, nó mới đọc toàn bộ SKILL.md. Script hay tài liệu đi kèm trong thư mục skill chỉ được mở khi hướng dẫn yêu cầu. Theo tổng hợp của trang flaviocopes.com, Codex còn giới hạn danh sách mô tả skill ở 2% cửa sổ ngữ cảnh (hoặc 8.000 ký tự khi không biết kích thước cửa sổ).
Hệ quả thực tế: phần description quyết định skill có được dùng hay không. Tài liệu Copilot ghi rõ Copilot chọn skill dựa trên prompt của bạn và mô tả của skill. Mô tả mơ hồ thì agent không biết lúc nào nên gọi.
Đặt skill ở thư mục nào
Mỗi skill là một thư mục con, tên viết thường nối bằng gạch ngang, bên trong có SKILL.md. Skill có hai cấp: cấp dự án (nằm trong repo, cả nhóm dùng chung) và cấp cá nhân (nằm trong thư mục người dùng, dùng cho mọi dự án của bạn). Bảng dưới tổng hợp từ tài liệu của từng hãng:
| Công cụ | Trong repo | Cá nhân |
|---|---|---|
| GitHub Copilot | .github/skills, .claude/skills, .agents/skills | ~/.copilot/skills, ~/.agents/skills |
| Claude Code | .claude/skills | ~/.claude/skills |
| Cursor | .agents/skills, .cursor/skills, cũng đọc .claude/skills và .codex/skills | ~/.agents/skills, ~/.cursor/skills |
| Codex | .agents/skills | ~/.agents/skills |
Nhìn bảng sẽ thấy không có thư mục nào được cả bốn công cụ cùng đọc. .claude/skills phủ Claude Code, Copilot và Cursor nhưng thiếu Codex; .agents/skills phủ Copilot, Cursor và Codex nhưng thiếu Claude Code. Cách đơn giản nhất cho người mới: để skill gốc ở .agents/skills, rồi tạo một liên kết tượng trưng (symlink) tên .claude/skills trỏ về đó.
Cấu trúc file SKILL.md
SKILL.md gồm hai phần: phần đầu YAML (frontmatter) nằm giữa hai dòng ---, và phần thân viết bằng Markdown. Theo tài liệu Copilot:
- name (bắt buộc): tên định danh, chữ thường, nối bằng gạch ngang, thường trùng tên thư mục. Cursor yêu cầu trùng hẳn tên thư mục cha.
- description (bắt buộc): skill làm gì và khi nào nên dùng.
- license (tuỳ chọn): giấy phép áp dụng cho skill.
- allowed-tools (tuỳ chọn): công cụ Copilot được dùng mà không hỏi lại. Tài liệu cảnh báo cho phép sẵn
shellhoặcbashcó thể để skill lạ chạy lệnh tuỳ ý.
Cursor hỗ trợ thêm vài trường riêng như paths (chỉ gợi ý skill khi làm việc với file khớp mẫu) và disable-model-invocation: true (agent không tự gọi, bạn phải gõ /tên-skill). Các trường riêng này công cụ khác có thể bỏ qua, nên skill dùng chung chỉ cần name và description là đủ.
Hướng dẫn viết skill đầu tiên
GitHub khuyên bắt đầu từ việc bạn phải giải thích đi giải thích lại. Với người mới vibe code, việc hay quên nhất là kiểm tra trước khi commit. Dưới đây là skill mẫu làm đúng việc đó.
Bước 1: Tạo thư mục skill
Mở terminal ở thư mục gốc của dự án và chạy:
mkdir -p .agents/skills/kiem-tra-truoc-commitLệnh mkdir -p tạo cả chuỗi thư mục nếu chưa có. Tên thư mục cuối cùng là tên skill, viết thường, không dấu, nối bằng gạch ngang. Trên Windows, lệnh này chạy được trong Git Bash; trong PowerShell bạn dùng New-Item -ItemType Directory -Force .agents\skills\kiem-tra-truoc-commit.
Bước 2: Viết file SKILL.md
Tạo file .agents/skills/kiem-tra-truoc-commit/SKILL.md với nội dung:
---
name: kiem-tra-truoc-commit
description: Kiểm tra dự án web trước khi commit. Dùng khi người dùng nhờ commit, mở pull request hoặc hỏi code đã sẵn sàng đẩy lên chưa.
---
# Kiểm tra trước khi commit
## Khi nào dùng
- Trước mỗi lần commit hoặc mở pull request.
## Các bước
1. Chạy `npm run lint` rồi `npm test`. Nếu lỗi, dừng lại và báo lỗi. Không sửa test cho qua.
2. Chạy `git diff --cached --name-only` để xem các file sắp commit.
3. Nếu có `.env`, file `*.pem` hoặc `.claude/settings.local.json`, cảnh báo và không commit.
4. Chạy `git diff --cached | grep -inE "(api[_-]?key|secret|password|token)\s*[:=]"`.
Có kết quả thì dừng và hỏi lại người dùng.
5. Viết lời nhắn commit tiếng Việt theo mẫu `loai: mo ta ngan`, ví dụ `sua: loi dang nhap`.
## Kết quả trả về
- Danh sách lệnh đã chạy và kết quả đạt hoặc lỗi.
- Các file bị chặn (nếu có) và lý do.Giải thích nhanh từng phần:
- description liệt kê đúng những câu bạn hay nói với agent (“nhờ commit”, “mở pull request”), để agent nhận ra lúc cần dùng.
- Bước 1 có câu “không sửa test cho qua” vì agent đôi khi sửa luôn bài test để lệnh chạy xanh.
- Bước 3 chặn các file hay chứa bí mật. File
.claude/settings.local.jsontừng làm lộ hàng nghìn mật khẩu trên GitHub, xem bài lộ API key qua AI coding agent. - Bước 4 dùng
grep -inE:-ikhông phân biệt hoa thường,-nin số dòng,-Ebật biểu thức chính quy mở rộng để bắt các dòng kiểuAPI_KEY=...haypassword: .... Đây là lưới thô, không thay được công cụ quét bí mật chuyên dụng. - Phần Kết quả trả về buộc agent báo cáo có bằng chứng, đúng tinh thần “phải có bằng chứng” của GitHub.
Bước 3: Cho Claude Code cùng đọc
Claude Code đọc .claude/skills, nên tạo một liên kết trỏ về thư mục vừa làm. Trên macOS hoặc Linux:
mkdir -p .claude
ln -s ../.agents/skills .claude/skillsĐường dẫn ../.agents/skills tính từ vị trí của liên kết (bên trong .claude), nên phải lùi ra một cấp. Trên Windows, mở Command Prompt ở thư mục dự án (cần bật Developer Mode hoặc chạy quyền quản trị):
mkdir .claude
mklink /D .claude\skills ..\.agents\skillsNếu ngại symlink, bạn chép nguyên thư mục skill sang .claude/skills cũng được, chỉ cần nhớ sửa cả hai nơi khi cập nhật.
Bước 4: Thử và chỉnh
Mở agent, gõ “commit giúp mình các thay đổi này” và xem nó có tự chạy lint, test, kiểm tra file nhạy cảm không. Trong Cursor, bạn có thể gọi thẳng bằng cách gõ / rồi tìm tên skill. Nếu agent bỏ qua skill, hãy sửa description cho sát cách bạn hay nói. GitHub khuyên thử skill với một agent khác nữa để chắc hướng dẫn không phụ thuộc thói quen của riêng một công cụ.
Bài học từ hai demo của GitHub
Bài của GitHub đi kèm hai ví dụ có mã nguồn công khai trong repo githubevents/build-once-run-on-any-agent.
Proof Agent: tự kiểm tra không phải là kiểm tra
Proof Agent là skill dùng một “người kiểm tra” độc lập để soát thay đổi do AI viết so với yêu cầu ban đầu. Nguyên tắc cốt lõi được GitHub phát biểu ngắn gọn: self-verification is not verification, tức agent tự chấm bài mình thì chưa phải kiểm tra. Một workflow GitHub Actions đưa cho verifier yêu cầu gốc và phần code thay đổi, nhưng không đưa phần tự đánh giá của agent viết code. Verifier trả về PASS, FAIL hoặc PARTIAL và bắt buộc dẫn bằng chứng. Trong bản demo, tuỳ chọn block-on-fail đặt là false, nghĩa là kết quả chỉ để tham khảo, chưa chặn việc merge.
Bài học cho người vibe code: đừng hỏi lại chính agent vừa viết code “code ổn chưa?”. Hãy mở phiên khác, hoặc dùng agent khác, đưa yêu cầu gốc và diff, yêu cầu chỉ ra bằng chứng.
Data Forge: nhiều skill phối hợp
Ví dụ thứ hai là một quy trình dữ liệu cho bộ phận hỗ trợ khách hàng, gồm bốn skill: forge-init dò bảng nguồn và quy ước đặt tên rồi ghi ra file manifest; forge-builder điều phối từ issue đến pull request; forge-dbx là đường truy cập dữ liệu duy nhất (qua Databricks hoặc DuckDB); forge-lint cung cấp chuẩn của nhóm trước khi sinh code. Quy trình có bảy pha, mỗi pha có một điểm người duyệt.
Thông tin riêng của dự án nằm trong manifest, không nằm trong skill:
project:
name: "support-desk"
store_name: "support_metric_store"
platform:
engine: "duckdb"
pipeline_framework: "spark_python"
duckdb_dir: "warehouse"Nhờ vậy cùng bộ skill dùng được cho dự án khác, chỉ cần đổi file manifest. Để chạy trên nhiều agent, GitHub viết skill gốc trong skills/*/SKILL.md rồi dùng một script đóng gói thành định dạng plugin của Claude Code (.claude-plugin/plugin.json), Cursor (.cursor-plugin/plugin.json) và Copilot (.github/agents/*.agent.md). Script có chế độ kiểm tra cho CI: node scripts/package.mjs --check.
Bảy nguyên tắc thiết kế skill
GitHub đúc kết bảy bước khi tự làm skill. Mình diễn giải lại cho người mới:
- Chọn một việc. Xác định đầu vào, đầu ra và lúc nào áp dụng. Skill “làm mọi thứ” sẽ không bao giờ được gọi đúng lúc.
- Để cấu hình ra ngoài skill. Tên dự án, lược đồ dữ liệu, quy ước đặt tên nằm trong một file manifest để skill đọc.
- Tách điều agent tự dò ra với chuẩn của nhóm. Chỗ nào cần phán đoán nghiệp vụ thì để người xác nhận.
- Dùng chung một đường thực thi. Các skill liên quan dùng cùng một cách truy cập nền tảng, không mỗi skill tự viết code kết nối.
- Thêm bước kiểm tra và duyệt. Người duyệt cho chỗ cần phán đoán, test và CI để bắt lỗi, quy tắc repo để chặn merge.
- Đóng gói cho từng công cụ rồi kiểm. Sau khi cài, xác nhận công cụ nhận ra skill, nạp tài liệu tham chiếu, dùng đúng công cụ và trả về bằng chứng như mong đợi.
- Lặp lại. Thử với agent khác, ghi rõ phạm vi và kỳ vọng của người duyệt, rồi chỉnh dần.
Khi nào không nên dùng skill
Skill hợp với việc có giới hạn rõ và lặp lại. Tài liệu Copilot gợi ý: chỉ dẫn đơn giản áp dụng cho gần như mọi việc (ví dụ “trả lời bằng tiếng Việt”, “dùng TypeScript”) thì để ở custom instructions; hướng dẫn chi tiết chỉ cần khi làm một việc cụ thể thì để thành skill.
GitHub cũng nói rõ lúc nên làm hẳn một ứng dụng thay vì skill: khi quy trình cần giao diện ổn định, trạng thái dùng chung, nhật ký kiểm toán, điều khiển việc chạy dài, hoặc quyền hạn phải được thực thi bên ngoài mô hình. Nói cách khác, skill là lời dặn, không phải hàng rào. Thứ gì bắt buộc phải chặn thì phải chặn bằng hệ thống, không chỉ bằng chữ.
| Nhu cầu | Nên dùng | Ví dụ |
|---|---|---|
| Quy tắc áp dụng cho mọi việc | Custom instructions | Luôn trả lời bằng tiếng Việt |
| Quy trình lặp lại, có giới hạn | Agent skill | Kiểm tra trước khi commit |
| Cần giao diện, trạng thái chung, quyền bắt buộc | Ứng dụng | Hệ thống duyệt chi tiêu của công ty |
Dùng skill an toàn
Skill của người khác là văn bản sẽ được chèn thẳng vào ngữ cảnh agent, và có thể kèm script. Tài liệu GitHub nói rõ GitHub không kiểm duyệt skill. Vài thói quen nên có:
- Xem trước khi cài. Công cụ
gh skillcủa GitHub CLI (đang public preview, cần GitHub CLI 2.90.0 trở lên) có lệnh tìm, xem trước, cài, cập nhật và xuất bản skill. Hãy dùng chức năng xem trước và đọc hết SKILL.md cùng mọi script trước khi cài. - Cẩn thận với allowed-tools. Đừng cho sẵn quyền
shellhoặcbashvới skill bạn không tự viết. - Không để bí mật trong skill. Skill nằm trong repo, ai đọc được repo là đọc được skill. Mật khẩu và khoá API để ở biến môi trường hoặc trình quản lý bí mật.
- Cài skill từ nguồn chính chủ. Ví dụ, README của công cụ gh-actions-lock gợi ý
gh skill install github/gh-actions-lockđể dạy agent dùng công cụ này.
Hiểu lầm phổ biến
“Có skill thì agent được làm nhiều việc hơn.” Không. Skill chỉ là hướng dẫn. Agent làm được gì vẫn do quyền và công cụ bạn cấp cho chương trình đang chạy.
“Viết càng nhiều skill càng tốt.” Mỗi skill tốn một ít ngữ cảnh cho tên và mô tả. Skill trùng nhau hoặc mô tả mơ hồ khiến agent chọn sai. Bắt đầu với 2–3 skill cho việc bạn lặp lại nhiều nhất.
“Skill viết cho Claude Code thì chỉ Claude Code dùng.” Copilot và Cursor đều đọc .claude/skills. Chỉ cần tránh tính năng riêng của một công cụ.
“Agent tự kiểm tra là đủ.” Chính GitHub khuyên dùng verifier độc lập, không đưa phần tự đánh giá của agent viết code.
Câu hỏi thường gặp
Agent skills có mất phí không?
Skill chỉ là thư mục và file Markdown, không mất phí. Bạn trả phí cho công cụ chạy skill (gói Copilot, Claude, Cursor, ChatGPT) như bình thường.
Skill khác gì file AGENTS.md hay CLAUDE.md?
Các file như AGENTS.md hay CLAUDE.md thường được nạp cho mọi việc trong dự án, giống custom instructions. Skill chỉ được nạp đầy đủ khi yêu cầu khớp mô tả, nên hợp với hướng dẫn dài cho một việc cụ thể.
Viết skill bằng tiếng Việt được không?
Được. Agent hiểu tiếng Việt tốt. Riêng trường name nên viết không dấu, chữ thường, nối gạch ngang. Phần description nên chứa đúng những từ bạn hay dùng khi giao việc để agent nhận ra.
Skill dùng được trên GitHub Copilot ở đâu?
Theo tài liệu GitHub, skill hoạt động với Copilot cloud agent, Copilot code review, GitHub Copilot CLI, ứng dụng GitHub Copilot và agent mode trong Visual Studio Code.
Làm sao biết agent đã dùng skill?
Hãy yêu cầu trong phần “Kết quả trả về” của skill một dòng ghi rõ đã dùng skill nào và đã chạy lệnh gì. Nếu báo cáo không có dòng đó, khả năng cao agent đã bỏ qua skill, hãy sửa description.
Kết luận
Agent skills biến những lời dặn lặp đi lặp lại thành tài sản của dự án: viết một lần, để trong repo, Copilot, Claude Code, Cursor hay Codex đều dùng được. Với người mới vibe code, hãy bắt đầu bằng một skill nhỏ như kiểm tra trước khi commit, đặt ở .agents/skills kèm liên kết sang .claude/skills, rồi chỉnh description cho tới khi agent gọi đúng lúc. Nhớ ba điều GitHub nhắc: mỗi skill một việc, cấu hình để ngoài, và kiểm tra bằng một bên độc lập.
Nếu bạn muốn đi tiếp, bài biến quy trình thành bộ prompt và Skills dùng chung có cách quản lý phiên bản cho cả nhóm, còn bài Modern Web Guidance 1.0 giới thiệu một bộ hướng dẫn có sẵn giúp agent viết web hiện đại. Bạn đang dặn agent việc gì nhiều nhất? Để lại bình luận, mmo.vn sẽ thử viết skill mẫu cho tình huống phổ biến nhất.
Nguồn tham khảo: GitHub Blog, “Build once, run on any agent: A practical guide to agent skills” (12/11/2026); GitHub Docs, “Add skills to GitHub Copilot”; Cursor Docs, “Agent Skills”; flaviocopes.com, “What are agent skills?”; README của github/gh-actions-lock.
