Claude Code từ zero đến thành thạo · Phần 12 — Skills: bản dịch đầy đủ

Bản dịch trọn vẹn trang tài liệu Skills: bundled skill, tạo skill đầu tiên, nơi skill sống, toàn bộ bảng frontmatter, chuỗi thay thế, inject context động, chạy skill trong subagent, đánh giá bằng skill-creator và troubleshooting.

SEP 9, 2026 44 MIN READ

Skill mở rộng thứ Claude làm được. Tạo một file SKILL.md chứa chỉ dẫn, và Claude thêm nó vào bộ đồ nghề của mình. Claude dùng skill khi thấy liên quan, hoặc bạn gọi thẳng bằng /skill-name.

Tạo skill khi bạn cứ dán đi dán lại cùng một chỉ dẫn, checklist hay quy trình nhiều bước vào chat, hoặc khi một mục trong CLAUDE.md đã phình từ một sự thật thành một quy trình. Khác nội dung CLAUDE.md, phần thân của skill chỉ nạp 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 bạn cần.

Custom command đã được gộp vào skill. Một file ở .claude/commands/deploy.md và một skill ở .claude/skills/deploy/SKILL.md đều tạo ra /deploy và hoạt động y hệt. File .claude/commands/ cũ của bạn vẫn chạy. Skill thêm các tính năng tuỳ chọn: một thư mục cho file hỗ trợ, frontmatter để kiểm soát ai được gọi, và khả năng để Claude tự nạp khi liên quan.

Skill của Claude Code theo chuẩn mở Agent Skills, chuẩn này chạy được trên nhiều công cụ AI khác nhau. Claude Code mở rộng chuẩn đó bằng các tính năng riêng như kiểm soát cách gọi, thực thi trong subagent, và inject context động.

Đây là bài dịch đầy đủ trang skills — bài dài nhất của series, viết để tra cứu chứ không phải để đọc một lượt. Nếu bạn chưa rõ khi nào nên dùng skill thay vì CLAUDE.md, hook hay MCP, đọc phần 11 trước.

Bundled skill

Claude Code có sẵn một bộ bundled skill, ví dụ /doctor, /code-review, /batch, /debug, /loop, và /claude-api. Bundled skill dựa trên prompt: chúng đưa cho Claude chỉ dẫn chi tiết và để nó tự điều phối công việc bằng tool của mình. Phần lớn built-in command thì ngược lại — chúng thực thi logic cố định.

Bạn gọi bundled skill giống mọi skill khác: gõ / rồi tên skill. Claude tự gọi một số bundled skill khi thấy liên quan; số khác — gồm cả /verify — chỉ chạy khi bạn gọi, để bạn giữ quyền quyết định lúc nào các lượt kiểm tra dài này tiêu thời gian và token.

Bundled skill có mặt ở mọi phiên. Muốn tắt thì dùng setting disableBundledSkills, nó tắt mọi bundled skill trừ /doctor.

/doctor vẫn gõ được khi disableBundledSkills bật. Muốn giấu hẳn thì đặt biến môi trường DISABLE_DOCTOR_COMMAND, hoặc một mục skillOverrides dạng "doctor": "off".

Chạy và kiểm chứng app của bạn

Ba bundled skill phối hợp để khởi chạy app và xác nhận thay đổi trên app đang chạy thay vì chỉ dựa vào test:

Skill	Mục đích
`/run`	Khởi chạy và điều khiển app để thấy thay đổi hoạt động
`/verify`	Build và chạy app để xác nhận một thay đổi code làm đúng việc của nó, không lùi về test hay type check
`/run-skill-generator`	Dạy `/run` và `/verify` cách build và khởi chạy project của bạn

Cả ba cần Claude Code v2.1.145 trở lên.

/run và /verify chạy được mà không cần thiết lập gì. Chúng suy ra cách khởi chạy từ loại project (CLI, server, TUI, chạy qua trình duyệt) và từ nội dung README, package.json, hoặc Makefile. Nhưng suy đoán đó trở nên không đáng tin với project cần thêm bất cứ thứ gì ngoài một lần khởi chạy tiêu chuẩn: một database, một file env, một phiên đồ hoạ, một quy trình build nhiều bước.

/run-skill-generator ghi lại công thức thay vì suy đoán. Nó làm app của bạn chạy từ môi trường sạch, ghi lại thứ đã hiệu quả (lệnh cài đặt, biến môi trường, script khởi chạy), và commit chúng thành một skill riêng cho project ở .claude/skills/run-<name>/. Sau đó /run, /verify và mọi agent khác trong repo đi theo công thức đã ghi thay vì phải khám phá lại. Chạy /run-skill-generator một lần cho mỗi project, và chạy lại khi quy trình build hoặc khởi chạy thay đổi.

/verify cũng tự ghi công thức được. Khi phải build và điều khiển app mà không có công thức sẵn, nó ghi thứ đã hiệu quả vào .claude/skills/verify/SKILL.md ở gốc repo — hoặc trong thư mục package vừa động tới nếu là monorepo. Ở gốc repo, skill được ghi này thay thế bundled /verify.

Claude chỉ sửa file đã ghi khi có thứ lái một lượt chạy đi sai, ví dụ một lệnh fail hoặc một bước bị thiếu — nên bạn commit file được mà không bị diff ở mỗi phiên.

Bắt đầu

Tạo skill đầu tiên

Ví dụ này tạo một skill tóm tắt các thay đổi chưa commit trong git repo và chỉ ra chỗ rủi ro. Nó kéo diff sống vào prompt trước khi Claude đọc, nên phản hồi bám vào working tree thật chứ không phải thứ Claude đoán từ các file đang mở.

Bước 1 — tạo thư mục skill. Skill cá nhân dùng được ở mọi project của bạn:

mkdir -p ~/.claude/skills/summarize-changes

Bước 2 — viết SKILL.md. Mọi skill cần một file 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à nội dung markdown chứa chỉ dẫn Claude làm theo khi skill chạy. Tên thư mục trở thành lệnh bạn gõ, còn description giúp Claude quyết định khi nào tự nạp skill.

Lưu vào ~/.claude/skills/summarize-changes/SKILL.md:

---
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.

Dòng !`git diff HEAD` dùng inject context động: Claude Code chạy lệnh và thay dòng đó bằng output trước khi Claude thấy nội dung skill — nên chỉ dẫn tới tay Claude đã kèm sẵn diff hiện tại.

Bước 3 — thử skill. Mở một git project, sửa nhẹ một file bất kỳ, chạy claude. Có hai cách thử. Để Claude tự gọi bằng cách hỏi thứ khớp với description:

What did I change?

Hoặc gọi thẳng:

/summarize-changes

Cách nào cũng cho ra một bản tóm tắt ngắn về sửa đổi của bạn kèm danh sách rủi ro.

Skill sống ở đâu

Chỗ bạn lưu skill quyết định ai dùng được nó:

Vị trí	Đường dẫn	Áp dụng cho
Enterprise	Xem managed settings	Mọi user trong tổ chức
Cá nhân	`~/.claude/skills/<skill-name>/SKILL.md`	Mọi 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

Khi các skill trùng tên, Claude Code giải quyết xung đột theo nguồn:

