3.2 Custom Slash Commands and Skills

Những gì cần nắm

Custom command và skill đã được gộp thành một hệ thống duy nhất: Skills system. Hai vị trí .claude/skills/ và .claude/commands/ đều tạo ra /command hoạt động y hệt nhau, nhưng cấu trúc file khác nhau. Skill là một thư mục chứa file SKILL.md (.claude/skills/deploy/SKILL.md); command là một file Markdown phẳng (.claude/commands/deploy.md). Một file phẳng đặt thẳng vào .claude/skills/ không tạo ra command nào. .claude/skills/ là vị trí chính thức. .claude/commands/ vẫn chạy để tương thích ngược.

Hệ thống Skills hợp nhất

Cả hai path đều cho ra cùng một kết quả — một /command mà developer gọi được:

• .claude/commands/deploy.md tạo ra /deploy — file phẳng, tên file thành tên command
• .claude/skills/deploy/SKILL.md cũng tạo ra /deploy — mỗi skill một thư mục, đặt tên theo command, bên trong bắt buộc có SKILL.md làm entrypoint

Path skills là lựa chọn được khuyến nghị vì nó có thêm những thứ mà alias commands không có: một thư mục file phụ trợ nằm cạnh SKILL.md, khả năng tự phát hiện để Claude load skill khi khớp ý định của bạn, và quyền ưu tiên khi skill và command trùng tên (skill thắng). Cả hai path đều hỗ trợ cùng bộ YAML frontmatter (context: fork, allowed-tools, argument-hint) và đều cho ra cùng một /command, nên các file .claude/commands/ hiện có vẫn chạy nguyên như cũ.

Hai cấp scoping

Project-scoped (chia sẻ qua git):

Đặt skill trong .claude/skills/ (chính thức) hoặc .claude/commands/ (alias) bên trong repository. Cả hai đều được version-control và chia sẻ qua git. Mọi developer clone hay pull repository đều tự động có những command này. Dùng cho workflow chung của team: /review, /deploy-check, /lint, /migration-guide.

<!-- .claude/commands/review.md — creates /review -->
Review the staged changes against our team checklist:
1. Check error handling patterns
2. Verify test coverage for new functions
3. Confirm API naming conventions
4. Flag any hardcoded credentials or secrets

User-scoped (cá nhân):

Đặt skill trong ~/.claude/skills/ (chính thức) hoặc ~/.claude/commands/ (alias). Những file này là cá nhân, không được version-control hay chia sẻ. Dùng cho workflow năng suất riêng mà người khác trong team không cần.

Ý chính

Mô hình scoping nhất quán xuyên suốt Claude Code: cấp project (.claude/) chia sẻ qua git; cấp user (~/.claude/) là cá nhân. Điều này đúng với CLAUDE.md, với commands/skills, và với rules. Thuộc mô hình này đi — nó xuất hiện khắp Domain 3. Cả .claude/commands/ lẫn .claude/skills/ đều project-scoped và tạo ra cùng những command; .claude/skills/ là path chính thức, nhiều tính năng hơn. Nhưng phải nhớ đúng hình dạng file: skill là thư mục có SKILL.md bên trong; command là file .md phẳng.

Frontmatter của skill: cấu hình tuỳ chọn

Skill trong .claude/skills/ với file SKILL.md hỗ trợ cấu hình YAML frontmatter tuỳ chọn. Frontmatter này cũng dùng được với file .claude/commands/, nhưng .claude/skills/ mới là vị trí chính thức cho skill có cấu hình. Skill là workflow riêng theo tác vụ, được gọi theo nhu cầu — chúng không tự load như CLAUDE.md.

Ba tuỳ chọn frontmatter trọng yếu:

context: fork

Chạy skill trong context sub-agent tách biệt. Toàn bộ output dài dòng bị giữ lại trong fork, hội thoại chính vẫn sạch. Cần thiết cho:

• Phân tích codebase (sinh ra rất nhiều file listing và trích đoạn code)
• Brainstorming (sinh ra nhiều phương án và đánh giá)
• Bất kỳ tác vụ nào cho ra output ồn, mang tính thăm dò

Không có context: fork, output của skill đổ thẳng vào hội thoại chính và ăn token của context window. Với skill dài dòng, điều này làm giảm chất lượng các response sau đó.

Frontmatter nằm ở đầu file SKILL.md của skill. Với skill gọi bằng /analyse-feature, file đó nằm ở .claude/skills/analyse-feature/SKILL.md:

---
description: "Analyse a feature area of the codebase and report structure, patterns and risks"
context: fork
allowed-tools:
  - Read
  - Grep
  - Glob
argument-hint: "Provide a feature description or area of the codebase to analyse"
---

Dòng description không nằm trong ba field mà đề thi hỏi. Nhưng bỏ nó khỏi một skill thật thì Claude chẳng có gì để đối chiếu với yêu cầu của bạn, nên skill chỉ chạy khi bạn tự gõ /analyse-feature.

allowed-tools

Duyệt trước các tool được liệt kê để Claude dùng mà không hỏi permission trong lúc skill đang chạy. Nó không giới hạn tool nào khả dụng: mọi tool khác vẫn gọi được, và permission settings thông thường vẫn chi phối những gì không có trong danh sách. Dùng nó để một workflow đáng tin cậy chạy liền mạch, không dừng lại hỏi ở từng lần gọi.

Thực tế hiện nay

Exam guide (v1.0) mô tả allowed-tools là giới hạn quyền truy cập tool của skill, và đó là đáp án được chấm: nếu câu hỏi hỏi field này làm gì, trả lời “giới hạn”. Hành vi duyệt trước ở trên mới là thứ Claude Code hiện tại (tháng 9/2026) thực sự làm. Phần quick reference của Domain 3 và prompt Concept Check của bài này cũng mang cùng ghi chú hai phần như vậy.

---
allowed-tools:
  - Read
  - Grep
  - Glob
---

Muốn loại bỏ tool khỏi kho tool của Claude trong lúc skill chạy, tức ranh giới bảo mật thật sự, hãy liệt kê chúng trong disallowed-tools, hoặc thêm deny rule trong permission settings.

argument-hint

Một gợi ý hiện ra lúc autocomplete để cho biết skill mong đợi tham số nào. Nó cải thiện trải nghiệm developer bằng cách nói rõ input thay vì bắt người dùng nhớ skill cần gì. Đây là một nhãn, không phải prompt tương tác: gọi skill mà không truyền tham số sẽ không khiến nó dừng lại hỏi.

Thực tế hiện nay

Exam guide v1.0 mô tả argument-hint là hỏi developer các tham số bắt buộc khi họ gọi skill mà không có tham số, và đó là đáp án đề thi mong đợi. Tính đến 14/8/2026, tài liệu frontmatter của skills định nghĩa nó là “Hint shown during autocomplete to indicate expected arguments”. Không có câu hỏi nào trong bank hay pack chấm theo hành vi này, nên bài tập ở trên dạy theo hành vi hiện tại.

---
argument-hint: "Specify the module path to analyse (e.g., src/api/auth)"
---

Thực tế hiện nay: description mới là field làm nhiều việc nhất

Ba field trên là những cái exam guide (v1.0) nêu tên, và là thứ một câu hỏi sẽ chấm. Danh sách field thật dài hơn nhiều, và cái bạn cần trước nhất lại không nằm trong danh sách của guide: description. Đó là thứ Claude đọc để quyết định một skill có phù hợp với điều bạn vừa hỏi hay không, nên skill không có description tử tế thì chỉ chạy khi bạn tự gõ /name. Tài liệu đánh dấu nó là Recommended chứ không bắt buộc: bỏ trống thì Claude Code lấy đoạn đầu tiên trong thân skill, và bản tóm tắt đó thường tệ hơn cái bạn tự viết. Cũng đang có thật: disallowed-tools, disable-model-invocation, model, effort và when_to_use. (Tài liệu skills của Claude Code, đã đối chiếu tháng 8/2026.)

Skill so với CLAUDE.md: phân biệt trọng yếu

Phân biệt này được hỏi trực tiếp trong đề thi:

• Skill = workflow theo nhu cầu, riêng cho từng tác vụ. Phần description luôn nằm trong context để Claude biết chúng tồn tại, nhưng toàn bộ thân skill chỉ load khi được gọi. Việc gọi có thể tường minh (/skill-name) hoặc tự động: Claude nhặt những skill có description khớp ý định của user, hoặc skill có field frontmatter paths khi bạn làm việc trên file khớp. Skill có disable-model-invocation: true bắt buộc user phải gọi tường minh.
• CLAUDE.md = chuẩn phổ quát, luôn được load. Áp dụng tự động cho mọi session, không cần bước gọi.

Quy tắc: đừng đưa quy trình riêng theo tác vụ vào CLAUDE.md. Đừng đưa tài liệu tham chiếu luôn-bật vào skill.

