Cách tạo custom skill cho Claude Code (kèm ví dụ chạy thật) 2026

bài viết dựa trên Claude Code CLI. Skills là tính năng đang phát triển nhanh, một số chi tiết có thể đổi; mình sẽ ghi rõ nguồn ở phần cuối.

Custom skill trong Claude Code là gì? (định nghĩa nhanh)

Custom skill là một gói hướng dẫn - gồm một thư mục và file SKILL.md - dạy Claude Code làm một workflow lặp lại theo đúng cách bạn muốn. Thay vì mỗi lần lại gõ lại nguyên đoạn prompt "format bài blog theo chuẩn X, thêm mục lục, viết meta...", bạn đóng gói cách làm đó một lần thành skill. Từ đó về sau Claude Code tự nhận ra khi nào cần dùng và làm theo.

Nhiều người mới nhầm skill với hai thứ khác, nên phân biệt nhanh:

• Skill - kiến thức/quy trình mà Claude Code tự động gọi khi ngữ cảnh khớp mô tả. Bạn không phải gõ lệnh gì.
• Slash command - một lối tắt bạn chủ động gõ (ví dụ /commit). Xem chi tiết ở bài slash commands trong Claude Code.
• Subagent - một "trợ lý con" chạy tác vụ nặng trong context riêng. Xem hướng dẫn subagents.

Nếu bạn vẫn còn lẫn lộn bốn khái niệm, bài phân biệt skills, subagents, hooks, MCP mổ xẻ kỹ hơn. Còn nếu bạn chưa nắm rõ skill là gì về bản chất, đọc trước Claude Code Skills là gì rồi quay lại đây để bắt tay viết skill. Bài này tập trung 100% vào việc làm được một skill chạy thật trong Claude Code CLI.

Skill hoạt động thế nào? (progressive disclosure)

Hiểu cơ chế này thì bạn sẽ viết skill đúng ngay từ đầu. Claude Code không nhồi toàn bộ nội dung mọi skill vào context - làm vậy sẽ ngốn token và gây nhiễu. Nó dùng cơ chế progressive disclosure (nạp dần theo nhu cầu), qua ba tầng:

• Tầng 1 - luôn thường trực: Claude Code chỉ giữ name và description của mỗi skill trong context. Đây là "tấm biển" để nó biết skill nào tồn tại và dùng để làm gì.
• Tầng 2 - nạp khi khớp: chỉ khi ngữ cảnh cuộc hội thoại khớp description, phần body của SKILL.md mới được đọc vào context.
• Tầng 3 - nạp on-demand: các file phụ như reference.md hay scripts/ chỉ được mở khi Claude thật sự cần tới chúng.

Hệ quả quan trọng nhất: description chính là "công tắc" auto-invoke. Nếu mô tả không chứa đúng từ khoá ngữ cảnh mà người dùng sẽ nói, Claude Code không bao giờ mở body skill của bạn ra đọc - dù body viết hay đến mấy. Đây là lý do phần lớn skill "không chạy" thất bại ngay ở dòng description, chứ không phải ở nội dung.

Chuẩn bị: skill đặt ở đâu (personal vs project)

Đây là chỗ hầu hết bài hướng dẫn tiếng Việt bỏ qua vì họ nói về claude.ai bản web. Với Claude Code CLI, skill sống trong hệ thống file và bạn có hai vị trí đặt, chọn theo mục đích:

Nguyên tắc đơn giản: workflow của riêng bạn → để ở ~/.claude/skills/; quy ước của cả team/dự án → để ở .claude/skills/ trong repo rồi commit vào git để mọi người cùng có.

Yêu cầu duy nhất: Claude Code đã được cài (nếu chưa, xem hướng dẫn cài đặt Claude Code). Bạn có thể kiểm tra các skill hiện có bằng cách hỏi thẳng trong phiên Claude Code - ví dụ prompt "liệt kê các skill bạn đang có" - hoặc mở thư mục ~/.claude/skills/ để xem. Sau khi tạo skill mới, nhớ restart để nó được quét vào.

Cách tạo custom skill cho Claude Code trong 5 bước

Dưới đây là quy trình đầy đủ. Mình dùng ví dụ xuyên suốt là skill blog-formatter - chuẩn hoá một bài blog Markdown thô - để bạn dễ hình dung, nhưng cách làm áp dụng cho bất kỳ workflow nào.

Bước 1 - Chọn 1 workflow lặp lại