Giữa các cấp: enterprise thắng cá nhân, cá nhân thắng project. Ví dụ có skill deploy ở cả ~/.claude/skills/ lẫn .claude/skills/ của project thì /deploy chạy bản cá nhân.
Skill ở bất kỳ cấp nào cũng ghi đè bundled skill trùng tên, nhưng không ghi đè alias của bundled skill. Ví dụ skill code-review trong project thay thế bundled /code-review, nhưng gõ alias /review không bao giờ chạy skill của bạn.
Skill của plugin dùng namespace plugin-name:skill-name nên không đụng độ với cấp nào.
Nếu bạn có file trong .claude/commands/, chúng hoạt động y hệt — nhưng khi một skill và một command trùng tên, skill thắng.
Skill hoặc command từ bất kỳ nguồn nào trên đây đều ghi đè một skill đồng bộ từ tài khoản claude.ai trùng tên.

Skill còn nạp từ các thư mục .claude/skills/ lồng bên dưới thư mục làm việc. Khi Claude đọc hoặc sửa một file trong thư mục con, skill từ .claude/skills/ của thư mục con đó trở nên khả dụng. Cơ chế này cho phép một package trong monorepo cấp skill riêng áp dụng khi làm việc với package đó, kể cả khi phiên bắt đầu ở gốc repo.

Nếu một skill lồng trùng tên với skill khác, cả hai đều còn. Ví dụ có skill deploy ở gốc project và một cái nữa ở apps/web/.claude/skills/:

Cái lồng xuất hiện dưới tên có kèm thư mục: apps/web:deploy.
Description của nó nói rõ nó áp cho thư mục nào.
Claude chọn biến thể khớp với file nó đang làm việc.

Gõ /deploy chạy skill ở gốc project. Gõ tên đầy đủ /apps/web:deploy để chạy biến thể lồng một cách tường minh. Khi bạn hoặc Claude gọi tên không kèm thư mục, skill ở gốc project nạp, và Claude Code nối thêm danh sách các biến thể vào nội dung của nó kèm chỉ dẫn cũng gọi biến thể nào có thư mục chứa file Claude đang làm.

Tên thư mục synced là tên dành riêng ở cả ba vị trí enterprise, cá nhân và project, ở mọi kiểu viết hoa thường.

Một mục <skill-name> ở các vị trí enterprise, cá nhân hoặc project có thể là symlink tới một thư mục khác trên đĩa. Claude Code đi theo symlink và đọc SKILL.md từ thư mục đích; nếu cùng một đích đến được từ nhiều vị trí, Claude Code chỉ nạp skill một lần.

Thêm .claude-plugin/plugin.json vào một thư mục skill và nó nạp như một plugin tên <name>@skills-dir, nhờ đó gói kèm được agent, hook và MCP server. Trong .claude/skills/ của project, việc này cần bạn chấp nhận hộp thoại workspace trust trước.

Phát hiện thay đổi trực tiếp

Claude Code theo dõi các thư mục skill. Khi bạn thêm, sửa hoặc xoá một skill dưới ~/.claude/skills/, .claude/skills/ của project, hoặc .claude/skills/ bên trong một thư mục --add-dir, Claude Code nhận thay đổi ngay trong phiên hiện tại, không cần khởi động lại.

Nếu bạn tạo mới một thư mục skills cấp cao chưa tồn tại lúc phiên bắt đầu, phải khởi động lại Claude Code để nó theo dõi thư mục mới.

Phát hiện thay đổi trực tiếp chỉ phủ phần text của SKILL.md. Với một thư mục skill đồng thời là plugin, thay đổi ở hooks/, .mcp.json, agents/ và output-styles/ cần chạy /reload-plugins mới có hiệu lực.

Phát hiện từ thư mục cha và thư mục lồng

Skill của project nạp từ .claude/skills/ ở thư mục bạn khởi động Claude Code và mọi thư mục cha lên tới gốc repository. Khởi động Claude trong một thư mục con vẫn nhặt được skill khai ở gốc.

Skill trong các thư mục .claude/skills/ lồng bên dưới thư mục khởi động thì không nạp lúc khởi động. Chúng nạp lần đầu tiên Claude đọc hoặc sửa một file bên trong thư mục con đó, rồi còn khả dụng suốt phần còn lại của phiên. Trước lúc đó, chúng không hiện trong autocomplete và không gọi được bằng tên.

Mỗi skill là một thư mục với SKILL.md làm điểm vào:

my-skill/
├── SKILL.md           # Chỉ dẫn chính (bắt buộc)
├── template.md        # Template để Claude điền
├── examples/
│   └── sample.md      # Output mẫu cho thấy định dạng mong đợi
└── scripts/
    └── validate.sh    # Script Claude chạy được

File trong .claude/commands/ hỗ trợ cùng bộ frontmatter, trừ name và paths — hai trường này bị Claude Code bỏ qua trong file command. Bạn gọi một file command bằng tên file của nó. Skill được khuyến nghị hơn vì hỗ trợ thêm các tính năng như file đi kèm.

Skill từ thư mục bổ sung

Flag --add-dir và lệnh /add-dir cấp quyền truy cập file chứ không phải phát hiện cấu hình — nhưng skill và command là ngoại lệ: Claude Code tự nạp .claude/skills/ và .claude/commands/ từ mỗi thư mục được thêm.

Ngoại lệ này chỉ áp cho --add-dir và /add-dir. Setting permissions.additionalDirectories trong settings.json chỉ cấp quyền truy cập file, không nạp skill, command hay subagent.

Subagent theo cùng ngoại lệ: khi bạn thêm một thư mục, Claude Code cũng nạp thư mục .claude/agents/ của nó. Nhưng nó không theo dõi thư mục đó, cũng không theo dõi .claude/commands/ của thư mục được thêm — nên sau khi thêm hoặc sửa một file subagent hay command ở đó, phải khởi động lại phiên.

Skill trong Cowork và phiên cloud

Phiên Cowork và phiên cloud — gồm cả routine — không đọc ~/.claude/skills/ trên máy bạn. Cả phiên Cowork tương tác lẫn theo lịch đều nạp các skill bạn bật cho tài khoản claude.ai, đồng bộ lúc phiên bắt đầu. Phiên cloud nạp thêm skill của project đã commit vào .claude/skills/ của repository được clone.

Nếu một skill chỉ tồn tại ở ~/.claude/skills/ trên máy bạn, Claude Code sẽ báo không tìm thấy skill khi một routine gọi nó, vì mỗi lần chạy routine là một phiên từ xa hoàn toàn mới. Để làm skill cá nhân khả dụng ở các phiên này:

Với Cowork và phiên cloud: bật skill đó cho tài khoản claude.ai.
Với phiên cloud, bạn có thể thay bằng cách commit skill vào .claude/skills/ của repository, hoặc ship nó trong một plugin khai trong .claude/settings.json của repository.

Desktop scheduled task thì khác: chúng chạy cục bộ trên máy bạn và nạp skill từ đúng các vị trí như mọi phiên local khác.

Skill đồng bộ từ claude.ai

Mục này áp dụng nếu bạn đã bật skill cho tài khoản claude.ai. Trong phiên Cowork và cloud, Claude Code nạp chúng mà không cần thiết lập gì trên máy bạn. Ở mọi phiên khác trên máy bạn, Claude Code chỉ nạp sau khi bạn bật đồng bộ bằng CLAUDE_CODE_SYNC_SKILLS trong một lượt chạy non-interactive.