Naming convention API cần áp dụng cho mọi lần sinh code thì thuộc về CLAUDE.md (hoặc .claude/rules/). Một workflow phân tích codebase nhiều bước mà developer thỉnh thoảng mới chạy thì thuộc về skill. Với convention áp cho một loại file cụ thể — như file test — .claude/rules/ path-scoped là lựa chọn phù hợp nhất vì chúng load thành context luôn-bật đi kèm file khớp.

Tuỳ biến skill cá nhân

Tạo bản riêng trong ~/.claude/skills/ (hoặc ~/.claude/commands/) với tên khác để không ảnh hưởng đồng nghiệp. Nếu team có skill chuẩn /analyse nhưng bạn thích bản chi tiết hơn, hãy tạo bản của bạn trong ~/.claude/skills/ với tên khác (ví dụ /deep-analyse). Skill cá nhân của bạn không override hay đụng độ bản của team.

Đặt custom command ở đâu: bảng tra nhanh

Nhu cầu	Vị trí chính thức	Cũng chạy được	Scoping
Command dùng chung cả team	.claude/skills/<name>/SKILL.md	.claude/commands/<name>.md	Project (chia sẻ qua git)
Command dùng chung cả team, có cấu hình frontmatter	.claude/skills/<name>/SKILL.md	.claude/commands/<name>.md	Project (chia sẻ qua git)
Command cá nhân	~/.claude/skills/<name>/SKILL.md	~/.claude/commands/<name>.md	User (không chia sẻ)
Chuẩn phổ quát	.claude/CLAUDE.md hoặc CLAUDE.md ở root	—	Project (luôn được load)
Sở thích cá nhân	~/.claude/CLAUDE.md	—	User (không chia sẻ)

Bẫy thi

Bẫy thi

Tạo file Markdown phẳng ngay trong .claude/skills/ (ví dụ .claude/skills/review.md) rồi mong có command /review

Hai path tạo ra cùng những command nhưng cấu trúc file khác nhau. Skill là một thư mục chứa entrypoint SKILL.md (.claude/skills/review/SKILL.md); file .md phẳng chỉ tạo command dưới .claude/commands/ (.claude/commands/review.md). File rời thả thẳng vào .claude/skills/ sẽ không được nhặt.

Bẫy thi

Đặt command dùng chung cả team vào path user-scoped (~/.claude/commands/ hoặc ~/.claude/skills/) thay vì path project-scoped

Path user-scoped (~/.claude/commands/ và ~/.claude/skills/) là cá nhân và không được version-control. Command của team, cần có sẵn cho mọi người ngay khi clone, phải nằm trong path project-scoped (.claude/skills/ hoặc .claude/commands/) bên trong repository. Cả hai path project-scoped tạo ra cùng những command; .claude/skills/ là vị trí chính thức, nhiều tính năng hơn.

Bẫy thi

Nghĩ skill hành xử như CLAUDE.md để làm hướng dẫn luôn-bật

Skill load theo nhu cầu như workflow dạng tác vụ, không phải context luôn hiện diện. Claude có thể tự gọi một skill khi prompt khớp description của skill (hoặc khi skill có paths khớp file đang edit), nhưng skill vẫn load như một đơn vị được gọi riêng chứ không định hình mọi session theo mặc định. CLAUDE.md và .claude/rules/ tự load vào context cho mọi session (hoặc mọi file khớp, với rule path-scoped). Nếu câu hỏi nói về convention luôn-bật áp cho mọi lần edit, đáp án là CLAUDE.md hoặc .claude/rules/, không phải skill.

Bẫy thi

Không biết khi nào dùng context: fork

context: fork cách ly output dài dòng của skill khỏi hội thoại chính. Không có nó, output brainstorming hay phân tích codebase làm ô nhiễm context window. Đề thi sẽ đưa tình huống output dài dòng làm rối hội thoại chính — cách sửa là context: fork.

Bẫy thi

Nhét workflow riêng theo tác vụ vào CLAUDE.md

CLAUDE.md dành cho chuẩn phổ quát luôn được load. Quy trình riêng theo tác vụ (workflow code review, routine phân tích, template brainstorming) thuộc về skill, được gọi theo nhu cầu.

Tình huống luyện tập

Một team muốn command /review có sẵn cho mọi người clone repository. Một developer cũng muốn skill /brainstorm cá nhân, sinh ra output phân tích codebase dài dòng mà không làm rối hội thoại chính. Mỗi thứ nên tạo ở đâu và skill cần cấu hình gì?

