Tạo Claude Code Skill Từ Đầu: Hướng Dẫn SKILL.md Đầy Đủ (2026)

Claude Code đã tạo ra $2,5 tỷ USD doanh thu hàng năm cho Anthropic (Anthropic Series G, tháng 2/2026). Hàng triệu developer đang dùng nó mỗi ngày. Nhưng mình nhận ra một điều: phần lớn mọi người chỉ dùng Claude Code ở mức gõ prompt rồi chờ kết quả.

Vấn đề nằm ở chỗ, bạn lặp đi lặp lại cùng một loại prompt. Viết commit message, review code, tạo PR summary, mỗi lần lại phải giải thích context từ đầu. Token cứ thế cháy. Output thì không nhất quán. Nghe quen không?

Bài viết này sẽ hướng dẫn bạn tạo Claude Code Skill từ đầu, từ file SKILL.md đầu tiên đến những kỹ thuật nâng cao như context fork và backtick injection. Nếu bạn đã đọc bài Skills là gì, đây là bước tiếp theo: thực hành tạo skill riêng cho project của bạn.

Tại Sao Cần Tạo Skill Riêng?

Theo Stack Overflow Developer Survey 2025 (n=33.662), 84% developer đang dùng AI tools trong workflow hàng ngày. Nhưng phần lớn vẫn dùng kiểu “gõ prompt, chờ kết quả”, không có chuẩn hóa. Skill riêng giải quyết chính xác vấn đề này.

Mình đã dùng Claude Code là gì suốt nhiều tháng trước khi bắt đầu viết skill. Kết quả? Mỗi lần viết blog phải paste lại cả đoạn prompt dài. Mỗi lần review code phải giải thích lại convention. Token cháy nhanh mà output vẫn không đồng nhất.

Khi chuyển sang dùng skill, mọi thứ thay đổi rõ rệt. Mình viết instructions một lần, gọi bằng /blog-write hay /review là xong. Output nhất quán hơn nhiều vì Claude đọc skill như system instructions, không phải gợi ý.

Lợi ích cụ thể khi tạo skill

Có 4 lý do chính để bạn nên tạo skill riêng ngay hôm nay:

• Tiết kiệm token: Không phải giải thích context mỗi lần. Skill được load tự động, bạn chỉ cần gọi lệnh.
• Output nhất quán: Claude đọc skill như instructions bắt buộc. Kết quả giống nhau mỗi lần chạy.
• Chia sẻ được: Commit file SKILL.md vào repo, cả team cùng dùng chung workflow.
• An toàn hơn: Dùng allowed-tools để giới hạn Claude chỉ được dùng những tools cụ thể, tránh hành vi ngoài ý muốn.

Muốn tiết kiệm token hiệu quả hơn nữa? Kết hợp skill với context fork để chạy tác vụ trong subagent riêng biệt.

SKILL.md Là Gì? Cấu Trúc File

Theo tài liệu chính thức của Anthropic, SKILL.md là file Markdown với YAML frontmatter ở đầu, chứa toàn bộ instructions mà Claude sẽ tuân theo khi skill được kích hoạt. Cấu trúc giống Jekyll frontmatter: phần YAML nằm giữa hai dấu ---, phần body là Markdown thuần.

File SKILL.md gồm hai phần rõ ràng:

1. Frontmatter (YAML): Metadata kiểm soát hành vi, bao gồm tên, mô tả, context mode, allowed tools, model override, và nhiều field khác.
2. Body (Markdown): Instructions chi tiết mà Claude sẽ đọc và thực thi. Viết bằng Markdown bình thường, hỗ trợ heading, list, code block.

Ví dụ SKILL.md tối thiểu

Đây là một skill đơn giản nhất có thể hoạt động:

---
name: hello
description: Chào hỏi bằng tiếng Việt
---

Khi user gọi skill này, trả lời bằng tiếng Việt thân thiện.
Luôn dùng giọng casual (mình/bạn).
Kèm theo một fun fact về lập trình.

Chỉ cần 2 fields trong frontmatter (name và description) là skill đã chạy được. Lưu file này vào .claude/skills/hello/SKILL.md, gọi bằng /hello. Đơn giản vậy thôi.

Cấu trúc thư mục skill