Claude Code tải skill đồng bộ về từ tài khoản của bạn thay vì đọc một file bạn viết trên máy — nên nó áp cho skill đồng bộ những luật không áp cho skill bạn lưu ở các vị trí thông thường.

Skill đồng bộ nạp ở đâu

Ở phiên khác trên máy bạn, Claude Code chỉ nạp sau khi bạn tải chúng về một lần trong một lượt chạy non-interactive:

Bật skill cho tài khoản claude.ai. Claude Code chỉ tải các skill bạn đã bật, và nó cần bạn đăng nhập claude.ai để tải.
Chạy Claude Code ở chế độ non-interactive với đồng bộ bật. Claude Code chỉ tải skill đồng bộ khi bạn chạy với flag -p và đặt CLAUDE_CODE_SYNC_SKILLS thành 1. Prompt bạn truyền vào không ảnh hưởng tới việc tải:

CLAUDE_CODE_SYNC_SKILLS=1 claude -p "List the skills you have available"

Claude Code tải skill vào ~/.claude/skills/synced/, trả lời prompt, rồi thoát như mọi lượt chạy non-interactive khác. Skill đã tải nằm lại trên đĩa sau khi nó thoát. Claude Code chỉ tải skill trong lượt chạy có đặt CLAUDE_CODE_SYNC_SKILLS, nên sau khi bạn bật hoặc đổi một skill trên claude.ai, chạy lại lệnh đó. Đổi thời gian chờ đồng bộ bằng CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS.

Xác nhận skill nạp trong phiên local. Mở phiên tương tác, không đặt CLAUDE_CODE_SYNC_SKILLS, rồi chạy /skills. Menu liệt kê các skill đã tải dưới nhãn claude.ai sync.

Khi tên skill đồng bộ trùng một lệnh khác

Claude Code bỏ qua một skill đồng bộ có tên trùng bất kỳ lệnh nào khác, và lệnh kia chạy. Lệnh kia có thể là built-in command, bundled skill, skill ở bất kỳ cấp local nào, skill plugin, file trong .claude/commands/, hoặc một MCP prompt. Claude Code còn giữ chỗ tên của built-in command và bundled skill của chính nó ngay cả khi chúng không khả dụng trong phiên của bạn.

Khi so tên, Claude Code bỏ qua hoa thường, khoảng trắng và ký tự vô hình, và coi các dạng tương thích như chữ fullwidth hay biến thể dấu gạch ngang là bản thường của chúng — nên một skill đồng bộ tên Commit không nạp cạnh một commit local được. Một tên chỉ khác ở một chữ cái giống hệt thuộc bảng chữ cái khác thì được tính là tên khác, và nhãn claude.ai sync là cách bạn phân biệt hai cái.

Claude Code xử lý frontmatter của skill đồng bộ thế nào

Hai luật:

Claude Code tôn trọng frontmatter ở mọi loại phiên, nên một grant allowed-tools vẫn đi qua luồng permission bình thường.
Claude Code làm sạch phần text hiển thị mà skill cung cấp, ví dụ description. Nó xoá ký tự điều khiển, và ở phần text tới tay Claude, nó còn escape dấu ngoặc nhọn để text không giả dạng được định dạng nội bộ của Claude Code.

Claude Code xử lý phần thân của skill đồng bộ thế nào

Phụ thuộc phiên chạy ở đâu:

Phiên cloud — phần thân giữ đúng hành vi của một skill local, vì phiên chạy trong container cô lập.
Phiên Cowork trên desktop — phần thân giữ hành vi của skill local, trừ việc Claude Code thay mọi dòng lệnh ! bằng placeholder disableSkillShellExecution.
Mọi phiên khác trên máy bạn — Claude Code không chạy lệnh !, không đính kèm file mà các tham chiếu @ chỉ tới, và không thay thế các placeholder ${CLAUDE_PROJECT_DIR} và ${CLAUDE_SESSION_ID} — nên các tham chiếu @ và cả hai placeholder tới tay Claude dưới dạng text nguyên văn.

Xoá một skill

Cách xoá phụ thuộc skill đến từ đâu:

Skill cá nhân hoặc project — xoá thư mục của nó, ~/.claude/skills/<skill-name>/ hoặc .claude/skills/<skill-name>/. Claude Code bỏ nó khỏi /skills ngay trong phiên hiện tại; nội dung từ một lần gọi trước đó trong phiên vẫn nằm lại trong context tới hết phiên.
Skill enterprise — quản trị viên xoá thư mục của skill khỏi .claude/skills/ bên trong thư mục managed settings.
Skill plugin — tắt hoặc gỡ plugin cung cấp nó, từ menu /plugin hoặc bằng /plugin uninstall <plugin-name>@<marketplace-name>.
Skill đồng bộ từ claude.ai — tắt skill đó cho tài khoản claude.ai. Nếu bạn xoá thư mục bằng tay, lần đồng bộ kế tiếp sẽ tải nó về lại khi skill vẫn còn bật trên claude.ai.
Bundled skill — đặt disableBundledSkills thành true để tắt mọi bundled skill trừ /doctor, hoặc đặt một skill thành "off" trong skillOverrides để giấu nó.

Muốn giữ một skill cá nhân hoặc project nhưng ngăn Claude tự gọi nó, đặt disable-model-invocation: true trong frontmatter, hoặc "user-invocable-only" trong skillOverrides khi bạn không muốn sửa file.

Cấu hình skill

Skill được cấu hình qua YAML frontmatter ở đầu SKILL.md và phần nội dung markdown theo sau.

Các loại nội dung skill

File skill chứa được chỉ dẫn bất kỳ, nhưng nghĩ về cách bạn muốn gọi nó sẽ định hướng nội dung nên có:

Nội dung tham chiếu thêm kiến thức Claude áp vào công việc hiện tại: convention, pattern, style guide, kiến thức miền. Nội dung này chạy inline để Claude dùng nó cùng với context hội thoại.

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
  - Use RESTful naming conventions
  - Return consistent error formats
  - Include request validation

Nội dung tác vụ đưa cho Claude chỉ dẫn từng bước cho một hành động cụ thể — deploy, commit, sinh code. Đây thường là hành động bạn muốn gọi thẳng bằng /skill-name thay vì để Claude tự quyết. Thêm disable-model-invocation: true để ngăn Claude tự kích hoạt:

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

Giữ phần thân ngắn gọn. Một khi skill nạp, nội dung của nó nằm lại trong context xuyên các lượt — nên mỗi dòng là một chi phí token lặp lại. Nêu làm gì thay vì kể lể thế nào và tại sao, và áp cùng bài kiểm tra súc tích như với CLAUDE.md.

Bảng tham chiếu frontmatter

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---
Your skill instructions here...

Mọi trường đều tuỳ chọn. Chỉ description là được khuyến nghị, để Claude biết khi nào dùng skill.

Trường boolean nhận yes, no, on, off, 1, 0 ở mọi kiểu viết hoa thường, ngoài true và false.