• A. Tạo cả hai trong .claude/commands/ để chúng đi theo repository, cho skill brainstorm frontmatter context: fork để cách ly
• B. Cả hai trong ~/.claude/commands/ kèm ghi chú trong README bảo mọi developer copy hai file vào setup local của mình
• C. /review viết trong CLAUDE.md dưới dạng quy trình có tài liệu, còn /brainstorm trong .claude/skills/ chỉ kèm giới hạn allowed-tools của nó
• D. /review trong .claude/commands/ để chia sẻ cho team; /brainstorm là ~/.claude/skills/brainstorm/SKILL.md với frontmatter context: fork

Đáp án & giải thích

Đúng: D

• A — Skill /brainstorm là cá nhân (cả team không cần), nên đặt nó vào .claude/commands/ project-scoped là chia sẻ thừa. Skill cá nhân thuộc về ~/.claude/skills/, dưới dạng một thư mục có tên với SKILL.md bên trong.
• B — ~/.claude/commands/ là user-scoped và không chia sẻ qua version control. Bắt copy thủ công làm hỏng luôn mục đích của cấu hình project-scoped và tạo gánh nặng bảo trì.
• C — CLAUDE.md dành cho chuẩn luôn được load, không phải để định nghĩa command. Command cần file riêng. Skill brainstorm cần đúng context: fork để cách ly output, không phải chỉ giới hạn tool.
• D — /review cần project-scoped (.claude/commands/) để chia sẻ qua version control. /brainstorm là cá nhân nên nằm dưới ~/.claude/skills/ như một thư mục riêng có SKILL.md bên trong, không bao giờ là file .md rời. context: fork cách ly output phân tích dài dòng khỏi hội thoại chính.

Nguồn

• Claude Code Skills Documentation (custom slash command là một phần của hệ thống Skills hợp nhất) — Anthropic
• Claude Certified Architect Foundations Exam Guide — Task Statement 3.2 — Anthropic

Exam Simulator

Năm câu trắc nghiệm theo format đề thi về Custom Slash Commands and Skills. Chọn đáp án trước, rồi mở phần giải thích.

Câu 1

Một team muốn command /review có sẵn cho mọi người clone repository. Một developer cũng muốn skill /brainstorm cá nhân, sinh ra output phân tích codebase dài dòng mà không làm rối hội thoại chính. Mỗi thứ nên tạo ở đâu và skill cần cấu hình gì?

• A. /review trong .claude/commands/ để chia sẻ cho team; /brainstorm là SKILL.md trong ~/.claude/skills/ với frontmatter context: fork
• B. Cả hai trong .claude/commands/, skill brainstorm dùng context: fork
• C. /review trong CLAUDE.md dưới dạng quy trình có tài liệu; /brainstorm trong .claude/skills/ chỉ với giới hạn allowed-tools
• D. Cả hai trong ~/.claude/commands/ kèm hướng dẫn cho từng developer tự copy về máy

Đáp án & giải thích

Đúng: A

• A đúng vì: /review cần project-scoped (.claude/commands/) để chia sẻ qua version control. /brainstorm là cá nhân nên nằm trong ~/.claude/skills/. context: fork cách ly output phân tích dài dòng khỏi hội thoại chính.
• B sai vì: Skill /brainstorm là cá nhân (cả team không cần), nên đặt nó vào .claude/commands/ project-scoped là chia sẻ thừa.
• C sai vì: CLAUDE.md dành cho chuẩn luôn được load, không phải để định nghĩa command. Skill brainstorm cần context: fork để cách ly output, không phải chỉ giới hạn tool.
• D sai vì: ~/.claude/commands/ là user-scoped và không chia sẻ qua version control. Bắt copy thủ công làm hỏng mục đích của cấu hình project-scoped.

Câu 2

Một developer tạo skill làm phân tích codebase. Trong lúc chạy, skill sinh ra hàng loạt file listing, dependency graph và trích đoạn code lấp đầy context của hội thoại chính. Cấu hình frontmatter nào xử lý được chuyện này?

• A. allowed-tools: [Read, Grep, Glob] để hạn chế lượng dữ liệu truy cập
• B. output-limit: 1000 để chặn số token sinh ra
• C. argument-hint: “Specify a narrow scope” để giảm khối lượng phân tích
• D. context: fork để cách ly output dài dòng của skill khỏi hội thoại chính

Đáp án & giải thích

Đúng: D