Mỗi skill nằm trong thư mục riêng. Ngoài file SKILL.md, bạn có thể thêm các thư mục con:

.claude/skills/my-skill/
├── SKILL.md          # File chính (bắt buộc)
├── references/       # Tài liệu tham khảo Claude đọc khi cần
├── scripts/          # Scripts thực thi (bash, python, v.v.)
├── assets/           # Templates, config files
└── examples/         # Ví dụ input/output mẫu

Thư mục references/ đặc biệt hữu ích. Claude sẽ đọc các file trong đây khi cần context thêm. Ví dụ, bạn có thể đặt coding standards, API docs, hoặc brand guidelines vào đây.

15 Frontmatter Fields Gồm Những Gì?

Theo Claude Code Docs, SKILL.md hỗ trợ 15 frontmatter fields. Chỉ name là gần như bắt buộc (nếu không khai báo thì lấy tên thư mục). Tất cả các fields còn lại đều optional nhưng rất mạnh khi cần kiểm soát chi tiết.

Bảng dưới đây liệt kê đầy đủ 15 fields. Mình chia thành 3 nhóm: Cơ bản, Kiểm soát hành vi, và Nâng cao.

Không cần nhớ hết 15 fields. Phần lớn skills chỉ cần 3-4 fields: name, description, context, và có thể allowed-tools. Bạn thêm dần khi cần kiểm soát chi tiết hơn.

Làm Sao Tạo Skill Đầu Tiên Trong 5 Phút?

Theo Anthropic Best Practices, description field là yếu tố quan trọng nhất quyết định hiệu quả của skill. Bạn chỉ cần 5 phút để tạo skill đầu tiên hoạt động. Dưới đây là quy trình từng bước.

Bước 1: Tạo thư mục

Mở terminal trong project của bạn và chạy:

mkdir -p .claude/skills/commit-msg

Tên thư mục nên dùng lowercase và hyphens. Đây cũng sẽ là tên slash command (/commit-msg) nếu bạn không khai báo field name.

Bước 2: Viết SKILL.md

Tạo file .claude/skills/commit-msg/SKILL.md với nội dung:

---
name: commit-msg
description: Tạo conventional commit message từ staged changes
argument-hint: <optional: scope>
allowed-tools:
  - Bash(git diff --staged)
  - Bash(git log --oneline -5)
---

## Quy tắc

1. Đọc staged changes bằng `git diff --staged`
2. Phân tích thay đổi, xác định type:
   - feat: tính năng mới
   - fix: sửa lỗi
   - docs: cập nhật docs
   - refactor: refactor code
   - chore: việc vặt (config, deps)
3. Viết commit message theo format:
   ```
   type(scope): mô tả ngắn gọn

   - Chi tiết thay đổi 1
   - Chi tiết thay đổi 2
   ```
4. Scope lấy từ argument hoặc tự xác định từ files changed
5. Mô tả bằng tiếng Anh, viết thường, không dấu chấm cuối
6. Body bullets tối đa 5 dòng

Bước 3: Kiểm tra skill

Mở Claude Code trong project, gõ / rồi xem skill commit-msg có hiện trong menu không. Nếu có, gõ /commit-msg để test. Claude sẽ đọc staged changes và tạo commit message theo đúng format bạn đã định nghĩa.

Bước 4: Tinh chỉnh description

Field description cực kỳ quan trọng. Nó quyết định khi nào Claude tự động kích hoạt skill (nếu disable-model-invocation không phải true). Viết description rõ ràng, cụ thể. Tránh viết chung chung kiểu “skill hữu ích cho developer”.

Ví dụ description tốt: “Tạo conventional commit message từ staged changes, phân tích diff và xác định type/scope tự động.” Ví dụ description tệ: “Giúp viết commit message.” Sự khác biệt nằm ở mức độ cụ thể.

3 Ví Dụ Thực Tế: /commit, /deploy, /pr-summary

Theo Pragmatic Engineer Survey 2026 (n=906), 46% developer chọn Claude Code là AI coding tool yêu thích nhất. Dưới đây là 3 skill thực tế mà mình dùng hàng ngày. Bạn có thể copy và điều chỉnh cho project của mình.

