1. Skill là gì?

Claude Skill là một tập hợp hướng dẫn được lưu trong file SKILL.md, giúp Claude thực hiện một tác vụ cụ thể theo quy trình đã định nghĩa sẵn.

Ví dụ:

• Review Pull Request.

• Tạo Unit Test.

• Phân tích log.

• Tạo commit message.

• Kiểm tra bảo mật.

• Viết tài liệu kỹ thuật.

Thay vì phải nhập lại một prompt dài nhiều lần, chúng ta có thể đóng gói prompt đó thành một Skill.

Claude có thể:

• Tự động sử dụng Skill khi thấy phù hợp.

• Hoặc người dùng gọi trực tiếp bằng cú pháp:

/skill-name

Nội dung đầy đủ của Skill chỉ được tải khi Skill được sử dụng, thay vì luôn nằm trong context như CLAUDE.md.

2. Skill làm được gì?

Skill có thể được sử dụng để:

• Lưu lại một workflow thường xuyên sử dụng.

• Chuẩn hóa cách Claude thực hiện công việc.

• Cung cấp kiến thức riêng của dự án.

• Tạo các slash command tùy chỉnh.

• Truyền tham số vào workflow.

• Cho phép Claude đọc file, tìm kiếm hoặc chạy lệnh.

• Chạy một tác vụ bằng model cụ thể.

• Chạy tác vụ trong subagent riêng biệt.

• Kết hợp template, script và tài liệu tham khảo.

Ví dụ, chúng ta có thể tạo Skill:

/review-code

Khi được gọi, Claude sẽ:

1. Đọc code thay đổi.

2. Kiểm tra coding convention.

3. Kiểm tra lỗi logic.

4. Kiểm tra security.

5. Kiểm tra performance.

6. Đưa ra đề xuất sửa lỗi.

3. Skill được lưu ở đâu?

Skill dùng cho một dự án

.claude/skills/<skill-name>/SKILL.md

Ví dụ:

.claude/
└── skills/
    └── review-code/
        └── SKILL.md

Skill này chỉ áp dụng trong project hiện tại.

Skill dùng cho tất cả project

~/.claude/skills/<skill-name>/SKILL.md

Ví dụ:

~/.claude/
└── skills/
    └── generate-commit/
        └── SKILL.md

Skill cá nhân có thể được sử dụng trong tất cả project trên máy tính của bạn.

4. Cấu trúc Skill cơ bản

Một Skill tối thiểu chỉ cần file SKILL.md:

review-code/
└── SKILL.md

Nội dung mẫu:

---
name: review-code
description: Review code về logic, security, performance và coding convention.
---

# Review Code

Thực hiện review code theo các bước:

1. Đọc và hiểu mục đích của code.
2. Kiểm tra lỗi logic.
3. Kiểm tra coding convention.
4. Kiểm tra security.
5. Kiểm tra performance.
6. Đưa ra cách sửa cụ thể.

## Output

Trả về kết quả gồm:

- Summary
- Critical issues
- Major issues
- Minor issues
- Suggested fixes

Phần nằm giữa hai dấu --- được gọi là YAML frontmatter.

Phần bên dưới là hướng dẫn Claude thực hiện khi Skill được kích hoạt.

5. Cách gọi Skill

Với cấu trúc:

.claude/skills/review-code/SKILL.md

Có thể gọi Skill bằng:

/review-code

Hoặc truyền thêm nội dung:

/review-code src/Services/PaymentService.php

Claude cũng có thể tự động gọi Skill nếu yêu cầu của người dùng phù hợp với trường description.

Ví dụ:

Review giúp tôi file PaymentService.php.

6. Truyền tham số bằng $ARGUMENTS

Skill có thể nhận nội dung phía sau slash command thông qua biến:

$ARGUMENTS

Ví dụ:

---
name: review-code
description: Review một file hoặc thư mục code.
---

Review code tại:

$ARGUMENTS

Kiểm tra:

1. Logic.
2. Security.
3. Performance.
4. Coding convention.

Khi chạy:

/review-code src/Services/PaymentService.php

Claude sẽ nhận được:

Review code tại:

src/Services/PaymentService.php

Ngoài $ARGUMENTS, có thể lấy từng tham số bằng:

$0
$1
$2

Ví dụ:

So sánh branch `$0` với branch `$1`.

Cách gọi:

/compare-branch feature/login develop

Trong đó:

$0 = feature/login
$1 = develop

Claude Code cũng hỗ trợ khai báo tham số có tên bằng trường arguments.

7. Cấu hình allowed-tools

Mặc định, Claude có thể yêu cầu quyền khi sử dụng một số tool như:

• Bash

• Edit

• Write

Trường allowed-tools cho phép Skill sử dụng một số tool mà không cần hỏi lại trong lượt chạy hiện tại.

Ví dụ:

---
name: analyze-code
description: Phân tích cấu trúc và chất lượng source code.
allowed-tools:
  - Read
  - Grep
  - Glob
---

Phân tích source code trong `$ARGUMENTS`.

Không thay đổi nội dung file.

Skill trên được phép:

• Đọc file bằng Read.

• Tìm nội dung bằng Grep.

• Tìm file bằng Glob.

Cho phép một số lệnh Bash

---
name: check-git
description: Kiểm tra trạng thái và thay đổi hiện tại của Git.
allowed-tools:
  - Bash(git status *)
  - Bash(git diff *)
  - Bash(git log *)
---

Kiểm tra trạng thái repository và tóm tắt các thay đổi.

Không nên cấp quyền quá rộng như:

allowed-tools:
  - Bash

Thay vào đó, nên giới hạn theo từng lệnh:

allowed-tools:
  - Bash(git status *)
  - Bash(git diff *)

allowed-tools chỉ tự động cấp quyền trong lượt chạy Skill hiện tại. Nó không giới hạn những tool khác; các tool không nằm trong danh sách vẫn tuân theo permission settings thông thường.

8. Cấu hình disallowed-tools

disallowed-tools dùng để loại bỏ một số tool khi Skill đang chạy.

Ví dụ tạo Skill chỉ được phân tích, không được sửa code:

---
name: readonly-review
description: Review code ở chế độ chỉ đọc.
allowed-tools:
  - Read
  - Grep
  - Glob
disallowed-tools:
  - Edit
  - Write
---

Review code nhưng tuyệt đối không thay đổi file.

Cấu hình này phù hợp với:

• Code review.

• Security audit.

• Architecture analysis.

• Điều tra lỗi production.

Quyền chặn cũng chỉ có hiệu lực trong lượt chạy Skill hiện tại.

9. Cấu hình model

Trường model cho phép chỉ định model được sử dụng khi Skill chạy.

Ví dụ:

---
name: architecture-review
description: Phân tích kiến trúc hệ thống và đưa ra đề xuất cải thiện.
model: opus
---

Phân tích kiến trúc của hệ thống trong `$ARGUMENTS`.

Tập trung vào:

1. Khả năng mở rộng.
2. Maintainability.
3. Coupling giữa các module.
4. Security.
5. Trade-off của từng phương án.

Một Skill đơn giản có thể dùng model nhẹ hơn:

---
name: generate-commit
description: Tạo commit message từ Git diff.
model: sonnet
allowed-tools:
  - Bash(git diff *)
---

Dựa trên Git diff, tạo commit message theo Conventional Commits.

model chỉ ghi đè model trong lượt chạy Skill hiện tại. Ở prompt tiếp theo, Claude quay lại model của session.

Có thể dùng:

model: inherit

để tiếp tục sử dụng model hiện tại.

10. Cấu hình effort

effort kiểm soát mức độ suy luận Claude sử dụng trong Skill.

Ví dụ:

---
name: deep-code-review
description: Review chuyên sâu những thay đổi phức tạp.
model: opus
effort: high
---

Phân tích code thật kỹ và tìm các edge case tiềm ẩn.

Các giá trị phổ biến:

low
medium
high
xhigh
max

Không phải model nào cũng hỗ trợ tất cả mức effort.

11. Ngăn Claude tự động gọi Skill

Mặc định, Claude có thể tự kích hoạt Skill nếu description phù hợp.

