Tạo slash command và skill cho Claude Code

Trong Claude Code, gõ / là ra danh sách lệnh. Ngoài các lệnh có sẵn, bạn có thể tự tạo lệnh cho những việc nhóm làm đi làm lại: review code theo checklist, tạo một endpoint mới theo mẫu, phân tích một module.

Bài này giúp bạn trả lời: đặt lệnh ở đâu để cả nhóm cùng có, cấu hình nó thế nào, và khi nào nên viết thành skill thay vì ghi vào CLAUDE.md?

Ví dụ xuyên suốt: nhóm làm app quản lý kho cho chuỗi siêu thị mini

Linh là tech lead của nhóm làm app quản lý kho. Linh muốn có mấy lệnh cho cả nhóm:

1. /review: review code theo checklist của nhóm (kiểm quyền truy cập, kiểm log, kiểm migration).
2. /ban-do-module: đọc hết một module rồi vẽ lại sơ đồ các file gọi nhau thế nào. Việc này đọc rất nhiều file, in ra rất dài.
3. /tao-api: tạo một endpoint mới theo mẫu của nhóm. Lệnh này cần biết tên tài nguyên, ví dụ phieu-nhap.

Còn Khoa, một thành viên trong nhóm, muốn có bản /review của riêng mình, thêm vài mục kiểm tra mà Khoa hay quên.

Đặt file ở đâu

Có hai cách viết một lệnh tự tạo: file Markdown trong thư mục commands/ (custom slash command), hoặc một thư mục chứa file SKILL.md trong thư mục skills/ (skill). Mỗi loại có hai chỗ đặt:

File trong repo được commit, nên ai clone hay pull về cũng có lệnh, và khi nhóm sửa checklist thì mọi người nhận bản mới qua git. File trong thư mục home chỉ nằm trên máy bạn.

Theo tài liệu Claude Code hiện tại, lệnh tự tạo đã được gộp vào skill: .claude/commands/review.md và .claude/skills/review/SKILL.md đều tạo ra lệnh /review và chạy như nhau. File cũ trong .claude/commands/ vẫn chạy, nhưng tài liệu khuyên viết việc mới thành skill, vì skill là một thư mục nên để kèm được file phụ như mẫu code hay script. Nếu một skill và một file trong commands/ trùng tên thì skill được dùng. Tài liệu cũng không còn nhắc tới ~/.claude/commands/; lệnh riêng của bạn nên viết thành skill trong ~/.claude/skills/.

Đề thi vẫn hỏi theo cả hai tên. Câu hỏi về lệnh dùng chung cho cả nhóm thì đáp án là .claude/commands/ trong repo, còn ~/.claude/commands/ là chỗ để lệnh riêng, không đi theo git. Câu hỏi về skill dùng chung thì đáp án là .claude/skills/<tên>/SKILL.md trong repo, có commit.

Frontmatter của SKILL.md

Đầu file SKILL.md có một đoạn YAML gọi là frontmatter, nằm giữa hai dòng ---. Đây là skill /tao-api của Linh:

---
name: tao-api
description: Tạo endpoint mới theo mẫu route, service, query của nhóm
argument-hint: [ten-tai-nguyen]
allowed-tools: Read Write Edit
---

Tạo endpoint CRUD cho tài nguyên $ARGUMENTS theo mẫu trong src/modules/mau/.

Tham số (argument-hint): bạn gõ /tao-api phieu-nhap thì chữ phieu-nhap thay vào chỗ $ARGUMENTS trong nội dung skill. Nếu người dùng gõ /tao-api mà quên tên tài nguyên, dòng gợi ý [ten-tai-nguyen] nhắc họ cần nhập gì. Muốn lấy từng tham số riêng thì dùng $0, $1…

Giới hạn tool (allowed-tools): đề thi coi trường này là cách giới hạn những tool skill được dùng, ví dụ chỉ cho ghi file để skill không chạy được lệnh có thể làm hỏng dữ liệu. Tài liệu Claude Code hiện tại mô tả cụ thể hơn:

• allowed-tools là danh sách tool được dùng mà không phải hỏi bạn trong lượt gọi skill. Nó không chặn tool nào: tool không có trong danh sách vẫn gọi được, chỉ là theo quyền thường của bạn.
• Muốn thật sự bỏ một tool ra khỏi tầm tay Claude khi skill đang chạy, dùng trường disallowed-tools.

Khi làm thật, muốn chặn thì dùng disallowed-tools. Trong đề thi, câu hỏi "giới hạn tool của skill bằng frontmatter" thì đáp án là allowed-tools.

Tách skill có output dài bằng context: fork

/ban-do-module đọc vài chục file, mỗi lần đọc là một đoạn dài đổ vào cuộc trò chuyện. Chạy xong, context của bạn đầy những nội dung file mà bạn không cần nữa, và các câu hỏi sau bị loãng.

Thêm context: fork vào frontmatter thì skill chạy trong một subagent riêng (isolated sub-agent context):

---
name: ban-do-module
description: Đọc một module và vẽ sơ đồ các file gọi nhau
context: fork
---

• Subagent đọc file, gọi tool trong context của nó. Những thứ đó không đổ vào cuộc trò chuyện của bạn.
• Khi xong, chỉ kết quả cuối (bản sơ đồ, bản tóm tắt) quay về cuộc trò chuyện chính.
• Subagent không thấy lịch sử trò chuyện của bạn, nên mọi thứ nó cần phải viết sẵn trong SKILL.md.
• Trường agent chọn loại subagent; bỏ trống thì dùng loại general-purpose.

Có hai kiểu skill nên tách như vậy: skill in ra nhiều (phân tích codebase) và skill thăm dò (nghĩ ra nhiều phương án để so sánh). Cả hai đều sinh nhiều chữ mà bạn chỉ cần phần kết luận.

Bản riêng không ảnh hưởng đồng đội

Khoa muốn sửa /review theo ý mình. Nếu Khoa sửa thẳng .claude/skills/review/SKILL.md rồi commit, cả nhóm nhận checklist của Khoa.

Cách đúng: Khoa tạo bản riêng trong thư mục home, đặt tên khác, ví dụ ~/.claude/skills/review-khoa/SKILL.md. Khoa gõ /review-khoa cho bản của mình, /review của nhóm vẫn nguyên. Đặt cùng tên review thì trên máy Khoa, bản riêng sẽ thay bản của nhóm (skill cá nhân được ưu tiên hơn skill của project), và Khoa sẽ không thấy những lần nhóm cập nhật checklist.

Skill hay CLAUDE.md

Hai thứ này được nạp khác nhau:

Tài liệu Claude Code gợi ý: khi một đoạn trong CLAUDE.md đã thành một quy trình nhiều bước chứ không còn là một quy ước, hãy chuyển nó thành skill. Nội dung skill chỉ tốn context khi được dùng.