Ví dụ 1: /commit (cải tiến)

Đây là phiên bản nâng cao hơn ví dụ ở trên, thêm context fork để không làm “bẩn” conversation chính:

---
name: commit
description: Tạo conventional commit từ staged changes và tự commit
context: fork
allowed-tools:
  - Bash(git diff --staged)
  - Bash(git log --oneline -10)
  - Bash(git commit -m *)
---

## Instructions

1. Chạy `git diff --staged` để xem thay đổi
2. Nếu không có staged changes, thông báo user cần `git add` trước
3. Phân tích diff, xác định type và scope
4. Tạo commit message theo Conventional Commits
5. Hiện message cho user review
6. Sau khi user đồng ý, chạy `git commit -m "message"`

## Format
```
type(scope): description

- bullet 1
- bullet 2
```

## Rules
- Type: feat, fix, docs, refactor, test, chore, ci
- Description: tiếng Anh, lowercase, không dấu chấm cuối, max 72 chars
- Body: tối đa 5 bullets, mỗi bullet max 100 chars

Để ý context: fork. Skill này chạy trong sub-agent riêng biệt, không ảnh hưởng đến conversation chính. Kết quả trả về là commit message đã format, conversation chính vẫn sạch.

Ví dụ 2: /deploy

---
name: deploy
description: Deploy project lên staging hoặc production qua SSH
argument-hint: <staging|production>
context: fork
disable-model-invocation: true
allowed-tools:
  - Bash(ssh *)
  - Bash(git push *)
  - Bash(docker compose *)
---

## Instructions

1. Xác định environment từ argument (staging hoặc production)
2. Nếu production, yêu cầu user confirm 2 lần
3. Chạy checklist:
   - [ ] Tests pass?
   - [ ] Commit mới nhất đã push?
   - [ ] Không có uncommitted changes?
4. SSH vào server, pull code, restart services
5. Kiểm tra health check
6. Báo cáo kết quả

## Safety
- KHÔNG BAO GIỜ deploy production mà không có user confirmation
- Luôn chạy health check sau deploy
- Nếu health check fail, tự động rollback

Skill /deploy dùng disable-model-invocation: true. Nghĩa là Claude không bao giờ tự gọi skill này. Chỉ user gõ /deploy staging hoặc /deploy production mới kích hoạt. Đây là biện pháp an toàn cho tác vụ nhạy cảm.

Ví dụ 3: /pr-summary

---
name: pr-summary
description: Tạo PR description từ commits và diff so với main branch
context: fork
allowed-tools:
  - Bash(git log *)
  - Bash(git diff *)
---

## Instructions

1. Chạy `git log main..HEAD --oneline` để lấy danh sách commits
2. Chạy `git diff main..HEAD --stat` để xem files changed
3. Tạo PR description theo template:

## What
[Mô tả ngắn gọn thay đổi, 1-2 câu]

## Why
[Lý do thay đổi, context cho reviewer]

## Changes
- [Liệt kê thay đổi chính, nhóm theo module]

## Testing
- [Các bước test đã thực hiện]

## Notes
- [Breaking changes, migration cần thiết, v.v.]

Cả 3 skill đều dùng context: fork. Mình khuyên bạn nên dùng fork cho hầu hết skills, trừ khi bạn cần skill đọc và ghi vào conversation chính (ví dụ skill review code inline).

Skill Nâng Cao: Context Fork Và Backtick Injection Là Gì?

Theo Claude Code Docs, context fork chạy skill trong một subagent hoàn toàn tách biệt, giữ cho conversation chính không bị nhiễm context. Đây là 3 kỹ thuật nâng cao mà hầu hết developer bỏ qua.

Context fork vs shared

Đây là quyết định quan trọng nhất khi tạo skill. Hai options:

• shared (mặc định): Skill chạy trong conversation chính. Claude thấy toàn bộ history và output của skill cũng nằm trong history. Phù hợp cho skills cần đọc context hiện tại.
• fork: Skill chạy trong subagent riêng. Conversation chính chỉ nhận kết quả cuối cùng. Token tiết kiệm hơn, context sạch hơn.