Đừng vội viết skill cho một việc bạn chưa từng làm thủ công. Mẹo thực chiến: làm tay với Claude Code vài lần cho tới khi nó ra đúng kết quả bạn muốn, rồi mới chắt lọc cái prompt/quy trình đó thành skill. Skill tốt là kết tinh của một quy trình đã được kiểm chứng, không phải phỏng đoán.

Vài ứng viên tốt để bắt đầu: format bài blog theo chuẩn của bạn, sinh commit message theo quy ước dự án, viết unit test theo mẫu sẵn có, hoặc soát lại tài liệu API. Chọn thứ bạn làm ít nhất tuần một lần - ROI mới rõ.

Bước 2 - Tạo cây thư mục + file SKILL.md

Một skill tối thiểu chỉ cần một thư mục và một file SKILL.md. Khi cần, bạn thêm file phụ. Cây thư mục đầy đủ trông như sau:

~/.claude/skills/
 blog-formatter/
 SKILL.md # bắt buộc - hướng dẫn chính
 reference.md # tuỳ chọn - chi tiết dài, nạp on-demand
 scripts/
 format.py # tuỳ chọn - script kèm theo

Tạo thư mục bằng terminal:

mkdir -p ~/.claude/skills/blog-formatter
cd ~/.claude/skills/blog-formatter

Tên thư mục nên viết kebab-case, ngắn gọn, mô tả đúng việc skill làm (blog-formatter, vn-commit-msg). Với skill nhỏ, một file SKILL.md là đủ - chỉ tách reference.md hay scripts/ khi body bắt đầu dài.

Bước 3 - Viết YAML frontmatter (name + description)

Mở SKILL.md. Trên cùng là khối YAML frontmatter đặt giữa hai dòng ---, chứa hai trường bắt buộc: name và description. Đây là phần quyết định skill có tự kích hoạt hay không, nên viết cẩn thận.

Công thức cho một description tốt: làm gì + KHI NÀO dùng + từ khoá kích hoạt mà người dùng sẽ thực sự nói ra. So sánh:

Cái bên trái mơ hồ, không có ngữ cảnh, Claude không biết khi nào nên gọi. Cái bên phải nói rõ làm gì, khi nào, và chứa đúng những cụm từ người dùng hay gõ. Viết description như thể bạn đang mô tả cho một đồng nghiệp mới biết "lúc nào thì nhờ tới tôi".

Bước 4 - Viết phần body hướng dẫn

Ngay dưới frontmatter là body Markdown - đây là quy trình Claude Code sẽ đọc và làm theo khi skill được gọi. Một body tốt nên có các mục:

• Mục đích - skill này giải quyết vấn đề gì.
• Khi nào dùng - nhắc lại ngữ cảnh (bổ trợ cho description).
• Input cần hỏi - nếu thiếu thông tin thì hỏi lại người dùng cái gì.
• Các bước - quy trình rõ ràng, đánh số.
• Tiêu chuẩn output - kết quả đúng trông ra sao.
• Lỗi cần tránh + ví dụ input/output minh hoạ.

Nguyên tắc vàng: concise is key - ngắn gọn, rõ ràng. Body phình to sẽ ngốn context và làm Claude phân tâm. Khi hướng dẫn dài (bảng tra cứu, nhiều ví dụ), hãy tách sang reference.md và trỏ tới nó trong body - nhờ progressive disclosure, file phụ chỉ nạp khi cần.

Bước 5 - Nạp lại & test skill

Claude Code quét thư mục skills lúc khởi động, nên sau khi tạo/sửa SKILL.md bạn cần restart: gõ /exit rồi mở lại phiên Claude Code. Sau đó test bằng một prompt tự nhiên khớp description - ví dụ: "Format lại bài blog trong file draft.md giúp mình". Nếu viết đúng, Claude Code sẽ tự nhận ra và gọi skill blog-formatter. Xác nhận nó đã dùng đúng skill (Claude thường báo skill nào được kích hoạt), rồi kiểm tra kết quả có đúng tiêu chuẩn bạn đặt ở Bước 4 không.

Ví dụ custom skill hoàn chỉnh (copy-paste chạy được)

Đây là một SKILL.md đầy đủ mình đã viết và dùng thật. Copy nguyên vào ~/.claude/skills/vn-commit-msg/SKILL.md, restart, rồi thử ngay:

---
name: vn-commit-msg
description: Sinh commit message theo chuẩn Conventional Commits từ các thay đổi đang staged. Dùng khi người dùng nói "viết commit", "commit message", "tạo message cho commit", hoặc trước khi commit code.
---

