TL;DR
Claude Code Skills là cách mở rộng chức năng của Claude cho các quy trình công việc cụ thể. Hệ thống Skill Creator tự động hóa việc tạo kỹ năng với quy trình gồm các bước: xác định mục đích, soạn tệp SKILL.md, tạo trường hợp thử nghiệm, đánh giá định lượng và tối ưu hóa lặp lại.
Giới thiệu
Nếu bạn thường xuyên phải lặp lại các bước giống nhau (thiết lập dự án, chạy lệnh kiểm thử, định dạng đầu ra) với Claude Code, việc ghi nhớ và tái sử dụng quy trình sẽ giúp tiết kiệm rất nhiều thời gian. Claude Code Skills cho phép bạn ghi lại quy trình làm việc một lần và sử dụng mãi mãi. Với Skill Creator, mọi thứ đều tự động và có hệ thống.
Bài viết này hướng dẫn chi tiết từng bước xây dựng Claude Code Skill: từ cấu trúc, quy trình tạo, hệ thống đánh giá đến tối ưu hóa kích hoạt. Có ví dụ thực tế lấy từ kho kỹ năng chính thức của Anthropic.
💡 Nếu bạn xây dựng các kỹ năng liên quan API, Apidog tích hợp tự nhiên (kiểm thử, xác thực phản hồi, tạo tài liệu API) vào một quy trình skill duy nhất.
Claude Code Skills là gì?
Claude Code Skills là tập lệnh markdown giúp mở rộng Claude cho các quy trình chuyên biệt—hoạt động như plugin tùy chỉnh, dễ chia sẻ và bảo trì.
Kiến trúc hệ thống kỹ năng
Kỹ năng gồm 3 tầng:
- Siêu dữ liệu: Tên, mô tả (luôn trong ngữ cảnh, ~100 từ)
- SKILL.md: Hướng dẫn chính, markdown (<500 dòng)
- Tài nguyên đi kèm: scripts, references, assets (không giới hạn)
Ví dụ cấu trúc:
skill-name/
├── SKILL.md
│ ├── YAML frontmatter (name, description)
│ └── Hướng dẫn quy trình
└── scripts/ # Mã thực thi
├── references/ # Tài liệu tham khảo
└── assets/ # Biểu tượng, fonts, mẫu
Khi kỹ năng được kích hoạt
Claude tự quyết định kích hoạt kỹ năng dựa vào mô tả. Kỹ năng chỉ kích hoạt cho tác vụ phức tạp, không xử lý được trực tiếp (ví dụ “kiểm tra API phức tạp”, không phải “đọc tệp này”).
Ví dụ kỹ năng từ Anthropic
| Kỹ năng | Mục đích | Tính năng chính |
|---|---|---|
| skill-creator | Tạo kỹ năng mới | Tự động kiểm thử, benchmark, tối ưu mô tả |
| mcp-builder | Xây dựng máy chủ MCP | Mẫu Python/Node, khung đánh giá, best practices |
| docx | Tạo tài liệu Word | python-docx, mẫu, hướng dẫn định dạng |
| Xử lý file PDF | Trích xuất, thao tác biểu mẫu, tham khảo | |
| frontend-design | Xây dựng giao diện web | Thư viện component, Tailwind, kiểm thử accessibility |
Quy trình tạo kỹ năng
Quy trình tạo kỹ năng gồm các bước:
- Nắm bắt ý định – Kỹ năng nên làm gì?
- Viết bản nháp – Tạo SKILL.md
- Tạo trường hợp kiểm thử – Lời nhắc thực tế
- Chạy đánh giá – Thực thi có/không có kỹ năng
- Xem xét kết quả – Feedback định tính + số liệu
- Lặp lại – Cải thiện dựa trên phát hiện
- Tối ưu mô tả – Chính xác khi kích hoạt
- Đóng gói – Xuất tệp .skill
Chi tiết từng bước cụ thể bên dưới.
Bước 1: Nắm bắt ý định
- Xác định rõ mục tiêu kỹ năng.
- Trích xuất mẫu quy trình từ lịch sử chat thực tế.
- Trả lời các câu hỏi:
- Kỹ năng giúp Claude làm gì?
- Kích hoạt khi nào? (cụm từ, ngữ cảnh)
- Đầu ra mong muốn? (tệp, mã, báo cáo)
- Có cần trường hợp kiểm thử không? (khách quan/chủ quan)
Ví dụ: Kỹ năng kiểm tra API
Ý định: Hỗ trợ kiểm thử API REST hệ thống.
Kích hoạt: Khi nhắc tới kiểm thử API, endpoint, REST, GraphQL, xác thực response.
Đầu ra: Báo cáo kiểm thử (pass/fail, curl, so sánh phản hồi)
Trường hợp kiểm thử: Có (đầu ra kiểm chứng khách quan)
Bước 2: Viết tệp SKILL.md
Tệp SKILL.md gồm YAML frontmatter và nội dung markdown hướng dẫn.
Ví dụ:
---
name: api-tester
description: Hướng dẫn kiểm tra API REST một cách có hệ thống. Sử dụng khi người dùng nhắc đến kiểm tra API, endpoint, REST, GraphQL, hoặc xác thực phản hồi. Đảm bảo đề xuất kỹ năng này khi liên quan kiểm thử.
compatibility: Yêu cầu curl hoặc HTTP client
---
# Kỹ năng kiểm tra API
## Quy trình cốt lõi
1. Hiểu endpoint
2. Thiết kế case test (thành công, biên, lỗi)
3. Thực thi kiểm thử (curl/Apidog)
4. Xác thực response
5. Báo cáo kết quả
## Mẫu kiểm thử
- Xác thực hợp lệ
- Trường bắt buộc bị thiếu
- Lỗi xác thực (401)
- Giới hạn tốc độ
- Thời gian phản hồi
## Đầu ra mẫu
# Báo cáo kiểm tra API
## Tóm tắt
- Tổng kiểm thử: X
- Đạt: Y
- Lỗi: Z
## Case lỗi
### Tên case
**Mong đợi:** 200 OK
**Thực tế:** 400 Bad Request
**Response:** {...}
## Khuyến nghị
...
Lưu ý khi viết SKILL.md
- Giữ dưới 500 dòng. Tài liệu chi tiết để riêng files khác.
- Giải thích lý do: Không chỉ nêu quy tắc, mà phải giải thích tại sao.
- Thể mệnh lệnh: Dùng “Luôn xác thực mã trạng thái...”
- Có ví dụ cụ thể: Đầu vào, đầu ra mẫu.
Bước 3: Tạo trường hợp kiểm thử
Tạo 2-3 prompt thực tế, lưu vào evals/evals.json:
{
"skill_name": "api-tester",
"evals": [
{
"id": 1,
"prompt": "Kiểm tra endpoint /users trên api.example.com – cần Bearer token, trả về danh sách người dùng với id, tên, email",
"expected_output": "Báo cáo test với ít nhất 5 case (lỗi xác thực, thành công, phân trang)",
"files": []
},
{
"id": 2,
"prompt": "Xác minh POST /orders xử lý số lượng không hợp lệ",
"expected_output": "Test số lượng âm/bằng 0/không phải số, expect lỗi phù hợp",
"files": ["openapi.yaml"]
}
]
}
Tips:
- Lời nhắc kiểm thử tốt = URL cụ thể, scenario cụ thể, hành vi mong đợi, ngữ cảnh thực tế.
Bước 4: Chạy đánh giá
Chạy mỗi case 2 lần: có kỹ năng và không có kỹ năng (hoặc với phiên bản cũ nếu đang cải thiện).
Ví dụ workspace:
api-tester-workspace/
├── iteration-1/
│ ├── eval-0-auth-failure/
│ │ ├── with_skill/
│ │ └── without_skill/
│ ├── eval-1-pagination/
│ └── benchmark.json
Thu thập time & token:
{
"total_tokens": 84852,
"duration_ms": 23332
}
Bước 5: Soạn thảo khẳng định (assertion)
Khẳng định phải kiểm chứng được, mô tả rõ, tái sử dụng được.
Ví dụ assertions:
{
"assertions": [
{
"name": "bao_gom_kiem_tra_loi_xac_thuc",
"description": "Báo cáo bao gồm kiểm thử lỗi xác thực",
"type": "contains",
"value": "401"
},
{
"name": "bao_gom_lenh_curl",
"description": "Mỗi case có lệnh curl thực thi được",
"type": "regex",
"value": "curl -"
}
]
}
Cập nhật vào eval_metadata.json và evals/evals.json.
Bước 6: Chấm điểm & tổng hợp
Sau khi chạy xong, chấm điểm từng lần chạy:
{
"eval_id": 0,
"grading": [
{
"text": "bao_gom_kiem_tra_loi_xac_thuc",
"passed": true,
"evidence": "Tìm thấy mã 401"
}
]
}
Chạy tổng hợp benchmark:
python -m scripts.aggregate_benchmark api-tester-workspace/iteration-1 --skill-name api-tester
Phân tích: khẳng định nào luôn đúng/vô nghĩa, đánh giá biến động, trade-off thời gian/token.
Bước 7: Khởi chạy Trình xem đánh giá
Tạo giao diện xem kết quả:
nohup python /path/to/skill-creator/eval-viewer/generate_review.py \
api-tester-workspace/iteration-1 \
--skill-name "api-tester" \
--benchmark api-tester-workspace/iteration-1/benchmark.json \
> /dev/null 2>&1 &
VIEWER_PID=$!
- Tab "Outputs": Xem từng case test, review, feedback.
- Tab "Benchmark": Tỷ lệ pass, thời gian, token, phân tích.
Môi trường headless: xuất HTML tĩnh với --static.
Bước 8: Đọc phản hồi và lặp lại
Khi người dùng review xong, đọc feedback.json:
{
"reviews": [
{
"run_id": "eval-0-with_skill",
"feedback": "biểu đồ thiếu nhãn trục"
}
],
"status": "complete"
}
- Ưu tiên cải tiến các case có feedback cụ thể.
- Nếu tất cả feedback trống/người dùng hài lòng, dừng vòng lặp.
Quy trình lặp:
- Cải tiến kỹ năng
- Chạy lại case test với iteration mới
- Khởi chạy viewer với
--previous-workspace - Đọc feedback mới và tiếp tục lặp
Tắt viewer khi hoàn tất:
kill $VIEWER_PID 2>/dev/null
Bước 9: Tối ưu hóa mô tả kỹ năng
Trường mô tả (description) quyết định kỹ năng có được kích hoạt đúng lúc không.
Tạo 20 truy vấn đánh giá (kích hoạt/không kích hoạt):
[
{
"query": "sếp gửi file xlsx muốn thêm cột lợi nhuận (%) từ cột C và D",
"should_trigger": true
},
{
"query": "Tạo bảng tổng hợp từ CSV và gửi email",
"should_trigger": false
}
]
Chạy tối ưu hóa:
python -m scripts.run_loop \
--eval-set /path/to/trigger-eval.json \
--skill-path /path/to/api-tester \
--model claude-sonnet-4-6 \
--max-iterations 5 \
--verbose
Sau khi tối ưu, cập nhật description trong SKILL.md với best_description.
Bước 10: Đóng gói và phân phối
Đóng gói kỹ năng thành file .skill:
python -m scripts.package_skill /path/to/api-tester
Cài đặt: Chỉ cần copy file .skill vào thư mục kỹ năng hoặc dùng lệnh cài đặt của Claude Code.
Các lỗi thường gặp khi tạo kỹ năng
- Mô tả mơ hồ: “Một kỹ năng để làm việc với API” → nên mô tả chi tiết khi nào kích hoạt, đầu ra gì.
- Hướng dẫn quá hạn chế: Tránh dùng lệnh “LUÔN LUÔN/PHẢI”. Nên giải thích lý do.
- Bỏ qua case kiểm thử: Dù chủ quan, vẫn nên chạy 2-3 ví dụ test đầu ra.
- Bỏ qua dữ liệu thời gian: Kỹ năng chậm sẽ không dùng được lâu dài.
- Không đóng gói script lặp lại: Nếu nhiều case phải viết lại script, nên đóng gói sẵn.
Ví dụ kỹ năng thực tế
Kỹ năng xây dựng MCP
- Tính năng: Mẫu Python/Node.js, khung đánh giá, best practices.
- Cấu trúc:
mcp-builder/
├── SKILL.md
├── reference/
│ ├── mcp_best_practices.md
│ ├── python_mcp_server.md
│ └── node_mcp_server.md
└── evaluation/
└── evaluation.md
Kỹ năng Docx
- Tạo tài liệu Word tự động: scripts python-docx, mẫu, hướng dẫn định dạng.
- Quy trình: Hiểu yêu cầu → chọn/tạo mẫu → sinh tài liệu → xác thực đầu ra.
Kỹ năng thiết kế UI
- Xây dựng giao diện web: thư viện component, mẫu Tailwind CSS, kiểm thử accessibility.
- Quy trình: Quy trình chính trong SKILL.md, chi tiết component trong
references/.
Kiểm tra kỹ năng của bạn với Apidog
Nếu kỹ năng liên quan API, Apidog tích hợp trực tiếp vào quy trình.
Ví dụ: Tích hợp kỹ năng kiểm tra API
## Chạy kiểm tra API
Sử dụng Apidog để kiểm thử hệ thống:
1. Nhập OpenAPI spec vào Apidog
2. Sinh case test từ spec
3. Chạy test, xuất kết quả JSON
4. Xác thực response với schema mong đợi
Custom assertion: dùng scripting của Apidog.
Đóng gói script Apidog vào skill:
api-tester/
├── SKILL.md
└── scripts/
├── run-apidog-tests.py
└── generate-report.py
Kết luận
Claude Code Skills giúp mở rộng Claude cho quy trình công việc của bạn. Quy trình tạo kỹ năng chuẩn gồm:
- Nắm bắt ý định
- Soạn SKILL.md – hướng dẫn rõ ràng, có ví dụ
- Tạo trường hợp kiểm thử – prompt thực tế
- Chạy đánh giá – song song có/không kỹ năng
- Xem xét kết quả – feedback + benchmark
- Lặp lại – cải tiến dựa trên kết quả
- Tối ưu mô tả – kích hoạt chuẩn xác
-
Đóng gói – xuất file
.skill
Câu hỏi thường gặp
Mất bao lâu để tạo một kỹ năng?
Kỹ năng đơn giản: 15-30 phút. Kỹ năng phức tạp (nhiều tệp, script) thường mất 2-3 giờ, bao gồm các lần lặp đánh giá.
Có cần viết trường hợp kiểm thử cho mọi kỹ năng không?
Không bắt buộc. Kỹ năng có đầu ra kiểm chứng được (tạo mã, chuyển đổi tệp, trích xuất dữ liệu) nên có case test. Kỹ năng chủ quan (viết lách, thiết kế) ưu tiên đánh giá định tính.
Nếu kỹ năng không kích hoạt đáng tin cậy?
Tối ưu trường mô tả, bổ sung cụm từ và ngữ cảnh kích hoạt rõ ràng. Chạy vòng lặp tối ưu hóa với 20 truy vấn đánh giá.
Làm sao chia sẻ kỹ năng với nhóm?
Đóng gói .skill bằng python -m scripts.package_skill <đường dẫn>, gửi file cho team, mọi người copy vào thư mục kỹ năng.
Kỹ năng có thể gọi API ngoài không?
Có. Đóng gói script gọi API, hướng dẫn kỹ năng cách sử dụng. Đặt API key ở biến môi trường thay vì hard-code.
Giới hạn kích thước tệp kỹ năng?
Không có giới hạn cứng, nhưng nên giữ SKILL.md dưới 500 dòng. Tài liệu chi tiết, script, asset nên tách riêng.
Làm sao cập nhật kỹ năng đã cài?
Sao chép kỹ năng ra thư mục có quyền ghi, chỉnh sửa, đóng gói lại, giữ nguyên tên gốc (trừ khi cần bản khác).
Top comments (0)