Claude Code skill là các file Markdown theo yêu cầu, dạy Claude một quy trình có thể tái sử dụng — định dạng commit message, rubric review code, giao thức debug. Khác với CLAUDE.md — thứ luôn được tải vào mỗi phiên dù bạn cần hay không — một skill chỉ được tải khi được gọi. Bạn viết file, đặt vào đúng thư mục, và từ đó trở đi /tên-skill sẽ tải hướng dẫn của bạn vào phiên làm việc.

Tutorial này xây dựng một skill thực từ đầu: skill commit-message giúp tạo Conventional Commits từ staged diff. Kết thúc bài, bạn sẽ có một skill được cài đặt, có thể kiểm thử qua slash command, debug được khi nó hoạt động sai, và — nếu muốn — đóng gói thành plugin cho cả team cài bằng một lệnh.

Dành cho ai

Các lập trình viên đã dùng Claude Code và thấy mình lặp đi lặp lại cùng một prompt — “viết commit message theo format của mình,” “review diff này theo naming convention của team,” “dùng pattern error-handling từ style guide.” Nếu vòng lặp đó nghe quen, skill chính là giải pháp. Bạn cần nắm được căn bản Claude Code. Không cần hiểu internals.

Claude Code skill là gì

Skill là một file SKILL.md với YAML frontmatter. Khi Claude Code khởi động phiên làm việc, nó tải name và description của mỗi skill đã cài vào system prompt. Bảng index đó là cách Claude quyết định khi nào nên tự động gọi một skill. Toàn bộ nội dung SKILL.md chỉ được tải khi skill thực sự được kích hoạt — hoặc do Claude thấy description khớp với task, hoặc do bạn gọi trực tiếp bằng /tên-skill.

So sánh với CLAUDE.md:

	`CLAUDE.md`	Skills
Khi nào tải	Mỗi phiên, luôn luôn	Theo yêu cầu — chỉ khi được kích hoạt
Mục đích chính	Thiết lập mặc định và giới hạn cho toàn project	Hướng dẫn quy trình có thể tái sử dụng
Phạm vi	Áp dụng cho mọi message	Được gọi cho một task cụ thể

Sự khác biệt này quan trọng về mặt chi phí context. Một CLAUDE.md 400 dòng tiêu tốn token ở mỗi message trong mọi phiên. Một skill 400 dòng không tốn gì cho đến khi được gọi. Với tài liệu quy trình nặng — review rubric, release checklist, debugging protocol nhiều bước — mô hình theo yêu cầu mới là lựa chọn đúng.

Cấu trúc của một file skill

Một skill tối giản hợp lệ:

---
name: commit-message
description: Generates conventional commit messages by analyzing staged git diffs. Use when the user asks for help writing a commit message or reviewing staged changes.
---

# Conventional Commit Messages

1. Run `git diff --staged` to read what's staged.
2. Write the commit in this format: `<type>(<scope>): <short description>`
3. Types: feat, fix, refactor, docs, test, chore, style, perf

Trường name

Tên thư mục mới là key để gọi skill — gõ /commit-message và Claude tải skill trong thư mục tên commit-message. Trường name: là tùy chọn: nó đặt nhãn hiển thị trong menu và danh sách, mặc định là tên thư mục nếu bỏ qua. Chỉ dùng chữ cái, số và dấu gạch ngang trong tên thư mục; dấu cách và ký tự đặc biệt làm hỏng việc gọi skill.

Trường description

Đây là phần quan trọng nhất của file skill, và cũng là phần mà tác giả hay mắc lỗi nhất.

Khi bắt đầu phiên, Claude đọc description của mọi skill đã cài để xây dựng bảng index về khi nào nên gọi cái nào. Claude đưa ra quyết định tự động từ bảng index này — nội dung đầy đủ không được tải cho đến sau khi quyết định. Description mơ hồ ("Helps with commits") không bao giờ khớp với gì. Description cụ thể ("Generates conventional commit messages by analyzing staged git diffs. Use when the user asks for help writing a commit message") kích hoạt đúng lúc.

Hai nguyên tắc cho description:

Viết ở ngôi thứ ba. Description được inject vào system prompt nguyên văn. Ngôi thứ nhất ("I can help you...") làm hỏng framing. Dạng chuẩn: "Does X. Use when..." — skill làm gì cộng với khi nào kích hoạt.
Đừng tóm tắt workflow trong description. Nếu description nói “runs two review passes,” Claude có thể coi đó là toàn bộ hướng dẫn và bỏ qua phần body. Description chỉ là điều kiện kích hoạt, không phải tóm tắt quy trình.

Thẻ command-name

Skill có thể dùng thẻ HTML-comment kiểu <command-name> trong body để đánh dấu điểm kích hoạt. Khi Claude Code tải một skill, nó tìm thẻ này để xác nhận skill đã tải đúng. Một số skill dùng thẻ này để expose hành vi có điều kiện — ví dụ <SUBAGENT-STOP> trong skill using-superpowers của Superpowers nói với Claude bỏ qua body khi đang chạy như subagent chứ không phải phiên tương tác. Skill cơ bản không cần thứ này, nhưng biết ý nghĩa của nó khi gặp trong skill production là cần thiết.

Kích thước file

Giữ SKILL.md dưới 500 dòng. Toàn bộ file được tải vào context mỗi lần gọi. Tài liệu tham khảo nặng — bảng lớn, ví dụ mở rộng, rubric ngoài — thuộc về file riêng mà SKILL.md link tới. Claude chỉ tải những file bổ sung đó khi body có tham chiếu rõ ràng đến chúng.

Viết skill đầu tiên của bạn

Bước 1: Tạo cấu trúc thư mục

mkdir -p ~/.claude/skills/commit-message
touch ~/.claude/skills/commit-message/SKILL.md

Skill sống trong thư mục con, không phải file phẳng. ~/.claude/skills/commit-message.md không hoạt động — thư mục con là bắt buộc và bị bỏ qua lặng lẽ nếu thiếu.

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

Mở ~/.claude/skills/commit-message/SKILL.md và dán vào:

---
name: commit-message
description: Generates conventional commit messages by analyzing staged git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
---

# Conventional Commit Messages

## Quick start

1. Run `git diff --staged` to read what's staged.
2. Write the commit message in this format:

```
<type>(<scope>): <short description>

<optional body: why this change, not what it does>
```

**Types**: feat, fix, refactor, docs, test, chore, style, perf

## Examples

```
feat(auth): add JWT refresh token rotation
fix(api): handle null response from upstream service
chore: upgrade lodash to 4.17.21
docs(readme): add local dev prerequisites
```

## Rules

- Subject line tối đa 72 ký tự.
- Scope là module, package, hoặc subsystem đang được thay đổi. Bỏ qua khi thay đổi là cross-cutting.
- Body là tùy chọn. Chỉ dùng khi *lý do* không rõ ràng từ diff.
- Không dấu chấm cuối subject line.
- Breaking changes: thêm `!` sau type/scope và thêm footer `BREAKING CHANGE:`.

Bước 3: Kiểm tra cấu trúc

ls -la ~/.claude/skills/commit-message/

Kết quả mong đợi:

total 8
drwxr-xr-x  3 you  staff   96 May 14 09:00 .
drwxr-xr-x  5 you  staff  160 May 14 09:00 ..
-rw-r--r--  1 you  staff  612 May 14 09:00 SKILL.md

Cài đặt và gọi skill

Personal skill trong ~/.claude/skills/ có sẵn ngay trong mọi phiên Claude Code mới — không cần lệnh install nào. Bắt đầu phiên mới là skill đã sẵn sàng.

Ba cách gọi:

Cách 1: Slash command trong terminal

/commit-message

Claude tải body của SKILL.md và thực thi trong phiên hiện tại. Cách này luôn hoạt động bất kể auto-trigger có bắn hay không.

Cách 2: Ngôn ngữ tự nhiên (auto-trigger)

Vì description được tải lúc bắt đầu phiên, Claude có thể tự kích hoạt skill khi message của bạn khớp với điều kiện trigger. Nếu bạn gõ “viết commit message cho các staged changes này,” Claude tự gọi /commit-message — bạn không cần gõ slash command.

