Tạo Custom Skill cho Claude Code: Hướng dẫn SKILL.md từ A đến Z

Hướng dẫn tạo custom skill Claude Code từ A-Z: Từ YAML frontmatter đến auto-invoke workflow. Tự động hóa test, deploy và PR chỉ với file SKILL.md đơn giản.

Định nghĩa

Custom Skill trong Claude Code là file SKILL.md đặt tại thư mục .claude/skills/, kết hợp YAML frontmatter và Markdown body. Nó đóng vai trò như một "bộ định tuyến thông minh" — cho phép Claude tự động kích hoạt workflow dựa trên ngữ nghĩa cuộc hội thoại, thay vì bắt bạn phải nhớ đúng cú pháp lệnh.

Giải thích chi tiết

Progressive Disclosure: Tiết kiệm context window bằng 4 cấp độ nạp thông tin

Skill sử dụng kiến trúc progressive disclosure (tiết lộ dần dần) để tối ưu tài nguyên context window — vốn đắt đỏ với AI agent:

Level 1 (Metadata): YAML frontmatter (name, description) luôn được load (~100 tokens). Đây như "mặt sau của sách" để Claude quyết định có nên mở skill hay không.
Level 2 (Instructions): Markdown body chỉ load khi skill được trigger (< 5k tokens). Chứa workflow, guardrails, và logic xử lý.
Level 3 (References): REFERENCE.md, GUIDELINES.md được tham chiếu on-demand qua bash commands, không chiếm token cho đến khi cần.
Level 4 (Scripts): File Python/JS thực thi deterministic operations được gọi qua subprocess, hoàn toàn nằm ngoài context window.

YAML Frontmatter: "Thẻ thư viện" quyết định khi nào kích hoạt

Frontmatter là phần quan trọng nhất vì nó quyết định khi nào skill chạy:

---
name: test-automation
description: Tự động phát hiện và chạy test liên quan đến code vừa thay đổi. Dùng khi user yêu cầu kiểm tra, test, hoặc validate code.
autoInvoke: 
  - "test this"
  - "check if it works"
version: 1.0.0
---

Quy tắc vàng: description tối đa 200 ký tự và là điều kiện if viết bằng ngôn ngữ tự nhiên. Claude sử dụng embedding similarity để so sánh description với intent của bạn. Nếu description quá chung chung ("handle files"), skill sẽ không bao giờ trigger đúng lúc. Nếu quá cụ thể ("dùng cho file React trong thư mục src/components"), skill sẽ bị bỏ sót khi cần.

Body: Nơi định nghĩa workflow chi tiết

Phần Markdown sau frontmatter chứa:

Workflow steps: Các bước thực hiện theo thứ tự
Guardrails: Giới hạn không được vượt qua (ví dụ: "Không chạy test trên production database")
Decision trees: Logic rẽ nhánh nếu gặp tình huống đặc biệt

Scripts và Templates: Tách biệt suy luận và thực thi

Thay vì nhét code Python vào context window (tốn token và rủi ro hallucination), skill gọi scripts qua bash:

## Execution
Run: `python .claude/skills/test-automation/run_tests.py --changed-files [files]`

Templates (Jinja2) xử lý phần "mơ hồ" — chuyển natural language thành structured parameters — còn scripts xử lý phần deterministic.

Ví dụ thực tế

Skill `/test` cho dự án fintech tích hợp VietQR

Tình huống: Bạn đang sửa API tích hợp thanh toán VietQR cho startup ở TP.HCM, vừa thay đổi file vietqr-gateway.js và cần đảm bảo không làm hỏng flow quét mã.

File .claude/skills/vietqr-test/SKILL.md:

---
name: vietqr-test
description: Phát hiện file thay đổi liên quan đến thanh toán VietQR, tự động chạy unit test cho payment gateway và kiểm tra regex validate mã QR theo chuẩn NAPAS. Dùng khi user nói "test payment", "kiểm tra VietQR", hoặc "chạy test thanh toán".
autoInvoke: 
  - "test payment"
  - "kiểm tra VietQR"
  - "test code vừa sửa"