Khi nào dùng fork? Khi skill không cần biết conversation trước đó. Ví dụ: tạo commit message, generate docs, run tests. Khi nào dùng shared? Khi skill cần đọc context hiện tại. Ví dụ: review code đang được thảo luận, tiếp tục refactor từ bước trước.

Backtick injection là gì?

Đây là tính năng ít người biết nhưng cực kỳ mạnh. Cú pháp !`command` trong body của SKILL.md cho phép chạy shell command trước khi gửi instructions cho Claude. Kết quả command được “inject” vào context.

---
name: review-recent
description: Review các thay đổi gần đây trong repo
---

## Context tự động

Files thay đổi gần đây:
!`git log --oneline -5`

Branch hiện tại:
!`git branch --show-current`

## Instructions
Dựa trên context ở trên, review các thay đổi.
Tập trung vào: bugs tiềm ẩn, security issues, performance.

Khi Claude load skill này, nó sẽ chạy git log --oneline -5 và git branch --show-current trước. Output thực tế được inject vào vị trí của backtick commands. Claude nhận được instructions kèm data thật, không cần chạy thêm tool calls.

Bạn tiết kiệm được ít nhất 1-2 tool calls mỗi lần chạy skill. Nghe ít nhưng nhân lên hàng trăm lần chạy mỗi ngày thì đáng kể. Muốn tìm hiểu thêm về /loop và automation? Đó cũng là một bundled skill rất hữu ích.

Model override khi nào cần?

Field model cho phép chọn model khác cho skill cụ thể. Ví dụ, bạn đang dùng Opus cho conversation chính nhưng muốn skill đơn giản (tạo commit message) chạy trên Sonnet để tiết kiệm cost.

---
name: quick-commit
description: Tạo commit message nhanh (dùng Sonnet cho tiết kiệm)
model: claude-sonnet-4-20250514
context: fork
effort: low
---

Tạo conventional commit message từ staged changes.
Ngắn gọn, không cần phân tích sâu.

Kết hợp model + effort: low + context: fork tạo ra skill cực kỳ tiết kiệm token. Phù hợp cho các tác vụ đơn giản, lặp lại nhiều lần trong ngày.

Skill Ở Đâu? Personal vs Project vs Enterprise

Theo Claude Code Docs, skills được load theo thứ tự ưu tiên: Enterprise > Personal > Project. Hiểu đúng hệ thống scope giúp bạn tổ chức skills hợp lý, tránh xung đột.

3 cấp độ scope

Cách mình tổ chức: Personal skills cho workflow cá nhân (viết blog, quản lý git). Project skills cho team conventions (coding standards, deploy process). Enterprise skills thường do admin thiết lập.

Khi nào skill bị xung đột?

Nếu hai skill cùng tên ở hai scope khác nhau, scope cao hơn thắng. Enterprise > Personal > Project. Ví dụ, nếu enterprise có skill /review và project cũng có /review, bản enterprise sẽ được dùng.

Để tránh xung đột, mình khuyên bạn đặt prefix cho project skills. Thay vì /review, đặt /proj-review hoặc /myapp-review. Personal skills thì dùng prefix cá nhân hoặc tên riêng.

Làm Sao Testing Và Debugging Skill?

Theo Anthropic Best Practices, một trong những lỗi phổ biến nhất là viết description quá chung chung khiến Claude kích hoạt sai skill. Testing kỹ trước khi dùng thật là bắt buộc.

Checklist testing skill

Mỗi khi tạo skill mới, mình chạy qua 5 bước này:

1. Kiểm tra cú pháp YAML: Frontmatter phải nằm giữa hai dấu ---. YAML sai cú pháp sẽ khiến skill không load.
2. Kiểm tra /menu: Gõ / trong Claude Code, xem skill có hiện không. Nếu không, kiểm tra đường dẫn file.
3. Test gọi thủ công: Gõ /ten-skill với input đơn giản. Xem output có đúng format không.
4. Test auto-trigger: Nếu disable-model-invocation là false, thử mô tả tác vụ bằng lời. Xem Claude có tự gọi skill không.
5. Test edge cases: Gọi skill khi không có data (ví dụ, không có staged changes cho /commit). Skill nên xử lý gracefully.

Lỗi thường gặp và cách sửa

