Bài 3.215 phút · 5 thẻ · 8 bài tập · 1 nhiệm vụ

Tự tạo lệnh slash

Biến hướng dẫn bạn hay gõ lại thành một lệnh: SKILL.md, tham số, dữ liệu thật từ shell, và ai được phép gọi.

Làm với todo-api được vài hôm, bạn sẽ thấy mình gõ lại cùng một đoạn: "thêm endpoint này, viết test trước, lỗi trả về dạng { error: "..." }, chạy npm test tới khi đạt". Lần nào cũng gõ, lần nào cũng sót một ý. Bài này biến đoạn đó thành một lệnh: /add-endpoint POST /todos/:id/restore, gõ một dòng là xong.

Khi nào nên có lệnh riêng

Dấu hiệu rõ nhất: bạn dán đi dán lại cùng một hướng dẫn, một checklist hay một quy trình nhiều bước. Một dấu hiệu khác: một phần CLAUDE.md đã dài ra thành quy trình thay vì dữ kiện. CLAUDE.md được nạp ở mọi phiên, còn một quy trình thì chỉ cần lúc bạn làm việc đó.

Ở bài 3.1 bạn đã biết /code-review hay /debug là skill: một prompt giao cho Claude. Lệnh tự tạo cũng vậy. Trước đây lệnh tự tạo là file Markdown trong .claude/commands/, giờ đã gộp vào skill. File cũ vẫn chạy, nhưng làm mới thì nên dùng skill, vì skill là một thư mục, có thể kèm script và file tham khảo (bài 3.3). Nếu một skill và một file trong .claude/commands/ trùng tên, skill được dùng.

Lệnh đầu tiên: /add-endpoint

Một skill là một thư mục chứa file SKILL.md. Tên thư mục là lệnh bạn gõ. Trong todo-api, tạo:

.claude/skills/add-endpoint/SKILL.md
Markdown
---
description: Add an endpoint to todo-api with a test first
disable-model-invocation: true
argument-hint: "[METHOD] [path]"
---
Add the $0 $1 endpoint to src/routes/todos.js.

1. Write a failing test in test/todos.test.js first
2. Implement the route; return errors as { error: "..." }
3. Run npm test and keep going until it passes

File có hai phần. Giữa hai dòng --- là frontmatter (phần khai báo bằng YAML): mô tả, ai được gọi, gợi ý tham số. Bên dưới là nội dung Claude sẽ làm theo, viết như bạn vẫn gõ prompt.

Ba lỗi hay gặp ở frontmatter:

  • --- phải là dòng đầu tiên của file. Chỉ cần một dòng tiêu đề # Add endpoint nằm phía trên, Claude Code sẽ coi cả file, kể cả các dấu ---, là nội dung và bỏ qua mọi khai báo.
  • YAML viết sai (thiếu dấu hai chấm, thụt lề lệch) thì skill vẫn nạp nhưng không có trường nào, và bạn chỉ thấy lệnh không chạy như mong đợi. Chạy claude --debug để xem lỗi YAML.
  • Giá trị có dấu ngoặc vuông như [METHOD] [path] phải đặt trong ngoặc kép. Không có ngoặc kép, YAML hiểu [...] là một danh sách, và hai danh sách liền nhau là YAML sai. Khi đó skill mất cả disable-model-invocation, và Claude lại được tự gọi lệnh mà bạn muốn giữ cho riêng mình.

Đặt ở đâu tùy ai cần dùng:

  • .claude/skills/<tên>/SKILL.md trong repo: lệnh của dự án. Commit thư mục này để cả team có cùng lệnh, giống CLAUDE.md ở cấp 2.
  • ~/.claude/skills/<tên>/SKILL.md trong thư mục nhà: lệnh cá nhân, dùng được ở mọi dự án trên máy bạn.

Gõ / trong Claude Code, /add-endpoint sẽ hiện trong danh sách cùng gợi ý [METHOD] [path] lấy từ argument-hint.

Tham số

Phần chữ bạn gõ sau tên lệnh là tham số, và skill nhận nó qua các biến:

  • $ARGUMENTS là toàn bộ phần chữ đó.
  • $0, $1, $2… (viết đầy đủ là $ARGUMENTS[0], $ARGUMENTS[1]…) là từng phần theo vị trí, đếm từ 0.

Gõ /add-endpoint POST /todos/:id/restore thì $0 là POST, $1 là /todos/:id/restore, và Claude nhận được câu "Add the POST /todos/:id/restore endpoint to src/routes/todos.js."