Đối với những thao tác nhạy cảm như:

• Commit code.

• Deploy.

• Push Git.

• Gửi tin nhắn.

• Thay đổi database.

Nên thêm:

disable-model-invocation: true

Ví dụ:

---
name: deploy-production
description: Deploy ứng dụng lên production.
disable-model-invocation: true
allowed-tools:
  - Bash(./scripts/deploy.sh *)
---

Deploy `$ARGUMENTS` lên production.

1. Chạy test.
2. Build ứng dụng.
3. Chạy script deploy.
4. Kiểm tra trạng thái sau deploy.

Khi đó Claude không được tự quyết định chạy Skill.

Người dùng phải gọi trực tiếp:

/deploy-production release-1.2.0

Trường này đặc biệt quan trọng với những workflow có side effect.

12. Tạo Skill chỉ dành cho Claude

Một số Skill chỉ cung cấp kiến thức nền, không cần xuất hiện trong menu /.

Có thể dùng:

user-invocable: false

Ví dụ:

---
name: legacy-system-context
description: Cung cấp kiến thức về kiến trúc hệ thống legacy khi Claude làm việc với module cũ.
user-invocable: false
---

Khi làm việc với thư mục `legacy/`:

- Không thay đổi public API.
- Không thay đổi cấu trúc database.
- Giữ backward compatibility.
- Viết characterization test trước khi refactor.

Skill này có thể được Claude tự sử dụng nhưng người dùng không gọi trực tiếp từ menu slash command.

13. Giới hạn Skill theo đường dẫn

Có thể dùng paths để Skill chỉ tự động kích hoạt với một nhóm file nhất định.

Ví dụ:

---
name: php-review
description: Review source code PHP.
paths:
  - "**/*.php"
  - "app/code/**/*.php"
---

Khi review PHP:

1. Tuân thủ PSR-12.
2. Kiểm tra Dependency Injection.
3. Kiểm tra exception handling.
4. Kiểm tra type declaration.

Skill này phù hợp khi Claude đang làm việc với các file PHP, thay vì kích hoạt cho toàn bộ project.

14. Chạy Skill trong subagent

Với các tác vụ lớn, có thể chạy Skill trong context riêng:

context: fork

Ví dụ:

---
name: deep-research
description: Phân tích chuyên sâu một phần của codebase.
context: fork
agent: Explore
background: false
---

Phân tích `$ARGUMENTS`.

1. Tìm các file liên quan.
2. Xác định luồng xử lý.
3. Xác định dependency.
4. Tìm rủi ro tiềm ẩn.
5. Tổng hợp kết quả kèm đường dẫn file.

Trong trường hợp này:

• Claude tạo một subagent riêng.

• Skill không làm đầy context chính.

• Subagent thực hiện phân tích.

• Kết quả được trả về conversation chính.

Các agent có thể sử dụng:

Explore
Plan
general-purpose

Hoặc custom agent trong:

.claude/agents/

background: false yêu cầu Claude chờ kết quả ngay trong lượt hiện tại.

15. Thêm file hỗ trợ cho Skill

Skill nâng cao không nên nhồi toàn bộ nội dung vào SKILL.md.

Có thể tổ chức như sau:

code-review/
├── SKILL.md
├── references/
│   ├── security.md
│   └── performance.md
├── examples/
│   └── review-example.md
├── templates/
│   └── report.md
└── scripts/
    └── collect-diff.sh

Trong SKILL.md:

## Tài liệu hỗ trợ

- Đọc [references/security.md](references/security.md) khi kiểm tra security.
- Đọc [references/performance.md](references/performance.md) khi kiểm tra performance.
- Sử dụng [templates/report.md](templates/report.md) để tạo báo cáo.
- Tham khảo [examples/review-example.md](examples/review-example.md) về format đầu ra.

Cách này giúp:

• SKILL.md ngắn gọn.

• Dễ bảo trì.

• Chỉ tải tài liệu khi cần.

• Giảm token không cần thiết.

Claude khuyến nghị giữ SKILL.md dưới khoảng 500 dòng và chuyển nội dung chi tiết sang file hỗ trợ.

