Skills mở rộng những gì Claude có thể làm. Bạn tạo một file SKILL.md chứa instructions, và Claude thêm nó vào toolkit của mình: Claude tự động dùng skill khi liên quan, hoặc bạn invoke trực tiếp bằng /skill-name. Không giống nội dung trong CLAUDE.md (luôn nằm trong context), body của skill chỉ load khi được dùng — nên tài liệu tham chiếu dài gần như không tốn gì cho tới lúc cần.
Khi nào nên tạo skill
Tạo skill khi bạn:
- Liên tục paste cùng một checklist, instructions, hoặc quy trình nhiều bước vào chat.
- Có một phần CLAUDE.md đã phình từ "một fact" thành "một quy trình".
- Muốn đóng gói một hành động có side-effect (deploy, commit, gửi Slack) để invoke đúng lúc.
Skills tuân theo chuẩn mở Agent Skills, hoạt động xuyên nhiều công cụ AI. Claude Code mở rộng chuẩn này với invocation control, subagent execution (context: fork), và dynamic context injection.
Custom commands đã được gộp vào skills. File
.claude/commands/deploy.mdvà skill.claude/skills/deploy/SKILL.mdđều tạo/deployvà hoạt động như nhau. File.claude/commands/cũ vẫn chạy; skills bổ sung: thư mục cho supporting files, frontmatter điều khiển ai invoke, và khả năng để Claude tự load khi liên quan.
Cấu trúc một skill
Mỗi skill là một thư mục với SKILL.md làm entrypoint (bắt buộc). Các file khác là tùy chọn.
my-skill/
├── SKILL.md # Instructions chính (bắt buộc)
├── template.md # Template để Claude điền vào
├── examples/
│ └── sample.md # Ví dụ output cho định dạng mong đợi
└── scripts/
└── validate.sh # Script Claude có thể execute
SKILL.md gồm hai phần: YAML frontmatter giữa hai dấu --- (cho Claude biết khi nào dùng skill), và markdown content (instructions Claude làm theo khi skill chạy). Tên thư mục trở thành lệnh bạn gõ; description giúp Claude quyết định khi nào tự load.
Ví dụ tối thiểu
Skill dưới đây tóm tắt thay đổi chưa commit và flag rủi ro. Dòng !`git diff HEAD` dùng dynamic context injection: Claude Code chạy lệnh và thay dòng đó bằng output trước khi Claude thấy nội dung skill.
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.
Lưu vào ~/.claude/skills/summarize-changes/SKILL.md. Sau đó test theo hai cách:
- Để Claude tự invoke: hỏi một câu khớp description, ví dụ
What did I change? - Invoke trực tiếp: gõ
/summarize-changes
Frontmatter reference
Tất cả field đều optional. Chỉ description được khuyến nghị để Claude biết khi nào dùng skill.
---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---
Your skill instructions here...
| Field | Bắt buộc | Mô tả |
|---|---|---|
name | Không | Display name trong skill listings. Mặc định là tên thư mục. Thường KHÔNG đổi lệnh bạn gõ (trừ plugin-root SKILL.md). |
description | Khuyến nghị | Skill làm gì và khi nào dùng. Claude dựa vào đây để quyết định. Nếu bỏ trống, lấy đoạn đầu của markdown content. Đặt use case chính lên đầu: description + when_to_use bị cắt ở 1.536 ký tự trong listing. |
when_to_use | Không | Ngữ cảnh bổ sung: trigger phrases hoặc ví dụ request. Nối vào description, tính vào giới hạn 1.536 ký tự. |
argument-hint | Không | Gợi ý autocomplete cho argument. Ví dụ [issue-number]. |
arguments | Không | Named positional arguments cho substitution $name. Chuỗi cách nhau bằng dấu cách hoặc YAML list. |
disable-model-invocation | Không | true để ngăn Claude tự load skill. Dùng cho workflow chỉ trigger thủ công bằng /name. Cũng ngăn preload vào subagent và (từ v2.1.196) ngăn chạy khi scheduled task fire. Mặc định false. |
user-invocable | Không | false để ẩn khỏi menu /. Dùng cho background knowledge người dùng không invoke trực tiếp. Mặc định true. |
allowed-tools | Không | Tools Claude được dùng mà không cần xin phép trong lượt invoke skill. Grant xóa khi bạn gửi message tiếp theo. Chuỗi cách nhau bằng dấu cách/dấu phẩy, hoặc YAML list. |
disallowed-tools | Không | Tools bị gỡ khỏi pool khi skill active. Dùng cho autonomous skill không được gọi một tool nào đó. Restriction xóa ở message tiếp theo. |
model | Không | Model dùng khi skill active. Áp dụng hết lượt hiện tại, không lưu vào settings. Nhận giá trị như /model, hoặc inherit. |
effort | Không | Effort level khi skill active. low, medium, high, xhigh, max (tùy model). Ghi đè effort của session. |
context | Không | fork để chạy trong forked subagent context. Xem Chạy skill trong subagent. |
agent | Không | Loại subagent dùng khi context: fork. |
hooks | Không | Hooks scoped theo lifecycle của skill. |
paths | Không | Glob patterns giới hạn khi nào skill được kích hoạt tự động. Chuỗi cách nhau bằng dấu phẩy hoặc YAML list. |
shell | Không | Shell cho !`command` và block ```!. bash (mặc định) hoặc powershell. |
Reference content vs task content
Nghĩ về cách bạn muốn invoke sẽ hướng dẫn nội dung nên đặt gì:
- Reference content — thêm kiến thức Claude áp dụng cho công việc hiện tại (conventions, style guides, domain knowledge). Chạy inline cùng context hội thoại. Thường để Claude tự dùng.
- Task content — instructions từng bước cho một hành động cụ thể (deploy, commit, code gen). Thường muốn invoke trực tiếp bằng
/skill-name; thêmdisable-model-invocation: trueđể Claude không tự trigger.
Giữ body ngắn gọn. Khi skill load, nội dung nằm trong context suốt session — mỗi dòng là chi phí token lặp lại. Nói làm gì thay vì kể lể thế nào hay tại sao. Giữ SKILL.md dưới 500 dòng; đẩy tài liệu tham chiếu dài sang file riêng.
Skills được tổ chức ở đâu
Nơi lưu skill quyết định ai dùng được nó:
| Location | Path | Áp dụng cho |
|---|---|---|
| Enterprise | Xem managed settings | Toàn bộ user trong tổ chức |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | Tất cả project của bạn |
| Project | .claude/skills/<skill-name>/SKILL.md | Chỉ project này |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Nơi plugin được bật |
Thứ tự override khi trùng tên: enterprise > personal > project. Skill ở bất kỳ level nào cũng override bundled skill trùng tên (ví dụ code-review trong .claude/skills/ thay thế bundled /code-review). Plugin skills dùng namespace plugin-name:skill-name nên không xung đột. Nếu skill và command trùng tên, skill thắng.
Nested skills (monorepo)
Skills cũng load từ .claude/skills/ trong thư mục con dưới working directory. Khi Claude đọc/sửa file trong subdirectory, skills từ .claude/skills/ của thư mục đó trở nên available. Điều này cho phép một package trong monorepo cung cấp skills riêng.
Nếu nested skill trùng tên với skill khác, cả hai đều còn:
- Nested skill xuất hiện dưới tên directory-qualified, ví dụ
apps/web:deploy. - Description của nó ghi rõ áp dụng cho thư mục nào.
- Claude chọn variant khớp với file đang làm việc.
Gõ /deploy chạy skill ở project root; gõ /apps/web:deploy chạy variant nested (yêu cầu v2.1.203+).
Discovery và live reload
- Parent directories: project skills load từ
.claude/skills/ở thư mục khởi động và mọi thư mục cha lên tới repo root, nên khởi động Claude trong subdirectory vẫn nhận skills định nghĩa ở root. --add-dir//add-dir: đây là ngoại lệ —.claude/skills/trong thư mục được add sẽ load tự động (settingpermissions.additionalDirectoriesthì KHÔNG).- Live change detection: thêm/sửa/xóa skill dưới
~/.claude/skills/, project.claude/skills/, hoặc.claude/skills/trong--add-dircó hiệu lực ngay trong session. Tạo mới một top-level skills directory chưa tồn tại lúc start thì cần restart. - Symlink: một entry skill có thể là symlink tới thư mục khác; Claude Code theo symlink đọc
SKILL.md.
Cloud sessions (bao gồm routines) và Cowork KHÔNG đọc
~/.claude/skills/trên máy bạn. Cloud sessions load project skills đã commit vào.claude/skills/của repo. Để dùng skill cá nhân ở đó: enable skill cho tài khoản claude.ai, commit vào repo, hoặc ship trong plugin khai báo ở.claude/settings.jsoncủa repo.
Cách Claude tự động invoke
Trong session thường, description của mọi skill được load vào context để Claude biết cái gì có sẵn, nhưng full content chỉ load khi skill được invoke. Hai field kiểm soát ai invoke được:
| Frontmatter | Bạn invoke | Claude invoke | Khi nào load vào context |
|---|---|---|---|
| (mặc định) | Có | Có | Description luôn trong context; full skill load khi invoke |
disable-model-invocation: true | Có | Không | Description KHÔNG trong context; full skill load khi bạn invoke |
user-invocable: false | Không | Có | Description luôn trong context; full skill load khi invoke |
disable-model-invocation: true— chỉ bạn invoke được. Dùng cho workflow có side-effect hoặc cần kiểm soát thời điểm:/commit,/deploy,/send-slack-message.user-invocable: false— chỉ Claude invoke được. Dùng cho background knowledge không phải một hành động: skilllegacy-system-contextgiải thích một hệ thống cũ.
Skill content lifecycle
Khi invoke, SKILL.md đã render vào hội thoại như một message và ở lại suốt session (persistence áp dụng cho instructions, không phải permissions — allowed-tools xóa ở message tiếp theo). Claude Code KHÔNG đọc lại file ở các lượt sau, nên hãy viết guidance áp dụng cả task như standing instructions.
- Re-invoke với nội dung y hệt: Claude Code chỉ thêm ghi chú ngắn "skill đã load", không copy lại (từ v2.1.202).
- Re-invoke với nội dung khác (arguments đổi hoặc dynamic command ra output mới): full content được append lại.
- Auto-compaction: mang skills đã invoke tiến lên trong token budget (giữ 5.000 token đầu mỗi skill, tổng ngân sách 25.000 token, ưu tiên skill invoke gần nhất).
Truyền arguments
Cả bạn và Claude đều truyền được arguments qua placeholder $ARGUMENTS.
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit
Chạy /fix-issue 123 → Claude nhận "Fix GitHub issue 123...". Nếu skill không chứa $ARGUMENTS, Claude Code nối ARGUMENTS: <input> vào cuối.
String substitutions hữu dụng:
| Biến | Mô tả |
|---|---|
$ARGUMENTS | Toàn bộ arguments truyền vào. |
$ARGUMENTS[N] / $N | Argument thứ N theo index 0-based ($0, $1...). |
$name | Named argument khai báo trong frontmatter arguments. |
${CLAUDE_SESSION_ID} | Session ID hiện tại. |
${CLAUDE_EFFORT} | Effort level hiện tại. |
${CLAUDE_SKILL_DIR} | Thư mục chứa SKILL.md — dùng để tham chiếu script bundled bất kể cwd. |
${CLAUDE_PROJECT_DIR} | Project root (v2.1.196+); áp dụng cho cả body lẫn allowed-tools. |
Advanced patterns
Dynamic context injection
Cú pháp !`<command>` chạy shell command TRƯỚC khi content gửi tới Claude; output thay placeholder. Đây là preprocessing, không phải thứ Claude execute.
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
## Your task
Summarize this pull request...
! chỉ được nhận diện khi ở đầu dòng hoặc ngay sau whitespace. Cho lệnh nhiều dòng, dùng fenced block mở bằng ```!. Đặt "disableSkillShellExecution": true trong settings để tắt hành vi này.
Chạy skill trong subagent
Thêm context: fork để skill chạy cô lập — content của skill trở thành prompt điều khiển subagent, và nó KHÔNG có lịch sử hội thoại của bạn. Chỉ hợp lý với skill có instructions rõ ràng (task), không phải guideline thuần.
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
Field agent chọn cấu hình subagent: built-in (Explore, Plan, general-purpose) hoặc custom agent từ .claude/agents/. Bỏ trống thì dùng general-purpose. Explore và Plan bỏ qua CLAUDE.md để giữ context nhỏ.
Pre-approve tools
allowed-tools cấp quyền dùng các tool liệt kê mà không hỏi, chỉ trong lượt invoke skill (grant xóa ở message tiếp theo). Nó KHÔNG hạn chế tool nào available — mọi tool vẫn gọi được, permission settings vẫn chi phối tool ngoài danh sách. Với skill trong project .claude/skills/, allowed-tools chỉ có hiệu lực sau khi bạn accept workspace trust dialog — hãy review project skills trước khi trust repo.
---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---
Viết description tốt
description là thứ Claude dùng để quyết định khi nào dùng skill, nên chất lượng của nó quyết định skill có trigger đúng không.
- Gồm keywords người dùng nói tự nhiên. Nêu skill làm gì VÀ khi nào dùng: "Use when the user asks what changed, wants a commit message, or asks to review their diff."
- Đặt use case chính lên đầu. Listing cắt
description+when_to_useở 1.536 ký tự (chỉnh bằngskillListingMaxDescChars). - Skill không trigger? Kiểm tra description chứa keyword, xác nhận skill xuất hiện khi hỏi
What skills are available?, thử diễn đạt lại request cho khớp, hoặc invoke trực tiếp/skill-name. - Skill trigger quá nhiều? Làm description cụ thể hơn, hoặc thêm
disable-model-invocation: truenếu chỉ muốn thủ công. - Description bị cắt ngắn: khi có nhiều skill, listing rút gọn description để vừa budget (mặc định 1% context window). Chạy
/doctorđể ước lượng chi phí, nâng bằngskillListingBudgetFractionhoặc đặt skill ít dùng thành"name-only"trongskillOverrides.
Nếu frontmatter YAML sai cú pháp, Claude Code load body với metadata rỗng:
/skill-namevẫn chạy nhưng Claude không códescriptionđể match. Chạy--debugđể thấy lỗi parse.
Điều khiển visibility từ settings
skillOverrides (trong .claude/settings.local.json) điều khiển visibility mà không cần sửa SKILL.md — hữu ích cho skill checked-in của repo dùng chung. Menu /skills ghi giúp bạn (nhấn Space để đổi trạng thái).
| Value | Listed cho Claude | Trong menu / |
|---|---|---|
"on" | Name + description | Có |
"name-only" | Chỉ name | Có |
"user-invocable-only" | Ẩn | Có |
"off" | Ẩn | Ẩn |
Plugin skills không bị skillOverrides ảnh hưởng — quản lý qua /plugin.
Đóng gói và chia sẻ
Skills phân phối ở nhiều scope tùy đối tượng:
- Project skills — commit
.claude/skills/vào version control. - Plugins — tạo thư mục
skills/trong plugin. Mỗi skill là folder chứaSKILL.md; skill được namespace theo tên plugin (hello/trong pluginmy-first-plugin→/my-first-plugin:hello). Sau khi cài, chạy/reload-pluginsđể load. Plugin cho phép versioned releases, chia sẻ qua marketplace, và bundle kèm agents/hooks/MCP servers. - Managed — deploy toàn tổ chức qua managed settings.
Một plugin ship đúng một skill có thể đặt SKILL.md ngay tại plugin root thay vì tạo thư mục skills/; khi đó frontmatter name mới quyết định tên invoke. Thêm .claude-plugin/plugin.json vào một skill folder biến nó thành plugin <name>@skills-dir.
Bundled skills
Claude Code kèm sẵn một bộ bundled skills, có trong mọi session trừ khi tắt bằng setting disableBundledSkills: /doctor, /code-review, /batch, /debug, /loop, /claude-api... Khác với built-in commands (chạy logic cố định), bundled skills là prompt-based — cho Claude instructions chi tiết và để nó orchestrate bằng tools. Bộ ba /run, /verify, /run-skill-generator phối hợp để khởi động app và xác nhận thay đổi trên app đang chạy.
Đánh giá và lặp lại
Thấy skill trigger chỉ nghĩa là Claude tìm được nó, không phải nó làm đúng ý bạn. Đo tách biệt hai thứ: (1) Claude có invoke đúng prompt cần không, (2) output có khớp mong đợi không. Cách kiểm: baseline comparison — chạy vài prompt thực tế trong session mới có/không có skill và so sánh. Plugin skill-creator (từ official marketplace) tự động hóa vòng lặp này: test cases, isolated runs, grading, benchmark pass-rate với/không skill, A/B version comparison, và description tuning.
/plugin install skill-creator@claude-plugins-official
Xem thêm
content/en/docs/claude-code/skills.md— tài liệu gốc đầy đủ về skillscontent/en/docs/claude-code/plugins.md— đóng gói và phân phối skills qua plugincontent/en/docs/claude-code/sub-agents.md— subagents và preload skillscontent/en/docs/claude-code/hooks.md— tự động hóa workflow quanh tool eventscontent/en/docs/claude-code/settings.md—disableBundledSkills,skillOverrides,skillListingBudgetFraction- agentskills.io — chuẩn mở Agent Skills và hướng dẫn viết skill