Auto-trigger có bắn hay không phụ thuộc hoàn toàn vào chất lượng description. Đây là lý do description là trường quan trọng nhất của skill.

Cách 3: Skill tool

Trong phiên làm việc, Claude gọi skill theo cách lập trình:

Skill({ skill: "commit-message" })

Bạn không gọi trực tiếp — đây là cách Claude Code kích hoạt skill nội bộ. Skill trong plugin dùng định dạng plugin:skill: Skill({ skill: "superpowers:brainstorming" }).

Đường dẫn cài đặt

Vị trí	Đường dẫn	Ai thấy
Personal	`~/.claude/skills/<name>/SKILL.md`	Chỉ bạn, mọi project
Project	`.claude/skills/<name>/SKILL.md`	Mọi người clone repo
Plugin	via `claude plugins install`	Ai cài plugin

Project-level skill là lựa chọn đúng cho convention của team — review rubric, release checklist, logging standard. Commit .claude/skills/ vào repo và mọi contributor có skill tự động mà không cần thiết lập thêm gì.

Kiểm thử và cải tiến

Bắt đầu bằng forced invocation trước khi dựa vào auto-trigger:

/commit-message

Xác nhận Claude tải body và tạo commit message từ staged diff của bạn. Nếu hoạt động qua slash command, skill đã được cài đúng. Vấn đề auto-trigger luôn là lỗi description, không phải lỗi cài đặt.

Checklist debug khi skill không kích hoạt:

Tên thư mục — kiểm tra tên thư mục khớp với slug bạn đang gõ. /commit_message (gạch dưới) sẽ không khớp thư mục tên commit-message (gạch ngang). Dấu cách hoặc ký tự đặc biệt trong tên thư mục làm hỏng invocation hoàn toàn.
Mức độ cụ thể của description — thêm chính xác cụm từ bạn dùng trong thực tế. Nếu bạn nói “write a commit” thay vì “write a commit message,” description của bạn cần khớp. Bắt đầu bằng "Use when..." và liệt kê các trigger phrase cụ thể.
Cấu trúc thư mục — file phải ở ~/.claude/skills/<name>/SKILL.md. File phẳng ~/.claude/skills/<name>.md bị bỏ qua lặng lẽ. Kiểm tra bằng ls ~/.claude/skills/<name>/.
Force-invoke làm baseline — /skill-name tải skill bất kể logic auto-trigger. Nếu slash command hoạt động nhưng auto-trigger không, vấn đề là description, không phải file.
Plugin conflict — nếu plugin skill và personal skill cùng name:, kiểm tra cái nào thắng bằng claude plugins details <plugin-name>. Thứ tự ưu tiên (personal vs. project vs. plugin) được ghi lại trong Anthropic docs chính thức.

Một chu kỳ iteration: chỉnh sửa SKILL.md, kiểm tra với /commit-message. Chỉnh sửa file skill hiện tại có hiệu lực ngay trong phiên mà không cần restart; chỉ tạo thư mục skills top-level hoàn toàn mới mới cần restart phiên.

Kiểm tra thực tế cho chất lượng description: đọc to description và tự hỏi nó có xác định duy nhất khi nào skill này nên kích hoạt so với mọi skill khác bạn đã cài không. Nếu câu trả lời còn mơ hồ, hãy cụ thể hơn.

Đóng gói và chia sẻ

Nếu skill hữu ích vượt ra ngoài máy của bạn, route plugin thêm version control và một lệnh cài cho cả team.

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

my-skills-plugin/
  .claude-plugin/
    plugin.json
  skills/
    commit-message/
      SKILL.md
    code-review/
      SKILL.md
      rubric.md
  README.md

File bổ sung (rubric.md, lookup table lớn) sống cạnh SKILL.md trong thư mục skill. File skill chính giữ ngắn gọn; nội dung nặng chuyển sang file reference tải theo yêu cầu.

plugin.json