• A sai vì: allowed-tools chi phối quyền truy cập tool (theo cách guide diễn đạt là giới hạn; Claude Code hiện tại thì duyệt trước các tool được liệt kê), không phải khối lượng output. Skill vẫn sinh ra output dài dòng bằng những tool được phép.
• B sai vì: output-limit không phải tuỳ chọn frontmatter hợp lệ của SKILL.md. Tuỳ chọn này không tồn tại.
• C sai vì: argument-hint hỏi tham số đầu vào. Nó không điều khiển khối lượng output. Kể cả với phạm vi hẹp, phân tích vẫn có thể ra output dài dòng.
• D đúng vì: context: fork chạy skill trong một sub-agent tách biệt. Toàn bộ output dài dòng bị giữ lại. Hội thoại chính chỉ nhận bản tóm tắt, giữ context window sạch cho công việc tiếp theo.

Câu 3

Naming convention API phải được áp dụng nhất quán cho mọi tác vụ sinh code trong project. Nên cấu hình những convention này ở đâu?

• A. Trong một skill tại .claude/skills/api-naming/SKILL.md
• B. Trong .claude/CLAUDE.md cấp project hoặc một file .claude/rules/
• C. Trong ~/.claude/commands/api-naming.md của từng developer
• D. Trong một pre-commit hook kiểm tra naming sau khi sinh code

Đáp án & giải thích

Đúng: B

• A sai vì: Skill chạy theo nhu cầu và phải được gọi tường minh. Developer sẽ phải gọi skill trước mỗi lần sinh code. Chuẩn phổ quát cần áp dụng tự động thì thuộc về CLAUDE.md.
• B đúng vì: CLAUDE.md và file .claude/rules/ luôn được load, áp dụng tự động cho mọi session. Chuẩn phổ quát cần được thực thi nhất quán thì nằm ở đây.
• C sai vì: Command user-scoped là cá nhân và không chia sẻ. Mỗi developer phải cấu hình riêng, và người mới vào team sẽ không nhận được gì.
• D sai vì: Pre-commit hook kiểm tra sau khi việc đã rồi, không phải trong lúc sinh code. Convention cần dẫn dắt việc sinh code theo thời gian thực qua CLAUDE.md.

Câu 4

Một team có skill chuẩn /analyse trong .claude/skills/. Một developer muốn phiên bản chi tiết hơn cho riêng mình. Cách làm đúng là gì?

• A. Sửa .claude/skills/analyse/SKILL.md của team để thêm cờ verbose mode
• B. Override skill của team bằng cách tạo ~/.claude/skills/analyse/SKILL.md cùng tên
• C. Tạo bản cá nhân tại ~/.claude/skills/deep-analyse/SKILL.md với tên khác
• D. Thêm hướng dẫn output chi tiết vào ~/.claude/CLAUDE.md của developer đó

Đáp án & giải thích

Đúng: C

• A sai vì: Sửa skill của team ảnh hưởng tới mọi người. Developer muốn bản riêng, không phải thay đổi cho cả team.
• B sai vì: Dùng cùng tên có thể gây đụng độ hoặc precedence khó đoán giữa vị trí skill của project và của user.
• C đúng vì: Skill cá nhân nằm trong ~/.claude/skills/ với tên khác để không đụng skill của team. Developer có bản chi tiết của mình mà không ảnh hưởng đồng nghiệp.
• D sai vì: CLAUDE.md dành cho chuẩn phổ quát luôn được load, không phải để cấu hình output của một skill.

Câu 5

Một developer mới tạo slash command tại ~/.claude/commands/deploy-check.md. Họ commit và push thay đổi nhưng đồng nghiệp không tìm thấy command /deploy-check. Vì sao?

• A. Nó nằm trong ~/.claude/commands/, bên ngoài repository
• B. Đồng nghiệp cần chạy /memory để load command mới
• C. File command cần YAML frontmatter thì mới được nhận diện
• D. Slash command chỉ hoạt động ở interactive mode, không chạy trong môi trường CI của đồng nghiệp

Đáp án & giải thích

Đúng: A

• A đúng vì: ~/.claude/commands/ nằm trong home directory của user, ngoài mọi repository. Nó không được version-control hay chia sẻ qua git. Với command dùng chung cả team, file phải nằm trong path project-scoped (.claude/commands/ hoặc .claude/skills/) bên trong repository.
• B sai vì: /memory là công cụ chẩn đoán cho cấu hình CLAUDE.md, không phải cơ chế load command.
• C sai vì: File command không bắt buộc có YAML frontmatter. Chính tên file định nghĩa tên command.
• D sai vì: Slash command hoạt động ở interactive mode với mọi user. Vấn đề là vị trí file, không phải chế độ chạy.