Mẹo debug nhanh: nếu skill chạy không đúng, thêm dòng “Trước khi thực thi, in ra toàn bộ frontmatter bạn đang đọc” vào body. Claude sẽ liệt kê, bạn thấy ngay nó đọc được gì.

Skill vs CLAUDE.md vs Hook: Khi Nào Dùng Gì?

Đây là câu hỏi mình nhận được nhiều nhất. Theo Claude Code Docs, mỗi hệ thống phục vụ mục đích khác nhau. Dùng sai công cụ sẽ gây lãng phí token hoặc mất kiểm soát. Bạn có thể đọc bài so sánh Skills vs Hooks chi tiết hơn.

Quy tắc ngón tay cái: Nếu Claude cần biết thông tin đó, dùng CLAUDE.md hoặc Skill. Nếu Claude không cần biết nhưng bạn muốn enforce rule, dùng Hook. Hook chạy bên ngoài model, Claude không bao giờ nhìn thấy.

Kết hợp cả 3 như thế nào?

Trong thực tế, bạn dùng cả 3 cùng lúc. CLAUDE.md chứa project rules chung (coding conventions, tech stack). Skills chứa task-specific instructions (/commit, /review). Hooks enforce rules cứng (auto-lint, block dangerous commands).

Ví dụ: CLAUDE.md nói “dùng TypeScript strict mode”. Skill /review kiểm tra code có tuân theo conventions không. Hook chạy eslint --fix tự động sau mỗi file write. Ba tầng bổ sung cho nhau, không thay thế nhau.

Agent Skills: Chuẩn Mở Hoạt Động Thế Nào?

Ngoài Claude Code, format SKILL.md đang trở thành chuẩn mở qua dự án Agent Skills (agentskills.io). Mục tiêu là tạo một định dạng skill file tương thích cross-tool: viết một lần, dùng được trên Claude Code, Cursor, Windsurf, và các AI coding tools khác.

Đây là hướng đi đáng chú ý. Nếu bạn đầu tư thời gian viết skills hôm nay, chúng có thể portable sang tools khác trong tương lai. Open standard nghĩa là không bị lock-in vào một vendor duy nhất.

Hiện tại, Agent Skills specification vẫn đang phát triển. Nhưng việc viết skills theo chuẩn SKILL.md của Claude Code đã tương thích sẵn rồi, vì Claude Code chính là một trong những tools đầu tiên implement specification này.

Bundled Skills Có Sẵn Gồm Những Gì?

Claude Code đi kèm 5 bundled skills mà bạn có thể dùng ngay. Theo tài liệu chính thức, đây là những skills được Anthropic xây dựng sẵn và tối ưu cho các tác vụ phổ biến nhất.

• /batch: Xử lý nhiều files cùng lúc theo pattern. Ví dụ: refactor tên biến trong 50 files.
• /claude-api: Gọi Claude API trực tiếp từ trong conversation.
• /debug: Phân tích và sửa lỗi có hệ thống. Claude tự đọc error logs, stack traces.
• /loop: Chạy lặp một tác vụ cho đến khi đạt điều kiện dừng.
• /simplify: Đơn giản hóa code phức tạp, giữ nguyên chức năng.

Mình khuyên bạn thử dùng 5 skills này trước khi tạo skill riêng. Chúng là ví dụ tốt để học cách viết instructions hiệu quả. Xem source code của bundled skills cũng giúp bạn hiểu best practices.

Sau khi tạo xong skill, bước tiếp theo là đo và cải tiến. Đây là nơi AutoResearch Claude Code phát huy tác dụng: nó chạy benchmark tự động, thử các prompt biến thể, và chỉ giữ phiên bản thắng baseline. Bạn sẽ không phải đoán xem edit skill có thực sự tốt hơn không.

Câu Hỏi Thường Gặp

SKILL.md khác gì file Commands (.md) trong .claude/commands/?

Skills thay thế Commands từ tháng 1/2026 (Claude Code Docs). Skills mạnh hơn nhiều: hỗ trợ YAML frontmatter, context fork, allowed-tools, model override, và auto-trigger dựa trên description. Nếu bạn đang dùng .claude/commands/, nên chuyển sang .claude/skills/ sớm. Cú pháp tương tự, chỉ thêm frontmatter và đổi đường dẫn.

