Ở bài 3.2, /add-endpoint là một lệnh: bạn gõ, Claude làm. Nhưng nhiều việc trong team không nên chờ ai nhớ mà gõ lệnh. Ví dụ: trước khi mở PR, đoạn code phải qua checklist review của team. Nếu Claude tự nhận ra lúc bạn nói "mình sắp mở PR", tự đọc checklist và tự chạy script kiểm tra, thì checklist được dùng mỗi lần chứ không chỉ khi có người nhớ. Bài này viết skill như vậy cho todo-api.
Skill khác lệnh ở đâu
Về hình thức thì không khác: vẫn là thư mục .claude/skills/<tên>/ có SKILL.md. Khác ở cách dùng. Lệnh ở bài 3.2 là một prompt bạn gọi bằng tay. Một Agent Skill là một gói năng lực: hướng dẫn, tài liệu tham khảo và script nằm chung một thư mục, và Claude tự quyết định khi nào dùng dựa vào phần mô tả.
Skill của Claude Code theo chuẩn mở Agent Skills (agentskills.io), nên một skill viết tốt dùng lại được ở các công cụ AI khác theo cùng chuẩn. Claude Code thêm vài trường riêng như disable-model-invocation, context, argument-hint.
Description quyết định khi nào Claude gọi
Khi mở phiên, Claude không đọc toàn bộ các file SKILL.md. Claude Code chỉ nạp một danh sách gồm tên và description của từng skill. Nội dung đầy đủ chỉ được nạp khi skill được gọi. Vì vậy description là thứ duy nhất Claude dựa vào để biết lúc nào nên dùng skill của bạn.
Một mô tả tốt trả lời hai câu: skill làm gì và khi nào dùng, bằng những từ người dùng hay nói thật.
# Quá chung chung: Claude không biết lúc nào cần
description: Review helper
# Tốt: nói việc, nói lúc, có từ khóa người dùng hay gõ
description: Review the current branch against the todo-api team checklist. Use when the user asks to review their changes, check a branch, or get ready to open a pull request.Vài giới hạn cần biết:
- Phần
descriptioncộng với trường tùy chọnwhen_to_usebị cắt ở 1.536 ký tự trong danh sách. Đặt trường hợp dùng chính lên đầu. - Cả danh sách có ngân sách khoảng 1% cửa sổ ngữ cảnh. Có quá nhiều skill thì Claude Code bỏ bớt mô tả của skill ít dùng nhất, và skill đó khó được gọi đúng lúc. Chạy
/skill-doctorđể xem skill nào tốn chỗ mà không ai dùng.
Khi skill không chạy như mong đợi:
- Không được gọi: thêm từ khóa người dùng hay nói, hỏi "What skills are available?" xem skill có trong danh sách không.
- Bị gọi quá thường xuyên: viết mô tả cụ thể hơn, hoặc thêm
disable-model-invocation: true.
File đi kèm và script
Skill là một thư mục, nên bạn có thể đặt nhiều file vào đó:
.claude/skills/pr-review/
├── SKILL.md (bắt buộc: tổng quan và các bước)
├── checklist.md (Claude đọc khi cần)
└── scripts/
└── red-flags.sh (Claude chạy, không đọc vào ngữ cảnh)Ba loại file được dùng theo ba cách:
SKILL.mdđược nạp khi skill được gọi. Docs khuyên giữ dưới 500 dòng.- File tham khảo như
checklist.mdchỉ được đọc khi Claude cần. Nhắc tới nó trongSKILL.mdkèm nội dung và lúc cần đọc, ví dụ "kiểm tra từng mục trong[checklist.md](checklist.md)". Tài liệu dài để ở đây không tốn chỗ cho tới khi dùng. - Script được chạy, chỉ output của nó vào ngữ cảnh. Việc nào cần kết quả chính xác (tìm dòng cấm, đếm, kiểm tra định dạng) thì giao cho script, đừng để Claude tự đoán.
Để gọi script, dùng biến ${CLAUDE_SKILL_DIR}, là thư mục chứa SKILL.md. Đường dẫn nhờ vậy luôn đúng, dù skill nằm trong dự án, trong ~/.claude/skills/ hay trong plugin. Biến này được thay ở hai chỗ: nội dung skill và luật Bash(...) trong allowed-tools. Dùng cùng biến ở cả hai chỗ thì script chạy không cần hỏi quyền:
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/red-flags.sh *)Khi thử thật, chúng tôi gặp một chỗ dễ vấp: Claude có lúc rút gọn đường dẫn thành .claude/skills/... hoặc gộp script với lệnh khác, và lệnh không còn khớp luật nên vẫn bị hỏi. Viết rõ trong bước: "chạy đúng lệnh này, riêng một mình, giữ nguyên đường dẫn đầy đủ".
So với !`lệnh` ở bài 3.2: lệnh chèn chạy trước khi Claude đọc skill, còn script đi kèm do Claude chạy khi tới bước đó, và Claude có thể đọc output rồi quyết định làm tiếp.
Ai gọi và gọi ở đâu
Bài 3.2 đã có disable-model-invocation: true để chỉ bạn gọi. Chiều ngược lại là user-invocable: false: chỉ Claude gọi, skill ẩn khỏi menu /. Dùng cho kiến thức nền không phải là một hành động, ví dụ skill legacy-billing giải thích hệ thống thanh toán cũ. Claude cần biết khi động vào phần đó, nhưng gõ /legacy-billing thì chẳng để làm gì.
| Frontmatter | Bạn gọi | Claude gọi | Mô tả nằm trong ngữ cảnh |
|---|---|---|---|
| (mặc định) | Có | Có | Có |
disable-model-invocation: true |
Có | Không tự gọi | Không |
user-invocable: false |
Không | Có | Có |
user-invocable: false chỉ ẩn skill khỏi menu, không chặn Claude gọi. Muốn chặn Claude thì dùng disable-model-invocation: true.
Tùy permission mode, Claude Code có thể hỏi bạn trước khi Claude tự gọi một skill. Khi thử ở chế độ mặc định, lần gọi pr-review đầu tiên cần được cho phép. Quy tắc quyền Skill(pr-review) trong cài đặt bỏ qua câu hỏi đó; Skill(deploy *) trong deny thì chặn hẳn skill deploy.
Trường paths nhận mẫu glob, cùng cú pháp với rule theo đường dẫn ở bài 2.3. Skill chỉ kích hoạt khi Claude làm việc với file khớp mẫu, ví dụ một skill về quy ước route chỉ cần khi động vào src/routes/**. Mẫu tính từ thư mục làm việc, nên không áp cho file nằm ngoài, kể cả một git worktree bên cạnh.
Chạy riêng trong subagent
Thêm context: fork, skill chạy trong một subagent mới (một agent phụ có ngữ cảnh riêng, là chủ đề của cấp 4). Trường agent chọn loại subagent: Explore, Plan, general-purpose (mặc định) hoặc agent bạn tự định nghĩa.
---
name: deep-research
description: Research a topic in this codebase thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS: find the relevant files, read them,
and summarise with file references.Cần nhớ ba điều:
- Subagent không thấy lịch sử hội thoại. Nội dung skill là toàn bộ nhiệm vụ của nó, nên phải tự đủ nghĩa.
- Chỉ hợp với skill có nhiệm vụ cụ thể. Skill kiểu "theo các quy ước API này" mà không có việc gì để làm thì subagent nhận hướng dẫn rồi trả về không có gì đáng kể.
- Mặc định subagent chạy nền: bạn làm tiếp, kết quả tự quay về khi xong. Đặt
background: falsenếu muốn chờ ngay trong lượt đó.
Skill pr-review của chúng ta cần thấy bạn đang làm gì, nên giữ nó chạy ngay trong hội thoại.
Skill review PR cho todo-api
Ghép tất cả lại. SKILL.md:
---
name: pr-review
description: Review the current branch against the todo-api team checklist. Use when the user asks to review their changes, check a branch, or get ready to open a pull request.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/red-flags.sh *)
---
Review this branch against main before a pull request.
1. Run exactly `${CLAUDE_SKILL_DIR}/scripts/red-flags.sh main` on its own, full path as written, and list every line it prints
2. Read the diff with `git diff main...HEAD`
3. Check each item in [checklist.md](checklist.md): pass, fail or n/a, with file:line for each fail
4. End with one verdict: ready, ready after fixes, or not readychecklist.md là checklist của team: route mới phải có test, lỗi trả về dạng { error: "..." }, todo không có hoặc đã xóa trả 404 chứ không bao giờ 500, không để lại console.log, npm test đạt.
scripts/red-flags.sh tìm những dòng mới thêm mà team không bao giờ merge:
#!/usr/bin/env bash
# Print added lines the team never merges: console.log, debugger, test.only
base="${1:-main}"
git diff "$base"...HEAD -U0 -- src test \
| grep -E '^\+[^+].*(console\.log|debugger|\.only\()' \
|| echo "No red flags against $base"Nhớ chmod +x cho script. Dòng || echo giúp script luôn thoát 0 kể cả khi không tìm thấy gì.
Thử skill trong một phiên mới, vì ngữ cảnh còn sót lại lúc viết skill sẽ che mất chỗ hướng dẫn còn thiếu. Nói "mình sắp mở PR cho nhánh này, xem giúp với", không gõ /pr-review. Khi chúng tôi thử, Claude tự gọi skill, chạy script, chỉ ra hai dòng console.log kèm số dòng, và kết luận "ready after fixes". Để biết skill có giúp thật không, hỏi lại cùng câu trong phiên mới khi đã tắt skill (/skills, chọn skill, Space đổi sang off, Esc để lưu) rồi so sánh.
Cuối cùng, skill là hướng dẫn, không phải luật. Phiên dài bị nén ngữ cảnh thì Claude Code chỉ giữ phần đầu của mỗi skill đã gọi, nên để điều quan trọng nhất lên trên. Điều gì phải đúng mọi lúc, như không bao giờ ghi vào .env, thì đưa vào hook ở cấp 6.
Commit .claude/skills/pr-review/ là cả team có cùng một người review biết checklist. Cấp sau: giao việc cho những agent chuyên trách.