Trường	Bắt buộc	Mô tả
`name`	Không	Tên hiển thị trong danh sách skill. Mặc định là tên thư mục
`description`	Khuyến nghị	Skill làm gì và khi nào dùng. Claude dùng nó để quyết định khi nào áp skill. Bỏ trống thì lấy đoạn markdown đầu tiên. Đặt use case quan trọng nhất lên trước: phần text gộp của `description` và `when_to_use` bị cắt ở 1.536 ký tự trong danh sách skill
`when_to_use`	Không	Ngữ cảnh bổ sung cho việc khi nào Claude nên gọi skill, ví dụ cụm từ kích hoạt hoặc yêu cầu mẫu. Được nối vào `description` và tính vào giới hạn 1.536 ký tự
`argument-hint`	Không	Gợi ý hiện lúc autocomplete để chỉ ra tham số mong đợi. Ví dụ: `[issue-number]` hoặc `[filename] [format]`
`arguments`	Không	Tham số vị trí có tên, dùng cho thay thế `$name` trong nội dung skill. Nhận chuỗi cách nhau bằng khoảng trắng hoặc một YAML list. Tên map theo thứ tự vị trí
`disable-model-invocation`	Không	Đặt `true` để ngăn Claude tự nạp skill này. Cũng ngăn skill được nạp trước vào subagent, và ngăn skill chạy khi một scheduled task kích hoạt với skill làm prompt. Mặc định `false`
`user-invocable`	Không	Đặt `false` khi chỉ Claude được gọi skill: Claude Code giấu nó khỏi menu `/` và không chạy khi bạn gõ `/name`. Dùng cho kiến thức nền mà user không nên gọi trực tiếp. Mặc định `true`
`allowed-tools`	Không	Tool Claude dùng được không cần hỏi quyền trong lượt gọi skill này. Grant hết hiệu lực khi bạn gửi tin nhắn kế tiếp. Nhận chuỗi cách nhau bằng khoảng trắng/dấu phẩy, hoặc YAML list
`disallowed-tools`	Không	Tool bị gỡ khỏi kho tool khả dụng của Claude trong lúc skill hoạt động. Dùng cho skill tự chủ không bao giờ nên gọi một số tool, ví dụ `AskUserQuestion` cho một vòng lặp nền. Hạn chế hết hiệu lực khi bạn gửi tin nhắn kế tiếp
`model`	Không	Model dùng khi skill này hoạt động. Override áp cho phần còn lại của lượt hiện tại và không lưu vào settings. Nhận cùng giá trị như `/model`, hoặc `inherit` để giữ model đang chạy
`effort`	Không	Effort level khi skill hoạt động. Ghi đè effort của phiên. Mặc định: kế thừa từ phiên. Giá trị: `low`, `medium`, `high`, `xhigh`, `max`
`context`	Không	Đặt `fork` để chạy trong context subagent forked
`agent`	Không	Loại subagent dùng khi `context: fork` được đặt
`background`	Không	Chỉ áp khi có `context: fork`. Đặt `false` để chờ kết quả của subagent forked ngay trong lượt gọi skill, thay vì chạy ở nền. Mặc định `true`
`hooks`	Không	Hook mà Claude Code đăng ký khi skill được gọi và giữ chạy suốt phần còn lại của phiên
`paths`	Không	Glob pattern giới hạn khi nào skill được kích hoạt. Khi đặt, Claude chỉ tự nạp skill khi làm việc với file khớp pattern. Cùng định dạng với path-specific rule
`shell`	Không	Shell dùng cho !`command` và khối ```! trong skill này. Nhận `bash` (mặc định) hoặc `powershell`
`metadata`	Không	Map YAML tự do cho dữ liệu key-value của riêng bạn, đọc bởi tooling của chính bạn. Claude Code không hành động gì với nội dung của nó, và bỏ qua giá trị không phải map
`license`	Không	Giấy phép của skill. Thuộc spec Agent Skills. Claude Code nhận trường này nhưng không hành động gì
`compatibility`	Không	Yêu cầu môi trường của skill, theo spec Agent Skills. Nhận chuỗi tối đa 500 ký tự. Claude Code nhận nhưng không hành động gì

Dùng frontmatter của skill ngoài Claude Code

Claude Code nhận mọi trường ở bảng trên. Ngoài Claude Code, bạn chỉ dùng được các trường thuộc spec Agent Skills:

Đường phân phối	Trường frontmatter dùng được
Skill Claude Code ở mọi cấp, gồm cả skill plugin	Mọi trường ở bảng trên
Upload skill lên claude.ai, Skills API, và đóng gói bằng `package_skill.py`	`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`

Khi bạn bật một skill cá nhân cho Cowork và phiên cloud, bạn upload nó lên claude.ai, nên cùng luật đó áp dụng.

Nếu bạn để lẫn bất kỳ trường nào spec không cho phép, việc đóng gói hoặc upload fail bằng lỗi cứng chứ không bỏ qua trường đó:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Các tính năng chỉ có ở phần thân của Claude Code, ví dụ inject context động, không hoạt động trong chat claude.ai hay qua API.

Tên lệnh của một skill đến từ đâu

Lệnh bạn gõ để gọi một skill đến từ chỗ file skill nằm, và với skill plugin thì còn từ trường name trong frontmatter. Ở skill cá nhân hoặc project, name chỉ đặt nhãn hiển thị trong danh sách skill, còn lệnh vẫn lấy từ tên thư mục.

Vị trí skill	Tên lệnh lấy từ	Ví dụ
Thư mục skill dưới `~/.claude/skills/` hoặc `.claude/skills/`	Tên thư mục	`.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging`
Thư mục `.claude/skills/` lồng, khi tên đụng skill khác	Đường dẫn thư mục con so với thư mục làm việc, rồi tới tên thư mục skill	`apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy`
File dưới `.claude/commands/`	Tên file bỏ phần mở rộng	`.claude/commands/deploy.md` → `/deploy`
Thư mục con `skills/` của plugin	`name` trong frontmatter hoặc tên thư mục, có namespace theo plugin	`my-plugin/skills/review/SKILL.md` → `/my-plugin:review`
`SKILL.md` ở gốc plugin	`name` trong frontmatter, fallback về tên thư mục plugin	`my-plugin/SKILL.md` với `name: review` → `/my-plugin:review`

Ở skill plugin, trường name thay thế tên thư mục ở đoạn cuối của lệnh, nên my-plugin/skills/review/SKILL.md với name: fancy trở thành /my-plugin:fancy. Lệnh trần /fancy cũng gọi được skill trừ khi đã có lệnh khác dùng tên đó.

Các chuỗi thay thế có sẵn

Biến	Mô tả
`$ARGUMENTS`	Toàn bộ tham số truyền vào khi gọi skill. Nếu `$ARGUMENTS` không có trong nội dung, tham số được nối vào cuối dưới dạng `ARGUMENTS: <value>`
`$ARGUMENTS[N]`	Truy cập một tham số theo chỉ số 0-based, ví dụ `$ARGUMENTS[0]` cho tham số đầu
`$N`	Viết tắt của `$ARGUMENTS[N]`, ví dụ `$0` cho tham số đầu, `$1` cho tham số thứ hai
`$name`	Tham số có tên khai trong danh sách `arguments` ở frontmatter. Tên map theo thứ tự vị trí
`${CLAUDE_SESSION_ID}`	Session ID hiện tại. Hữu ích cho ghi log, tạo file theo phiên, hoặc đối chiếu output của skill với phiên
`${CLAUDE_EFFORT}`	Effort level hiện tại: `low`, `medium`, `high`, `xhigh`, hoặc `max`. Ultracode không là một mức riêng và báo về là `xhigh`
`${CLAUDE_SKILL_DIR}`	Thư mục chứa file `SKILL.md`. Với skill plugin, đây là thư mục con của skill trong plugin, không phải gốc plugin
`${CLAUDE_PROJECT_DIR}`	Thư mục gốc project. Cùng path mà hook và MCP server nhận được
`${CLAUDE_PLUGIN_ROOT}`	Thư mục cài đặt của plugin. Chỉ được thay thế trong skill plugin
`${CLAUDE_PLUGIN_DATA}`	Thư mục dữ liệu bền vững của plugin, sống sót qua các lần cập nhật plugin. Chỉ thay thế trong skill plugin

Claude Code thay thế ${CLAUDE_SKILL_DIR} và ${CLAUDE_PROJECT_DIR} ở hai chỗ: nội dung markdown của skill, và các rule Bash trong frontmatter allowed-tools. Dùng cùng một biến ở cả hai chỗ cho phép skill chạy một script đi kèm mà không bị hỏi quyền:

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---
Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

Nếu skill này cài ở ~/.claude/skills/render-chart/, cả hai chỗ ${CLAUDE_SKILL_DIR} đều nở ra thành thư mục đó. Rule allowed-tools khi ấy khớp chính xác lệnh mà phần thân skill bảo Claude chạy, nên script chạy không cần hỏi.

Tham số theo chỉ số dùng cách trích dẫn kiểu shell, nên bọc giá trị nhiều từ trong dấu nháy để truyền thành một tham số. Ví dụ /my-skill "hello world" second làm $0 nở thành hello world và $1 thành second. Placeholder $ARGUMENTS luôn nở thành toàn bộ chuỗi tham số như bạn gõ.

Một placeholder theo chỉ số không có tham số tương ứng, ví dụ $2 khi chỉ truyền một tham số, nằm nguyên trong nội dung. Một placeholder có tên khai trong arguments mà không có tham số khớp thì nở thành chuỗi rỗng.

Muốn có ký tự $ theo nghĩa đen trước một chữ số, trước ARGUMENTS, hoặc trước một tên tham số đã khai — ví dụ $1.00 trong văn xuôi — thì escape bằng dấu gạch chéo ngược: \$1.00. Dấu gạch chéo ngược trước bất kỳ $ nào khác được giữ nguyên. Escape này chỉ phủ các placeholder tham số; nó không ngăn được việc thay thế một biến ${CLAUDE_*}.

Ví dụ dùng chuỗi thay thế:

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

Thêm file hỗ trợ

Skill chứa được nhiều file trong thư mục của nó. Cách này giữ SKILL.md tập trung vào phần cốt lõi trong khi vẫn cho Claude truy cập tài liệu tham chiếu chi tiết chỉ khi cần.

my-skill/
├── SKILL.md (bắt buộc — tổng quan và điều hướng)
├── reference.md (tài liệu API chi tiết — nạp khi cần)
├── examples.md (ví dụ sử dụng — nạp khi cần)
└── scripts/
    └── helper.py (script tiện ích — được thực thi, không nạp vào context)

Tham chiếu các file hỗ trợ từ SKILL.md để Claude biết mỗi file chứa gì và khi nào nạp:

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Giữ SKILL.md dưới 500 dòng. Chuyển tài liệu tham chiếu chi tiết sang file riêng.

Tài nguyên bổ sung

Kiểm soát ai được gọi skill

Mặc định, cả bạn lẫn Claude đều gọi được mọi skill. Hai trường frontmatter giới hạn điều này:

disable-model-invocation: true — chỉ bạn gọi được. Dùng cho workflow có tác dụng phụ hoặc bạn muốn kiểm soát thời điểm, kiểu /commit, /deploy, /send-slack-message. Bạn không muốn Claude tự quyết deploy chỉ vì code trông có vẻ sẵn sàng.
user-invocable: false — chỉ Claude gọi được. Dùng cho kiến thức nền không phải là một hành động. Một skill legacy-system-context giải thích một hệ thống cũ hoạt động thế nào: Claude nên biết khi liên quan, nhưng /legacy-system-context không phải hành động có nghĩa cho user.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Nếu Claude vẫn cố gọi, Claude Code chặn lời gọi và chỉ dẫn nó không tái tạo các bước deploy bằng cách khác — nên hãy chờ Claude gợi ý bạn tự chạy /deploy.

Ảnh hưởng của hai trường lên việc gọi và nạp context:

Frontmatter	Bạn gọi được	Claude gọi được	Nạp vào context khi nào
(mặc định)	Có	Có	Description luôn trong context, nội dung đầy đủ nạp khi được gọi
`disable-model-invocation: true`	Có	Không	Description không trong context, nội dung đầy đủ nạp khi bạn gọi
`user-invocable: false`	Không	Có	Description luôn trong context, nội dung đầy đủ nạp khi được gọi

Ở phiên thường, description của skill nạp vào context để Claude biết có gì khả dụng, nhưng nội dung đầy đủ chỉ nạp khi được gọi. Subagent có skill nạp trước thì khác: nội dung đầy đủ được tiêm vào ngay lúc khởi động.

Vòng đời nội dung skill

Khi bạn hoặc Claude gọi một skill, nội dung SKILL.md đã render vào hội thoại như một tin nhắn duy nhất và nằm đó suốt phần còn lại của phiên. Tính bền vững này áp cho chỉ dẫn của skill, không áp cho quyền của nó: một grant allowed-tools hết hiệu lực khi bạn gửi tin nhắn kế tiếp.

Claude Code không đọc lại file skill ở các lượt sau — nên hãy viết hướng dẫn cần áp dụng suốt một task dưới dạng chỉ dẫn thường trực, chứ không phải các bước một lần.

Khi Claude gọi lại một skill mà nội dung render giống hệt bản đã có trong context, Claude Code thêm một ghi chú ngắn rằng skill đã nạp rồi, thay vì thêm bản thứ hai. Khi nội dung render khác — vì tham số đổi hoặc một lệnh context động cho output mới — Claude Code nối lại toàn bộ nội dung.

Auto-compaction mang các skill đã gọi đi tiếp trong một ngân sách token. Khi hội thoại bị tóm tắt để giải phóng context, Claude Code đính lại lần gọi gần nhất của mỗi skill sau bản tóm tắt, giữ 5.000 token đầu của mỗi cái. Các skill được đính lại chia chung ngân sách 25.000 token. Claude Code lấp ngân sách này bắt đầu từ skill được gọi gần nhất, nên skill cũ hơn có thể bị bỏ hẳn sau compaction nếu bạn đã gọi nhiều skill trong một phiên.

Nếu một skill có vẻ ngừng ảnh hưởng tới hành vi sau phản hồi đầu tiên, nội dung thường vẫn còn đó và model đang chọn tool hoặc cách tiếp cận khác. Hãy làm mạnh description và chỉ dẫn của skill, hoặc dùng hook để cưỡng chế hành vi một cách tất định. Nếu skill lớn hoặc bạn đã gọi vài skill khác sau nó, gọi lại nó sau compaction để khôi phục nội dung đầy đủ.

Tiền phê duyệt tool cho một skill

Trường allowed-tools cấp quyền cho các tool được liệt kê trong lượt gọi skill, để Claude dùng chúng mà không cần bạn duyệt. Grant hết hiệu lực khi bạn gửi tin nhắn kế tiếp, dù nội dung skill vẫn nằm trong context; gọi lại skill sẽ áp lại grant cho lượt đó.

Nó không hạn chế tool nào khả dụng: mọi tool vẫn gọi được, và permission settings của bạn vẫn chi phối các tool không được liệt kê. Muốn tiền phê duyệt cho cả phiên thay vì một lượt, hãy thêm allow rule vào permission settings.

Workspace trust không chặn trường này. Claude Code áp allowed-tools của một skill project bất cứ khi nào skill được gọi, kể cả trong một lượt chạy -p ở thư mục bạn chưa bao giờ tin tưởng. Một skill tự cấp cho mình quyền truy cập tool rất rộng được — nên hãy xem lại allowed-tools của các skill đã commit vào một repository trước khi bạn chạy Claude Code ở đó.

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Muốn gỡ tool khỏi kho khả dụng của Claude trong lúc skill hoạt động thì liệt kê chúng ở disallowed-tools. Hạn chế hết hiệu lực khi bạn gửi tin nhắn kế tiếp. Giống deny rule, trường này không gỡ được EndConversation khi vẫn còn tool khác.

Truyền tham số cho skill

Cả bạn lẫn Claude đều truyền tham số được khi gọi skill. Tham số có sẵn 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 thì Claude nhận được “Fix GitHub issue 123 following our coding standards…”.

Nếu bạn gọi một skill kèm tham số nhưng skill không chứa $ARGUMENTS, Claude Code nối ARGUMENTS: <your input> vào cuối nội dung skill để Claude vẫn thấy thứ bạn gõ.

Bạn cũng xếp chồng nhiều skill ở đầu một tin nhắn được. Gõ /write-tests /fix-issue 123 nạp cả hai skill và truyền phần text đuôi 123 làm $ARGUMENTS cho từng cái.

Claude Code nở skill đầu tiên cộng tối đa năm cái nữa xếp sau. Việc nở dừng ở token đầu tiên không phải một skill inline gọi được bởi user — nên một skill chạy dưới dạng subagent forked, ví dụ /code-review, hoặc một skill mà tham số của nó có thể tự bắt đầu bằng dấu gạch chéo, ví dụ /loop, cũng kết thúc chuỗi tại đó. Token đó và mọi thứ sau nó trở thành text tham số cho mọi skill đã nở.

Truy cập tham số theo vị trí bằng $ARGUMENTS[N] hoặc dạng ngắn $N:

---
name: migrate-component
description: Migrate a component from one framework to another
---
Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

Chạy /migrate-component SearchBar React Vue thay $ARGUMENTS[0] bằng SearchBar, $ARGUMENTS[1] bằng React, $ARGUMENTS[2] bằng Vue. Cùng skill đó viết bằng dạng ngắn $N:

---
name: migrate-component
description: Migrate a component from one framework to another
---
Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Pattern nâng cao

Inject context động

Cú pháp !`<command>` chạy lệnh shell trước khi nội dung skill được gửi tới Claude. Output của lệnh thay thế placeholder, nên Claude nhận dữ liệu thật chứ không phải bản thân lệnh. Claude Code không chạy các lệnh này trên máy bạn khi skill được đồng bộ từ tài khoản claude.ai.

Skill dưới đây tóm tắt một pull request bằng cách lấy dữ liệu PR sống qua GitHub CLI:

---
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...

Việc thay thế chạy đúng một lượt trên file gốc. Output của lệnh được chèn vào dưới dạng text thuần và không được quét lại để tìm placeholder tiếp theo — nên một lệnh không thể phát ra một placeholder cho lượt sau nở.

Dạng inline chỉ được nhận diện khi ! nằm ở đầu dòng hoặc ngay sau khoảng trắng. Nếu ! đi sau một ký tự khác, như trong KEY=!`cmd`, placeholder bị để nguyên dưới dạng text và lệnh không chạy.

Với lệnh nhiều dòng, dùng khối code mở bằng ```! thay cho dạng inline:

## Environment

```!
node --version
npm --version
git status --short
```

Muốn tắt hành vi này cho skill và custom command từ nguồn user, project, plugin hoặc thư mục bổ sung, đặt "disableSkillShellExecution": true trong settings. Mỗi lệnh sẽ được thay bằng [shell command execution disabled by policy] thay vì được chạy. Bundled skill và managed skill không bị ảnh hưởng. Setting này hữu ích nhất trong managed settings, nơi user không ghi đè được.

Muốn yêu cầu suy luận sâu hơn khi một skill chạy, chèn ultrathink vào bất kỳ đâu trong nội dung skill.

Lệnh được inject chạy thế nào

Claude Code chọn tool chạy lệnh inject từ khoá shell trong frontmatter và từ môi trường của bạn:

shell: powershell với PowerShell tool bật → lệnh chạy qua PowerShell tool.
shell: bash khi bash không có → lời gọi fail trước khi bất kỳ lệnh nào chạy. Xảy ra trên Windows không có Git Bash.
Mọi tổ hợp khác → lệnh chạy qua Bash tool khi bash có sẵn; khi không có thì chạy qua PowerShell tool.

Tool nào cũng chạy lệnh y như cách nó chạy lệnh shell của chính Claude, dùng chung thư mục làm việc, timeout và cách xử lý output:

Thư mục làm việc — Claude Code chạy mỗi lệnh ở thư mục làm việc hiện tại của shell phiên. Thư mục đó di chuyển khi Claude chạy cd. Dùng ${CLAUDE_SKILL_DIR} hoặc ${CLAUDE_PROJECT_DIR} cho những path phải giải ra giống nhau ở mọi lần.
stderr — với shell bash mặc định, Claude Code gộp stderr vào stdout. Mọi thứ lệnh ghi ra stderr đều xuất hiện trong text được inject.
Timeout — mỗi lệnh chạy dưới timeout mặc định 2 phút của Bash tool. Khi Bash tool đẩy một lệnh quá hạn xuống nền, skill vẫn render và text inject báo lại việc đó kèm tên background task. Với lệnh mà Bash tool không bao giờ tự đẩy xuống nền, Claude Code giết nó ở mốc timeout, và thất bại đó huỷ cả lời gọi.
Kích thước output — output vượt trần inline của Bash tool tới dưới dạng một đường dẫn file cộng một đoạn xem trước, không phải text bị cắt cụt.

Khi một lệnh inject thất bại

Một lệnh thất bại huỷ toàn bộ lời gọi skill, không chỉ placeholder của riêng nó. Claude không bao giờ thấy nội dung skill cho lần gọi đó. Thông báo huỷ hiện Shell command failed for pattern "...", kèm output của lệnh dưới nhãn [stderr].

Với shell bash mặc định, mọi exit code khác 0 đều tính là thất bại. Có đúng một ngoại lệ: Claude Code coi exit code 1 từ các lệnh tìm kiếm và so sánh là kết quả bình thường và vẫn inject output của chúng. Exit code từ 2 trở lên thì fail kể cả với những lệnh đó.

Nhóm lệnh được hưởng ngoại lệ phụ thuộc shell:

Shell bash mặc định: nhóm lệnh liệt kê ở mục Output limits của tools reference.
shell: powershell khi PowerShell tool bật: một nhóm khác, có grep và git diff nhưng không có find hay diff.