Skill có thể gọi skill khác không?

Có. Claude có thể tự kích hoạt skill dựa trên description (trừ khi disable-model-invocation: true). Bạn cũng có thể viết trong body: “Sau bước 3, gọi skill /review.” Claude sẽ tìm và gọi slash command tương ứng. Tuy nhiên, tránh tạo chain quá dài vì sẽ tốn nhiều token.

Skill có an toàn không? Claude có thể phá gì?

Skills mang tính advisory. Claude “nên” tuân theo nhưng không bị ép buộc 100%. Để kiểm soát tuyệt đối, dùng allowed-tools giới hạn tools Claude được phép sử dụng. Kết hợp với Hooks để enforce rules cứng bên ngoài model. Đây là cách tiếp cận defense-in-depth.

Tạo bao nhiêu skills là vừa đủ?

Không có giới hạn kỹ thuật. Nhưng mình khuyên bắt đầu với 3-5 skills cho các tác vụ lặp lại nhiều nhất. Thêm dần khi cần. Quá nhiều skills với description chung chung sẽ khiến Claude nhầm lẫn khi auto-trigger. Chất lượng quan trọng hơn số lượng.

Personal skills có bị team members thấy không?

Không. Personal skills nằm ở ~/.claude/skills/ trên máy bạn, không commit vào repo. Chỉ bạn thấy, dùng được ở mọi project. Project skills (.claude/skills/) mới được commit và cả team thấy. Chọn đúng scope tùy mục đích.

Có thể dùng SKILL.md cho Agent Skills (agentskills.io) không?

Có. Agent Skills (agentskills.io) là chuẩn mở dựa trên format SKILL.md. File skill viết cho Claude Code tương thích sẵn. Tuy nhiên, một số fields nâng cao (context fork, model override) có thể chưa được tools khác hỗ trợ. Kiểm tra compatibility trước khi cross-tool.

Làm sao chia sẻ skills với cộng đồng?

Commit thư mục skill vào public repo trên GitHub. Người khác chỉ cần clone hoặc copy vào .claude/skills/ là dùng được. Hiện tại chưa có marketplace chính thức, nhưng cộng đồng đang xây dựng. Bạn cũng có thể đóng gói thành npm package nếu muốn versioning.

Kết Luận

Tạo Claude Code Skill không khó. Bạn chỉ cần một file SKILL.md với frontmatter đơn giản và instructions rõ ràng. Bắt đầu từ skill cơ bản (3-4 fields), dùng thật, rồi thêm dần các kỹ thuật nâng cao như context fork và backtick injection. Ví dụ thực tế: excalidraw-diagram skill chỉ cần SKILL.md + references/ là tự vẽ được architecture diagram. Xem thêm bài top skills tốt nhất để tham khảo cách các skill phổ biến được xây dựng.

Điểm mấu chốt cần nhớ: description quyết định khi nào Claude tự trigger skill. context fork giữ conversation sạch. allowed-tools kiểm soát những gì Claude được phép làm. Ba yếu tố này chiếm 80% hiệu quả của một skill tốt.

Nếu bạn mới bắt đầu, hãy tạo skill /commit từ ví dụ trong bài này. Dùng thử vài ngày, cảm nhận sự khác biệt. Sau đó, viết thêm 2-3 skills cho các tác vụ bạn lặp lại nhiều nhất. Chỉ cần vậy là workflow của bạn đã khác rồi.

Muốn xem ví dụ skill thực tế phức tạp với 8 sub-skills và scoring system? Xem bài claude-github — skill tối ưu GitHub repo, chạm điểm 0-100 trên 6 danh mục. Đây là ví dụ tốt nhất về cách thiết kế skill chuyên biệt.

Muốn hiểu sâu hơn về hệ sinh thái Claude Code? Đọc tiếp bài CLAUDE.md để nắm project-level instructions, hoặc bài Hooks để học cách enforce rules bên ngoài model. Khi đã thành thạo skill, bước tiếp theo là kết hợp Skills với Sub-Agents để biến skill đơn lẻ thành pipeline tự động hóa. Đọc thêm lộ trình 6 levels Claude Code để biết bạn đang ở đâu và nên học gì tiếp theo.