16. Chạy lệnh để lấy context động

Claude Skill hỗ trợ cú pháp:

!`command`

Lệnh được chạy trước, sau đó kết quả được chèn vào nội dung Skill.

Ví dụ:

---
name: review-changes
description: Review những thay đổi chưa commit.
allowed-tools:
  - Bash(git diff *)
  - Bash(git status *)
---

## Git status

!`git status --short`

## Git diff

!`git diff HEAD`

## Yêu cầu

1. Tóm tắt thay đổi.
2. Tìm lỗi tiềm ẩn.
3. Kiểm tra file test.
4. Đề xuất commit message.

Khi Skill chạy:

1. Claude Code chạy git status.

2. Claude Code chạy git diff.

3. Kết quả được chèn vào prompt.

4. Claude phân tích dữ liệu thực tế.

Đây là cách hữu ích để tạo Skill dựa trên trạng thái hiện tại của project.

17. Ví dụ Skill nâng cao hoàn chỉnh

---
name: review-pull-request
description: Review Pull Request về logic, security, performance, coding convention và test coverage.
argument-hint: "[base-branch]"
model: opus
effort: high
context: fork
agent: Explore
background: false
disable-model-invocation: true
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
  - Bash(git status *)
disallowed-tools:
  - Edit
  - Write
---

# Pull Request Review

Base branch:

$ARGUMENTS

## Git status

!`git status --short`

## Changes

!`git diff $ARGUMENTS...HEAD`

## Workflow

1. Xác định mục đích của thay đổi.
2. Phân tích các file đã thay đổi.
3. Kiểm tra lỗi logic.
4. Kiểm tra security.
5. Kiểm tra performance.
6. Kiểm tra backward compatibility.
7. Kiểm tra test coverage.
8. Phân loại vấn đề theo mức độ.

## Output

### Summary

Tóm tắt mục đích và phạm vi thay đổi.

### Critical Issues

Các lỗi nghiêm trọng cần sửa trước khi merge.

### Major Issues

Các lỗi logic, security hoặc performance quan trọng.

### Minor Issues

Các vấn đề về naming, readability hoặc maintainability.

### Suggested Fixes

Đưa ra cách sửa cụ thể kèm ví dụ code khi cần.

Không chỉnh sửa bất kỳ file nào.

Cách gọi:

/review-pull-request develop

Skill này sẽ:

• Sử dụng model mạnh hơn.

• Chạy trong subagent riêng.

• Đọc Git diff.

• Không được chỉnh sửa source code.

• Không tự động kích hoạt.

• Trả về báo cáo review hoàn chỉnh.

18. Một số trường frontmatter quan trọng

19. Lưu ý khi tạo Skill

Viết description rõ ràng

Không nên:

description: Hỗ trợ code.

Nên:

description: Review code PHP về logic, security, performance và PSR-12.

Không cấp quyền quá rộng

Không nên:

allowed-tools:
  - Bash

Nên:

allowed-tools:
  - Bash(git diff *)
  - Bash(git status *)

Workflow có side effect phải chạy thủ công

Nên thêm:

disable-model-invocation: true

cho các Skill như:

• Deploy.

• Commit.

• Push.

• Gửi tin nhắn.

• Thay đổi database.

Skill chỉ phân tích nên chặn ghi file

disallowed-tools:
  - Edit
  - Write

Tách tài liệu dài thành file riêng

Không nên để toàn bộ checklist, template và ví dụ trong SKILL.md.

20. Kết luận

Claude Skill là cách đóng gói một prompt hoặc workflow thành một công cụ có thể tái sử dụng.

Một Skill cơ bản chỉ cần:

SKILL.md

Một Skill nâng cao có thể kết hợp:

• model

• effort

• allowed-tools

• disallowed-tools

• $ARGUMENTS

• context: fork

• Subagent

• Script

• Template

• Context động từ command line

Khi thiết kế tốt, Skill giúp Claude thực hiện công việc nhất quán hơn, giảm việc lặp lại prompt và chuẩn hóa workflow cho cả cá nhân lẫn đội nhóm.