# Sinh commit message chuẩn Conventional Commits

## Mục đích
Đọc phần diff đang staged và viết một commit message ngắn gọn, đúng chuẩn.

## Khi nào dùng
Khi người dùng chuẩn bị commit hoặc yêu cầu viết commit message.

## Input cần hỏi
Nếu chưa có gì staged, chạy `git diff --staged` để xem thay đổi.
Nếu vẫn trống, hỏi người dùng: "Bạn đã `git add` chưa?"

## Các bước
1. Chạy `git diff --staged` để đọc thay đổi.
2. Xác định loại: feat / fix / docs / refactor / test / chore.
3. Xác định scope (module/thư mục chính bị đổi).
4. Viết dòng tiêu đề: `type(scope): mô tả ngắn` - tối đa 72 ký tự, thì hiện tại.
5. Nếu thay đổi phức tạp, thêm 1-3 gạch đầu dòng ở phần body giải thích "vì sao".

## Tiêu chuẩn output
- Tiêu đề ≤ 72 ký tự, không dấu chấm cuối.
- Mô tả bằng tiếng Việt, rõ ràng, đúng việc đã làm.
- KHÔNG bịa thay đổi không có trong diff.

## Lỗi cần tránh
- Đừng dùng type sai (thêm tính năng mà ghi `fix`).
- Đừng viết mơ hồ kiểu "update code", "sửa linh tinh".

## Ví dụ
Input diff: thêm hàm validate email ở `src/auth/`.
Output:
feat(auth): thêm validate định dạng email khi đăng ký

Kết quả thật: sau khi nạp, mình chỉ cần gõ "viết commit đi" là Claude Code chạy git diff --staged, phân loại đúng và trả về message theo chuẩn - không phải nhắc lại quy ước mỗi lần.

Một giới hạn quan sát được (trung thực): nếu diff quá lớn hoặc trộn nhiều loại thay đổi, message tổng hợp đôi khi chọn type chưa sát nhất - lúc đó vẫn nên tách commit hoặc chỉnh tay. Skill giúp nhanh 90% trường hợp, không thay hoàn toàn phán đoán của bạn.

Test & debug khi skill không trigger

Skill viết xong mà Claude Code "phớt lờ" là chuyện rất hay gặp. Đây là checklist mình chạy qua theo thứ tự khi một skill không chịu kích hoạt:

1. YAML sai cú pháp. Thiếu một dấu ---, sai thụt lề, hay ký tự lạ trong frontmatter → toàn bộ skill bị bỏ qua thầm lặng. Kiểm tra lại khối frontmatter trước tiên.
2. Description mơ hồ / thiếu từ khoá ngữ cảnh. Đây là thủ phạm số một. Nếu prompt của bạn không chứa cụm từ nào trùng với description, skill không được gọi. Thêm đúng những từ người dùng thật sẽ nói.
3. Chưa restart Claude Code. Thư mục skills chỉ được quét lúc khởi động. Sửa xong phải /exit rồi mở lại.
4. Trùng tên hoặc sai đường dẫn. Hai skill cùng name, hoặc SKILL.md đặt lệch thư mục (viết hoa/thường, sai cấp) → không nạp.
5. Body quá dài gây nhiễu. Body phình to có thể làm Claude khó bám đúng quy trình. Rút gọn, tách bớt sang reference.md.

Mẹo kiểm tra nhanh: ép gọi thủ công để tách bạch vấn đề. Prompt thẳng "Dùng skill blog-formatter để làm việc này." Nếu ép gọi mà chạy ổn → lỗi nằm ở description (không auto-invoke được). Nếu ép gọi vẫn hỏng → lỗi ở YAML hoặc đường dẫn.

Chia sẻ & publish skill

Viết được skill hay thì nên chia sẻ - và đây là phần gần như không đối thủ tiếng Việt nào nói tới. Có ba cách, từ đơn giản đến bài bản:

1. Commit vào repo cho cả team. Đặt skill ở .claude/skills/ trong dự án rồi git commit. Ai clone repo cũng có ngay skill đó - cách nhanh nhất để chuẩn hoá quy trình cho một team.
2. Đẩy lên GitHub cho cộng đồng. Tạo một repo chứa các skill, người khác clone hoặc copy thư mục skill vào ~/.claude/skills/ của họ. Kèm README mô tả mỗi skill làm gì.
3. Đóng gói thành plugin. Với nhiều skill liên quan, bạn có thể gom thành một plugin phân phối gọn gàng hơn (mình sẽ có bài riêng về Claude Code plugins).