---

Body chứa logic: Tìm file test tương ứng trong tests/payment/ → Chạy jest vietqr-gateway.test.js → Kiểm tra kết quả validate mã QR (đúng format 9704 + số tài khoản) → Báo cáo coverage.

Skill `/deploy` lên VPS staging tại Việt Nam

Tình huống: Team 5 người ở Hà Nội cần deploy nhanh lên server staging (VPS Vultr Singapore hoặc máy chủ VNPT) sau khi commit feature mới.

File .claude/skills/deploy-vn/SKILL.md:

---
name: deploy-staging-vn
description: Build Docker image cho Node.js app, chạy security scan cơ bản với Trivy, và deploy lên VPS staging qua SSH. Chỉ chạy khi user explicitly yêu cầu "deploy staging" hoặc "lên test server".
autoInvoke: []
---

Body chứa checklist: docker build -t app:staging-$(git rev-parse --short HEAD) . → trivy image app:staging → docker save → ssh deploy@staging-vn "docker load && docker-compose up -d" → Kiểm tra health check endpoint /health.

Skill `/release` chuẩn hóa Merge Request cho team

Tình huống: Team sử dụng GitLab (phổ biến ở các công ty Việt Nam) và cần tạo MR với đúng format, link đến Jira ticket dạng VIETQR-123.

Skill tự động: Parse tên branch hiện tại → Tạo branch mới theo pattern feature/VIETQR-123-mo-ta-ngan → Viết commit message theo conventional commits → Generate MR template với checklist pre-filled (đã chạy test chưa, đã update API docs chưa) → Mở trình duyệt để review trên GitLab.

Ứng dụng

Developer cá nhân / Freelancer

Tự động hóa "nghi thức" lặp đi lặp lại khi làm dự án outsource cho khách hàng Việt Nam: format code theo chuẩn ESLint AirBnB, tạo boilerplate cho component React mới theo cấu trúc dự án, hoặc chạy lint + type check trước khi commit. Giảm 5-10 phút context switching mỗi lần chuyển task.

Tech Lead tại startup 5-10 người

Encode "tribal knowledge" thành executable documentation. Thay vì viết Notion "Làm thế nào để release lên production", tạo skill /release mà mọi thành viên dùng được nhất quán. Đảm bảo junior dev không bỏ sót bước quan trọng như quên bump version trong package.json hoặc quên chạy script migrate database.

DevOps / Platform Engineer ngân hàng/fintech

Tạo skill tích hợp với CI/CD pipelines — không phải thay thế Jenkins/GitLab CI, mà là "local pre-flight check" để bắt lỗi sớm trước khi push lên repo nội bộ. Ví dụ: skill /precommit chạy unit test chỉ cho file staged, tiết kiệm thời gian so với chạy full suite trên toàn bộ codebase lớn.

So sánh

Đặc điểm	Custom Skill	MCP (Model Context Protocol)	Slash Command truyền thống
Kích thước	Single file SKILL.md (~1-5KB)	External server process	Single file markdown
Kích hoạt	Auto-invoke qua semantic matching	Tool calling qua JSON-RPC	Manual (`/command`)
Capability	Prompt-based workflow + local scripts	Kết nối external APIs, databases	Prompt template đơn giản
Context	Progressive disclosure, lazy loading	Real-time query, không tốn token lưu trữ	Load toàn bộ khi gọi
Ví dụ	`/test`, `/deploy`, `/release`	Query PostgreSQL, đọc Slack, dùng GitHub API	`/commit`, `/fix`

Insight then chốt: Skill là "bộ não" biết khi nào và làm gì với context nội bộ, còn MCP là "đôi tay" với ngoại vi — kết nối ra thế giới bên ngoài. Skill giải quyết bài toán "tự động hóa workflow có điều kiện", MCP giải quyết "lấy dữ liệu từ bên ngoài". Đừng dùng skill để thay thế MCP khi cần query database — nhưng cũng đừng dùng MCP để chạy lệnh bash đơn giản khi skill đủ dùng.