Với shell bash mặc định, hãy nối || true vào bất kỳ lệnh nào khác mà bạn dự đoán sẽ thoát với mã khác 0 — ví dụ một script kiểm tra thoát với mã 1 khi tìm thấy vấn đề.

Lệnh inject không bao giờ hỏi quyền. Khi kiểm tra quyền của một lệnh trả về bất cứ thứ gì khác allow, Claude Code huỷ lời gọi — kể cả với một rule mà bình thường sẽ hỏi bạn. Thông báo huỷ hiện Shell command permission check failed for pattern "...".

Muốn một lệnh không khớp rule khỏi huỷ lời gọi, hãy tiền phê duyệt nó bằng allowed-tools. Nhưng một ask hoặc deny rule khớp vẫn huỷ lời gọi bất kể allowed-tools.

Chạy skill trong subagent

Thêm context: fork vào frontmatter khi bạn muốn một skill chạy cô lập. Nội dung skill trở thành prompt điều khiển subagent. Nó không có quyền truy cập lịch sử hội thoại của bạn.

Subagent forked chạy ở nền: bạn làm việc tiếp trong lúc nó chạy, và kết quả về tới hội thoại khi nó xong. Đặt background: false để chờ kết quả ngay trong lượt gọi skill.

Claude Code cũng chờ kết quả ngay cả khi skill không đặt background: false, trong bốn trường hợp:

Ở chế độ non-interactive, với flag -p hoặc Agent SDK
Khi bạn đặt CLAUDE_CODE_DISABLE_BACKGROUND_TASKS thành 1
Khi bạn gọi một forked skill trong lúc một lần gọi trước của chính skill đó vẫn đang chạy
Khi một scheduled task kích hoạt với skill làm prompt

Một fork chạy ở nền cũng chạy với bộ tool hẹp hơn áp cho background subagent. Nếu các bước trong skill của bạn phụ thuộc một tool ngoài bộ đó, đặt background: false để giữ bộ tool đầy đủ.

Một forked skill chạy ở nền áp thay đổi của nó ngoài checkpoint của phiên bạn, nên /rewind không hoàn tác được; dùng git để revert.

context: fork chỉ có nghĩa với skill có chỉ dẫn tường minh. Nếu skill của bạn chứa hướng dẫn kiểu “use these API conventions” mà không kèm một task, subagent nhận được hướng dẫn nhưng không có prompt hành động, và trả về mà không có output có nghĩa.

Skill và subagent phối hợp theo hai chiều:

Cách tiếp cận	System prompt	Task	Còn nạp thêm
Skill có `context: fork`	Từ loại agent	Nội dung `SKILL.md`	`CLAUDE.md`, trừ khi agent là `Explore` hoặc `Plan`
Subagent có trường `skills`	Phần thân markdown của subagent	Tin nhắn giao việc của Claude	Skill nạp trước + `CLAUDE.md`

Với context: fork, bạn viết task trong skill và chọn loại agent để thực thi nó. Agent dựng sẵn Explore và Plan bỏ qua CLAUDE.md và git status để giữ context nhỏ, nên một forked skill dùng agent: Explore chỉ thấy nội dung SKILL.md và system prompt của chính agent đó.

Ví dụ: skill nghiên cứu dùng agent Explore

---
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

Khi skill này chạy:

Một context cô lập mới được tạo
Subagent nhận nội dung skill làm prompt của nó
Trường agent quyết định môi trường thực thi (model, tool, và permission)
Subagent tóm tắt kết quả và trả về hội thoại chính khi xong

Trường agent chỉ định cấu hình subagent nào được dùng. Lựa chọn gồm các agent dựng sẵn (Explore, Plan, general-purpose) hoặc bất kỳ subagent tuỳ biến nào trong .claude/agents/. Bỏ trống thì dùng general-purpose.

Giới hạn quyền truy cập skill của Claude

Mặc định Claude gọi được mọi skill không đặt disable-model-invocation: true. Một vài built-in command cũng khả dụng qua tool Skill, gồm /init và /security-review; các built-in command khác như /compact thì không.

Ba cách kiểm soát skill nào Claude gọi được.

Tắt mọi skill bằng cách deny tool Skill trong /permissions:

# Thêm vào deny rules:
Skill

Cho phép hoặc chặn từng skill bằng permission rule:

# Chỉ cho phép một số skill
Skill(commit)
Skill(review-pr *)

# Chặn một số skill
Skill(deploy *)

Cú pháp permission: Skill(name) cho khớp chính xác, Skill(name *) cho khớp tiền tố với tham số bất kỳ.

Giấu từng skill bằng cách thêm disable-model-invocation: true vào frontmatter — cách này gỡ hẳn skill khỏi context của Claude.

Với user-invocable: false, bạn không gọi được skill nhưng Claude vẫn gọi được. Muốn ngăn Claude gọi nó qua tool Skill, phải đặt disable-model-invocation: true.

Ghi đè mức hiển thị của skill từ settings

Setting skillOverrides kiểm soát mức hiển thị của skill từ settings thay vì từ frontmatter của chính skill. Dùng nó cho các skill mà bạn không muốn sửa SKILL.md, ví dụ skill đã commit vào một repo dùng chung. Menu /skills ghi setting này hộ bạn: chọn một skill, bấm Space để xoay vòng trạng thái, rồi Enter để lưu vào .claude/settings.local.json.

Mỗi khoá là tên một skill và mỗi giá trị là một trong bốn trạng thái:

Giá trị	Liệt kê cho Claude	Trong menu `/`
`"on"`	Tên và description	Có
`"name-only"`	Chỉ tên	Có
`"user-invocable-only"`	Ẩn	Có
`"off"`	Ẩn	Ẩn

Menu /skills gắn nhãn trạng thái "user-invocable-only" là user-only.

Giá trị "off" cũng giấu skill khỏi danh sách lệnh công bố cho Remote Control client và cho Agent SDK caller, ngoài menu / ở terminal. Gọi một skill bị giấu bằng tên đầy đủ vẫn trả về lỗi skillOverrides chứ không chạy nó.

Một skill vắng mặt trong skillOverrides được coi là "on":

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Skill của plugin không chịu ảnh hưởng của skillOverrides. Quản lý chúng qua /plugin.

Đánh giá và cải tiến một skill

Thấy một skill kích hoạt chỉ cho biết Claude tìm ra nó, không cho biết nó làm đúng thứ bạn định. Muốn biết một skill có hoạt động không, hãy đo hai thứ riêng biệt: Claude có gọi nó ở đúng những prompt cần gọi không, và khi gọi thì output có khớp mong đợi không.

Cách kiểm cho cả hai là so sánh với baseline. Thu thập vài prompt thực tế, chạy từng cái trong một phiên sạch với skill khả dụng, rồi chạy lại với skill bị tắt, và so kết quả.

Phiên sạch là điều kiện bắt buộc, vì context còn sót lại từ lúc bạn viết skill sẽ che mất các lỗ hổng trong chỉ dẫn đã viết ra.

Chạy eval bằng skill-creator

Plugin skill-creator tự động hoá vòng so sánh này ngay trong Claude Code:

/plugin install skill-creator@claude-plugins-official

Nếu cài fail, khớp theo thông báo Claude Code đưa ra:

Marketplace "claude-plugins-official" not found → thêm marketplace bằng /plugin marketplace add anthropics/claude-plugins-official rồi thử lại.
Plugin không tìm thấy trong marketplace → kiểm tra lại tên plugin.