Điểm cộng: skill dùng chuẩn mở (Markdown + YAML frontmatter), nên một file SKILL.md viết cho Claude Code thường dùng lại được hoặc chuyển đổi dễ dàng sang các công cụ khác như Cursor hay Copilot - công sức viết một lần, dùng nhiều nơi.

Không muốn tự viết? Dùng 108+ skill dựng sẵn

Tự viết skill là kỹ năng đáng học - nó cho bạn toàn quyền tuỳ biến theo đúng workflow riêng, và mình khuyên ai dùng Claude Code nghiêm túc đều nên biết. Nhưng nếu bạn muốn có ngay một bộ skill production-ready mà không phải DIY từng cái, thì Engineer Kit có 60+ skill dựng sẵn (frontend, backend, database, DevOps, code review) là lối tắt đáng cân nhắc.

Rút ngắn đường: bộ skill dựng sẵn AgentKit (giảm 20% qua link) đóng gói 108+ skill cho Claude Code - dùng được ngay thay vì tự viết từng file. Trung thực mà nói: bạn vẫn nên biết cách tự viết skill (như bài này) để tuỳ biến phần đặc thù; kit lo phần nền tảng lặp đi lặp lại.

Câu hỏi thường gặp (FAQ)

Skill khác subagent thế nào?

Skill là gói hướng dẫn được Claude Code tự nạp vào context hiện tại khi ngữ cảnh khớp, chạy trong cùng phiên. Subagent là một trợ lý con chạy tác vụ nặng trong context riêng, độc lập. Việc nhẹ, lặp lại → skill; việc lớn cần cô lập → subagent.

SKILL.md đặt ở đâu?

Đặt ở ~/.claude/skills/<tên>/SKILL.md nếu muốn dùng cho mọi dự án (personal), hoặc .claude/skills/<tên>/SKILL.md trong repo nếu muốn commit chia sẻ cho cả team (project). Mỗi skill là một thư mục riêng chứa file SKILL.md.

Sao skill của mình không tự chạy?

Thường là do description mơ hồ, thiếu từ khoá mà bạn thực sự nói trong prompt. Ngoài ra kiểm tra: YAML frontmatter có sai cú pháp không, đã restart Claude Code chưa, đường dẫn thư mục có đúng không.

Tạo/sửa skill xong có cần restart không?

Có. Claude Code chỉ quét thư mục skills lúc khởi động, nên sau khi tạo mới hoặc chỉnh SKILL.md, bạn cần /exit rồi mở lại phiên thì skill mới được nạp.

Skill viết cho Claude Code dùng chung với claude.ai được không?

Chuẩn skill (Markdown + YAML frontmatter) là mở, nên nội dung thường tái sử dụng được. Tuy nhiên cách nạp khác nhau: Claude Code dùng thư mục file cục bộ (~/.claude/skills/), còn claude.ai bản web nạp theo cách của nền tảng đó. Nên xem file SKILL.md là tài sản dùng lại được, không phải plug-and-play y hệt mọi nơi.

Có sẵn skill làm sẵn để dùng ngay không?

Có. Nếu không muốn viết từ đầu, các bộ kit như AgentKit đóng gói sẵn 108+ skill cho Claude Code theo nhiều lĩnh vực. Bạn vẫn nên biết tự viết để tuỳ biến, nhưng kit tiết kiệm được phần dựng nền lặp lại.

Kết luận + bước tiếp theo

Custom skill là cách hiệu quả nhất để "dạy" Claude Code làm việc theo đúng chuẩn của bạn mà không phải lặp lại prompt. Bắt đầu nhỏ: chọn một workflow bạn làm hằng tuần, chắt thành SKILL.md, viết description thật rõ, test rồi lặp. Đọc tiếp Claude Code Skills là gì để nắm nền tảng và slash commands trong Claude Code để kết hợp với lối tắt chủ động. Còn khi cần một bộ skill production-ready ngay thay vì viết từng cái, hãy cân nhắc một bộ kit dựng sẵn (xem hộp bên dưới).

Nguồn tham khảo: Claude Code Docs - Skills (Anthropic, cập nhật 2026) cho cấu trúc SKILL.md và cơ chế nạp. Skills là tính năng đang phát triển; chi tiết có thể thay đổi theo phiên bản.