Review Skill: Skill Dùng Để Rà Soát Skill
Tôi viết khá nhiều skill, và rất lâu cách kiểm tra duy nhất của tôi là "chạy thấy ổn". Rồi tôi đọc Day 3 của khóa "5-Day AI Agents" do Google biên soạn, phần nói về Agent Skills. Tài liệu này dẫn kết quả SkillsBench: trong 84 tác vụ agent thực tế, 19% làm tệ hơn khi có skill so với không có. Một skill viết ẩu không phải là vô hại, nó kéo agent xuống.
Day 3 còn chứa rất nhiều hướng dẫn cụ thể: viết description thế nào, skill được phép dài đến đâu, những mùi cần tránh, cách đánh giá và đưa vào sử dụng. Tôi không muốn đọc lại từ đầu mỗi lần viết skill mới, nên đã tổng hợp thành review-skill (MIT, v1.5.0), nằm trong repo the-skills của tôi. Trỏ nó vào một thư mục skill bất kỳ, agent sẽ rà soát skill đó theo các quy tắc của whitepaper.
1. Skill Này Kiểm Tra Những Gì
Một lần rà soát có hai lớp. Linter Python lo phần script quyết định được. Agent đánh giá phần còn lại theo năm tiêu chí, mỗi tiêu chí lấy từ một phần của Day 3.
| Tiêu chí | Người rà soát tìm gì | Nguồn từ Day 3 |
|---|---|---|
| Metadata & định tuyến | name dạng kebab-case, version theo SemVer, description nói rõ làm gì, khi nào dùng, khi nào không dùng, tối đa 1024 ký tự |
"Description là thuật toán định tuyến" |
| Nạp dần ngữ cảnh | SKILL.md dưới 5.000 từ, việc xác định được đẩy sang scripts/, kiến thức sâu vào references/, template vào assets/ |
Cơ chế nạp ba cấp |
| Độ rõ ràng của chỉ dẫn | Bước làm dạng mệnh lệnh, mỗi luật chặt có lý do đi kèm, định dạng đầu ra cụ thể, có xử lý ca biên | "Đưa ra lý do, không chỉ luật" |
| Vệ sinh script & công cụ | Script có hướng dẫn dùng, không lộ secret, không đường dẫn tuyệt đối, không gắn cứng tên công cụ của một vendor | Danh sách Don't |
| Khả năng kiểm thử | Phủ đủ trigger, execution, regression và token budget | Mục 4, bốn kiểu lỗi |
Có thêm một lượt tùy chọn: đọc skill như chính model sẽ đọc. Lượt này bắt các đoạn hiểu được hai nghĩa, thuật ngữ không được định nghĩa ở đâu, và một quy tắc bị lặp ở hai chỗ.
Linter validate_skill.py lo phần cơ học: frontmatter thiếu hoặc sai định dạng, description mở đầu bằng "a helpful skill for", body vượt 5.000 từ, ALWAYS hoặc NEVER không có lời giải thích gần đó, secret viết cứng, đường dẫn tuyệt đối, thư mục rỗng, script không có chú thích cách dùng và dependency không ghim phiên bản. Linter thoát với mã 0 khi sạch, mã 1 khi có lỗi, và cờ --json cho đầu ra máy đọc được.
2. Quy Trình Rà Soát
Tôi cố định thứ tự: kiểm tra xác định trước, đánh giá chủ quan sau, mọi phát hiện đều phải có bằng chứng.
- Linter trước. Kết quả được đưa vào báo cáo ở mục Mechanical Checks. Skill còn lỗi linter thì chưa xong.
- Xác định phạm vi. Người rà soát liệt kê những gì có:
SKILL.md, frontmatter, cùngreferences/,scripts/,assets/hoặcexamples/nếu có. - Năm tiêu chí. Mỗi tiêu chí nhận Pass, Needs Improvement hoặc Fail.
- Phát hiện xếp theo mức độ. Mỗi phát hiện ghi rõ file và dòng, mức độ (Critical, High, Medium hoặc Low) và cách sửa cụ thể. Kết luận là APPROVED, APPROVED WITH CONDITIONS hoặc REJECTED.
3. Các Quyết Định Thiết Kế
Mỗi quyết định dưới đây đều xuất phát từ một điều Day 3 đề cao.
Kiểm tra rẻ trước kiểm tra đắt. Day 3 nói việc xác định lặp đi lặp lại nên nằm trong scripts/. Vì vậy linter chạy trước, và token của agent dành cho những câu mà regex không trả lời được, ví dụ description có mơ hồ không.
Luật "đưa ra lý do" nằm trong code. Day 3 khuyên: nếu bạn bắt gặp việc gõ "ALWAYS" hay "NEVER" viết hoa, hãy giải thích lý do thay vì ra lệnh. Linter tìm từng từ như vậy nằm ngoài code span, rồi quét khoảng 150 ký tự hai bên để tìm các từ như "because" hay "since". Không thấy thì báo lỗi và gợi ý chuyển luật đó sang AGENTS.md. Đây là heuristic thô, nhưng bắt được lỗi phổ biến nhất mà không tốn gì.
Khả năng kiểm thử bám theo bốn kiểu lỗi. Skill ghi rõ bốn kiểu lỗi của Day 3: trigger, execution, regression và token budget. Tôi cũng giữ nguyên cổng của whitepaper: thiếu một loại là skill vẫn ở mức bản nháp, dù ca thuận lợi chạy tốt đến đâu.
Danh sách "skill smell" có sẵn. Tôi chép sáu mẫu xấu của Day 3: vượt 5.000 từ, hai đội cùng có thể sở hữu, không viết nổi ba test case, không tham chiếu tài nguyên nào, mục ca biên cứ phình ra, và description mở đầu bằng "a helpful skill for". Người rà soát gọi đúng tên lỗi thay vì nói "thấy có gì đó sai sai".
Phát hiện phải có bằng chứng. Phát hiện thiếu file, dòng, mức độ hoặc cách sửa thì không tính là phát hiện. Nhờ vậy báo cáo chuyển thành danh sách việc cần làm rất dễ.
Skill tự tuân thủ luật do chính nó đặt ra. Cả SKILL.md dài khoảng 1.700 từ, còn linter nằm trong scripts/. Chạy linter lên chính skill này thì nó vượt qua. Skill cũng cấm gắn cứng tên công cụ và đường dẫn, nên dùng được trên nhiều agent, đúng tinh thần "runtime có thể thay thế" của Day 3.
Kết thúc bằng cổng triển khai. Bảy ô kiểm lấy từ checklist triển khai của Day 3: lint, người khác đọc lại description, test script trong CI, bộ eval có ngưỡng đạt, quét bảo mật, thử cài trên nhiều công cụ và cấp quyền ở cấp tổ chức.
[!NOTE] Những gì skill chưa làm được: linter chỉ kiểm tra cấu trúc, không kiểm tra hành vi. Nó không đo được độ chính xác của trigger hay regression, nên các mục này vẫn là checklist để bạn tự chạy. Tôi cũng chưa viết eval case cho chính review-skill.
4. Cài Đặt & Chạy Thử
Trình Cài Đặt Tương Tác
Một lệnh mở menu để bạn chọn coding agent và các skill cần cài. Không cần git clone.
# Windows (PowerShell)
irm https://raw.githubusercontent.com/pxuanbach/the-skills/main/install.ps1 | iex
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/pxuanbach/the-skills/main/install.sh | bash
Chỉ Cài review-skill
Truyền cờ để bỏ qua menu:
curl -fsSL https://raw.githubusercontent.com/pxuanbach/the-skills/main/install.sh | bash -s -- --targets claude --skills review-skill
--targets nhận pi, claude, antigravity, codex, opencode, common hoặc all. --skills nhận danh sách cách nhau bằng dấu phẩy hoặc all. Script PowerShell dùng -Targets và -Skills theo cách tương tự.
| Agent | Đường dẫn cài đặt |
|---|---|
| Pi Agent | ~/.pi/agent/skills |
| Claude Code | ~/.claude/skills |
| Antigravity / Gemini CLI | ~/.gemini/config/skills |
| OpenAI Codex CLI | ~/.codex/skills |
| OpenCode | ~/.config/opencode/skills |
Chạy Riêng Linter
python ~/.claude/skills/review-skill/scripts/validate_skill.py path/to/your-skill
[!IMPORTANT] Chỉ trỏ rà soát vào một thư mục skill. Trỏ vào thư mục cha sẽ trộn nhiều skill không liên quan vào cùng một báo cáo.
Prompt Thực Thi
Rà soát skill trong ./skills/my-skill. Chạy linter trước, sau đó đánh giá cả năm tiêu chí và đưa báo cáo xếp theo mức độ nghiêm trọng.
Kết Quả Mong Đợi
Một báo cáo "Skill Review Report" gồm tóm tắt, đánh giá năm tiêu chí, các phát hiện nhóm theo mức độ kèm file và dòng, và checklist sửa lỗi theo thứ tự ưu tiên.