{
  "name": "my-skills-plugin",
  "description": "Team workflow skills",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "repository": "https://github.com/yourusername/my-skills-plugin"
}

Validate trước khi publish:

claude plugins validate .

Cài đặt từ GitHub repo

# Đăng ký repo làm marketplace source (một lần mỗi máy)
claude plugins marketplace add yourusername/my-skills-plugin

# Cài plugin
claude plugins install my-skills-plugin@yourusername

Claude Code restart, skill của plugin sẵn sàng, và plugin xuất hiện trong ~/.claude/settings.json dưới enabledPlugins. Các thành viên team chạy hai lệnh này trên máy của họ và có cùng skill.

Kiểm thử plugin cục bộ trước khi publish:

claude --plugin-dir /path/to/my-skills-plugin

Cách này tải plugin cho một phiên duy nhất — không ghi gì vào settings.json. Chạy /commit-message trong phiên đó để xác nhận body skill tải đúng.

Plugin CLI reference (Claude Code v2.1.140):

claude plugins list                          # danh sách plugin đã cài
claude plugins install <name>@<source>       # cài
claude plugins update <name>                 # cập nhật lên phiên bản mới nhất
claude plugins uninstall <name>              # gỡ
claude plugins details <name>                # liệt kê skills + chi phí token ước tính mỗi skill
claude plugins validate <path>               # validate plugin.json

claude plugins details đáng chạy trên bất kỳ plugin mới nào trước khi cài trên máy dùng chung — nó cho thấy footprint token ước tính của mỗi skill để bạn biết chi phí mỗi lần gọi trước khi quyết định.

Đi xa hơn

Superpowers là plugin tham chiếu chuẩn cho skill pattern trong production. Nó ship 14 skill bao gồm brainstorming, systematic debugging, TDD, code review và nhiều hơn nữa. Mỗi skill minh họa định dạng chuẩn: SKILL.md ngắn gọn dưới 200 dòng, nội dung tham khảo nặng chuyển sang file bổ sung, và description được tinh chỉnh để auto-trigger đáng tin cậy. GitHub: obra/superpowers. Cài bằng:

claude plugins install superpowers@claude-plugins-official

Với team skill trong production ngoài hệ thống plugin, thư mục packages/agents/skills/ trong repo này có 16 editorial-pipeline skill dùng bởi AI agent chạy workflow xuất bản của site. Chúng được tải theo cơ chế khác (inject qua CLAUDE.md thay vì Skill tool), nhưng cấu trúc nội dung — các bước đánh số, CLI invocation chính xác, failure mode tường minh — chính là thứ làm skill đáng tin cậy ở quy mô lớn. Editorial rubric, house-style guide, và SEO checklist đều là skill ở đây. Đáng đọc nếu bạn đang build skill cho agent workflow hơn là phiên tương tác.

Đặc tả frontmatter đầy đủ ngoài name và description có tại agentskills.io/specification và docs.anthropic.com/en/docs/claude-code/skills.

Skill mở rộng hành vi của Claude bằng workflow có thể tái sử dụng; MCP mở rộng những gì Claude có thể kết nối đến. Nếu bạn muốn Claude Code truy vấn dữ liệu bên ngoài — database, API, dịch vụ thứ ba — xây dựng MCP server cho Claude Code là phần bổ trợ tự nhiên, và cũng chỉ mất khoảng 30 phút để có kết quả.

Với team chạy phiên AI agent nặng — nhiều Claude Code instance, parallel pipeline, automated workflow — Claude Max đáng cân nhắc. Giới hạn sử dụng cao hơn quan trọng khi skill kích hoạt trên nhiều phiên song song. GitHub Copilot không có model extensibility tương đương tính đến 2026: không có cách nào đóng gói và chia sẻ hướng dẫn workflow như Claude Code skill. Với team đã dùng Claude Code, skill là con đường ít tốn công nhất để đạt được hành vi AI nhất quán cho mọi người. Trước khi quyết định nâng lên Max, đánh giá Claude Code năm 2026 tổng hợp benchmark, giới hạn usage, và câu chuyện sự cố tháng 4 trong một bài.