Quên đặt biến nào trong nội dung cũng không sao: Claude Code nối thêm một dòng ARGUMENTS: … vào cuối để Claude vẫn thấy bạn đã gõ gì. Nhưng đặt biến đúng chỗ thì câu lệnh rõ nghĩa hơn.

Dữ liệu thật từ shell

Có khi lệnh cần thông tin chỉ có lúc chạy: diff hiện tại, nhánh đang đứng, kết quả test. Viết !`lệnh` trong SKILL.md, Claude Code chạy lệnh shell đó trước khi gửi nội dung cho Claude, rồi thay chỗ đó bằng output. Claude đọc thẳng dữ liệu, không phải tự đi chạy lệnh.

Ví dụ skill /changes:

Markdown
---
description: Summarise my uncommitted changes
---
Uncommitted changes:
!`git diff HEAD`

Summarise these changes in three bullets, then list any risks.

Cần nhiều lệnh thì dùng một khối mã mở bằng ```!.

Hai điều cần nhớ:

  • Một lệnh chèn bị lỗi sẽ hủy cả lần gọi skill, không chỉ chỗ của nó; Claude không nhận được gì. Với bash, mọi mã thoát khác 0 đều tính là lỗi. Lệnh nào hay thoát khác 0 mà vẫn ổn thì thêm || true phía sau.
  • Lệnh chèn không hỏi quyền lúc skill chạy, mà được đối chiếu với các quy tắc quyền của bạn. Lệnh bị một quy tắc deny chặn thì lần gọi bị hủy. Ngoài auto mode, lệnh chưa được cho phép cũng làm hủy lần gọi, trừ khi bạn cấp sẵn quyền cho nó bằng allowed-tools trong frontmatter.

Ai được gọi lệnh

Khi mở phiên, Claude Code nạp phần description của mọi skill để Claude biết có những gì; toàn bộ nội dung chỉ nạp khi skill được gọi. Vì vậy mặc định cả bạn và Claude đều gọi được: bạn gõ /changes, hoặc bạn hỏi "mình vừa sửa gì nhỉ?" và Claude tự nhận ra skill hợp với câu hỏi. Cách Claude chọn và cách viết description cho tốt là chủ đề của bài 3.3.

Với lệnh có tác động thật, như deploy, commit, gửi tin nhắn, bạn không muốn Claude tự quyết lúc nào chạy. Thêm disable-model-invocation: true: Claude không tự gọi, lệnh chỉ chạy khi bạn gõ. /add-endpoint ở trên dùng cờ này vì nó sửa code theo một quy trình bạn muốn tự khởi động.

Vị trí của tên lệnh trong tin nhắn cũng quan trọng:

  • Đầu tin nhắn, như /deploy staging: lệnh chạy ngay.
  • Giữa câu, như một từ riêng, như "test đạt rồi, cứ /deploy lên staging": không có gì chạy trực tiếp. Tên lệnh chỉ là lời cho phép trong tin nhắn đó; Claude đọc câu chữ của bạn và tự quyết có chạy hay không.
  • Muốn nhắc tới một lệnh mà không cho phép chạy, bỏ dấu /: "skill deploy đang lỗi".

Còn allowed-tools cho phép Claude dùng một số công cụ mà không hỏi, nhưng chỉ trong lượt gọi skill: quyền hết khi bạn gửi tin nhắn tiếp theo. Muốn cho phép cả phiên thì đặt quy tắc trong cài đặt quyền. Một thói quen an toàn: trước khi chạy Claude Code trong repo người khác, mở .claude/skills/ xem các skill đó xin những quyền gì.

Giữ lệnh ngắn

Khi một skill được gọi, nội dung của nó nằm lại trong hội thoại ở các lượt sau; Claude Code không đọc lại file. Mỗi dòng trong SKILL.md vì thế là chi phí lặp lại ở mọi lượt còn lại của phiên. Viết như ví dụ /add-endpoint: vài bước rõ ràng, không giải thích dài dòng điều Claude đã biết.

Với todo-api, sau bài này bạn có hai lệnh: /add-endpoint để thêm route theo đúng quy trình của dự án, và /changes để tóm tắt việc vừa làm trước khi /diff và /code-review. Commit .claude/skills/ là cả team có chúng.

Bài sau: skill không chỉ là lệnh bạn gõ. Thêm script, file tham khảo và một description tốt, Claude sẽ tự biết lúc nào cần dùng.

Luyện tập bài 3.2

5 thẻ ghi nhớ, 8 bài tập chấm ngay trên trang, 1 nhiệm vụ làm trên máy.

Bắt đầu luyện tập

Tra cứu liên quan

Gõ để tìm trong tra cứu, mẫu cấu hình và bài học. Không dấu cũng được.