Nếu bản tóm tắt cài đặt báo Run /reload-plugins to activate., chạy lệnh đó. Rồi bảo Claude đánh giá một skill sẵn có, ví dụ “evaluate my summarize-changes skill with skill-creator”. Plugin dẫn bạn qua việc viết test case và chạy vòng lặp:

Test case — lưu prompt, file input và hành vi mong đợi vào evals/evals.json trong thư mục skill
Chạy cô lập — sinh một subagent cho mỗi test case để mỗi lượt chạy bắt đầu với context sạch, và ghi lại số token cùng thời gian
Chấm điểm — kiểm từng khẳng định với output rồi ghi pass hoặc fail kèm bằng chứng vào grading.json
Benchmark — tổng hợp tỉ lệ pass, thời gian và token cho hai trường hợp có skill và không skill vào benchmark.json, để bạn so mức cải thiện tỉ lệ pass với chi phí token và thời gian
So phiên bản — chạy A/B mù giữa hai phiên bản của skill để bạn xác nhận một lần sửa là cải thiện thật trước khi commit
Tinh chỉnh description — sinh các prompt nên kích hoạt và không nên kích hoạt, đo tỉ lệ trúng, và đề xuất sửa description khi skill kích hoạt nhầm yêu cầu
Trình xem review — mở một report HTML để bạn xem từng output và ghi phản hồi định tính cho vòng lặp sau đọc

Chia sẻ skill

Skill phân phối được ở nhiều phạm vi tuỳ đối tượng:

Skill project — commit .claude/skills/ vào version control
Plugin — tạo một thư mục skills/ trong plugin của bạn
Managed — triển khai toàn tổ chức qua managed settings

Sinh output trực quan

Skill đóng gói và chạy được script ở bất kỳ ngôn ngữ nào, cho Claude những năng lực vượt xa thứ làm được trong một prompt đơn. Một pattern mạnh là sinh output trực quan: file HTML tương tác mở được trong trình duyệt để khám phá dữ liệu, debug, hoặc tạo báo cáo.

Ví dụ dưới đây tạo một codebase explorer: cây thư mục tương tác gập mở được, thấy ngay kích thước file, phân biệt loại file bằng màu.

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

Lưu vào ~/.claude/skills/codebase-visualizer/SKILL.md. Đường dẫn script dùng ${CLAUDE_SKILL_DIR} để nó giải đúng dù skill được cài ở cấp cá nhân, project hay plugin:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

Rồi lưu script Python vào ~/.claude/skills/codebase-visualizer/scripts/visualize.py. Script quét cây thư mục và sinh một file HTML tự chứa gồm:

Một sidebar tóm tắt hiện số file, số thư mục, tổng kích thước, và số loại file
Một biểu đồ cột phân rã codebase theo loại file (8 loại lớn nhất theo dung lượng)
Một cây gập mở được, có chỉ báo màu theo loại file

Script cần Python 3 nhưng chỉ dùng thư viện dựng sẵn, nên không phải cài gói nào. Mã nguồn đầy đủ của script nằm ở trang docs gốc — nó dài khoảng 150 dòng nên tôi không chép lại ở đây; hãy copy trực tiếp từ nguồn để tránh sai lệch.

Để thử, mở Claude Code ở một project bất kỳ rồi hỏi “Visualize this codebase.” Claude chạy script, script in ra đường dẫn file được sinh, ví dụ Generated /path/to/codebase-map.html, và mở nó trong trình duyệt. Nếu bạn làm việc trong môi trường headless không có trình duyệt, đường dẫn được in ra chính là bằng chứng script chạy thành công.

Pattern này áp cho mọi loại output trực quan: đồ thị dependency, báo cáo test coverage, tài liệu API, hoặc sơ đồ schema database. Script đi kèm làm phần việc, còn Claude lo phần điều phối.

Troubleshooting

Skill không kích hoạt

Nếu Claude không dùng skill của bạn khi lẽ ra phải dùng:

Kiểm tra description có chứa từ khoá mà user sẽ nói một cách tự nhiên không
Xác nhận skill xuất hiện khi hỏi What skills are available?
Thử diễn đạt lại yêu cầu cho khớp description hơn
Gọi thẳng bằng /skill-name nếu skill cho phép user gọi

Nếu YAML frontmatter bị lỗi cú pháp, Claude Code nạp phần thân skill với metadata rỗng — nên /skill-name vẫn chạy nhưng Claude không có description nào để khớp. Chạy với --debug để thấy lỗi parse.

Skill kích hoạt quá thường xuyên

Làm description cụ thể hơn
Thêm disable-model-invocation: true nếu bạn chỉ muốn gọi tay

Description của skill bị cắt cụt

Claude Code nạp một danh sách tên và description của skill vào context để Claude biết có gì khả dụng. Danh sách luôn chứa mọi tên skill, nhưng nếu bạn có nhiều skill, Claude Code rút ngắn description cho vừa ngân sách ký tự — và điều đó có thể cắt mất chính những từ khoá Claude cần để khớp yêu cầu của bạn.

Ngân sách này bằng 1% context window của model. Khi danh sách tràn, Claude Code bỏ description bắt đầu từ những skill bạn ít gọi nhất, nên các skill bạn dùng nhiều giữ được text đầy đủ.

Chạy /doctor để ước lượng chi phí context của danh sách và biết cái nào đóng góp nhiều nhất. Khi danh sách vượt ngân sách, Claude Code cũng ghi một cảnh báo vào debug log, xem được bằng --debug.

Dòng Skills trong /context báo kích thước của danh sách sau khi ngân sách được áp, nên nó khớp với thứ model thực sự nhận.

Ba cách xử lý:

Nâng ngân sách — đặt setting skillListingBudgetFraction (ví dụ 0.02 là 2%), hoặc biến môi trường SLASH_COMMAND_TOOL_CHAR_BUDGET cho một số ký tự cố định.
Giải phóng ngân sách cho skill khác — đặt các mục ưu tiên thấp thành "name-only" trong skillOverrides để chúng chỉ liệt kê tên, không kèm description.
Cắt gọt ngay tại nguồn — tỉa text description và when_to_use, đặt use case quan trọng nhất lên trước, vì text gộp của mỗi mục bị giới hạn ở 1.536 ký tự bất kể ngân sách. Giới hạn này chỉnh được bằng skillListingMaxDescChars.

Tài nguyên liên quan

Debug your configuration — chẩn đoán vì sao một skill không xuất hiện hoặc không kích hoạt
Evaluating skill output quality — định dạng file eval và quy trình cải tiến trên agentskills.io
Skill authoring best practices — hướng dẫn viết skill áp dụng cho mọi sản phẩm Claude
Subagents — giao việc cho agent chuyên biệt (phần 16)
Plugins — đóng gói và phân phối skill cùng các extension khác
Hooks — tự động hoá quy trình quanh sự kiện tool
Memory — quản lý file CLAUDE.md cho ngữ cảnh bền vững (phần 4)
Commands — tham chiếu built-in command và bundled skill (phần 6)
Permissions — kiểm soát quyền truy cập tool và skill (phần 7)

Nguồn

Extend Claude with skills

Docs gốc cập nhật thường xuyên; khi có mâu thuẫn, tin bản tiếng Anh.