Agent skills trong Claude Code: tạo một skill thật, đo khi nào Claude tự gọi và vì sao gọi đúng mà không viết

Agent skills là cách đóng gói một quy trình thành tệp để Claude tự lấy ra dùng khi cần, thay vì bạn dán lại cùng một đoạn hướng dẫn mỗi lần. Ngày 18/09/2026, mình tạo một skill thật trong Claude Code 2.1.276: viết mô tả sản phẩm theo chuẩn của một cửa hàng cà phê giả lập tên Mây Chiều. Mình hỏi Claude Sonnet 5 mười câu, mỗi câu 2 lần, với hai kiểu description.

Những gì đo được:

1. 1Description chỉ có ba chữ "Mô tả sản phẩm." vẫn đủ để Claude gọi skill đúng lúc 10/10 lần, nhưng cũng gọi nhầm cả 2 lần ở câu "mô tả bức ảnh".
2. 2Description cụ thể hết nhầm ở câu ảnh, nhưng vẫn gọi nhầm 1 trong 2 lần ở câu "mô tả công việc", dù description đã ghi rõ không dùng cho việc đó.
3. 3Gọi đúng skill chưa chắc ra kết quả. Với phần hướng dẫn ban đầu, cả 20 lần gọi đúng lúc Claude đều hỏi lại thay vì viết, vì trong skill có hai luật mâu thuẫn nhau.
4. 4Sửa đúng một dòng hướng dẫn, 5/5 lần Claude viết ra mô tả và kết đúng câu mà skill yêu cầu.
5. 5Mỗi lần gọi skill, lượng token đầu vào gần gấp đôi: từ khoảng 12.700 lên 26.000.

Mỗi câu mới chạy 2 lần, nên đây là quan sát chứ chưa phải thống kê.

Agent skills trong Claude Code: một thư mục và một tệp SKILL.md

Theo tài liệu Claude Code, một skill là một thư mục chứa tệp SKILL.md. Tệp gồm hai phần: đoạn YAML nằm giữa hai dòng --- ở đầu tệp (frontmatter), và phần hướng dẫn Claude làm theo khi skill chạy. Tên thư mục trở thành lệnh bạn gõ, ví dụ /mo-ta-san-pham. Skill trong Claude Code theo chuẩn mở Agent Skills, nên phần theo chuẩn của một skill có thể dùng ở các công cụ AI khác hỗ trợ chuẩn này; một số trường frontmatter là phần mở rộng riêng của Claude Code.

Nói gọn, cách tạo skill Claude Code là tạo một thư mục mang tên skill và đặt tệp SKILL.md vào đó. Chỗ đặt thư mục quyết định skill chạy ở đâu:

• .claude/skills/ten-skill/SKILL.md trong dự án: chỉ trong dự án đó, và cả nhóm dùng chung nếu bạn đưa lên kho mã.
• ~/.claude/skills/ten-skill/SKILL.md: mọi dự án trên máy của bạn.

Mọi trường trong frontmatter đều không bắt buộc. Tài liệu chỉ khuyên có description, vì đó là thứ Claude đọc để quyết định có dùng skill hay không. Phần description và when_to_use cộng lại bị cắt ở 1.536 ký tự trong danh sách skill, nên việc chính phải nằm ở đầu.

Skill mình dựng để thử

Tệp .claude/skills/mo-ta-san-pham/SKILL.md, bản đầu tiên với description mơ hồ:

---
description: Mô tả sản phẩm.
---

Viết mô tả sản phẩm theo chuẩn của cửa hàng cà phê Mây Chiều:

- Dài 60 đến 80 chữ, một đoạn văn, không tiêu đề, không gạch đầu dòng, không biểu tượng cảm xúc.
- Đủ ba ý theo thứ tự: hương vị hoặc công dụng, cách dùng, cách bảo quản.
- Chỉ dùng thông tin người dùng đưa ra. Không tự thêm xuất xứ, hạn dùng, chứng nhận.
- Kết thúc bằng đúng câu: "Mây Chiều rang mới mỗi thứ Hai."

Câu kết "Mây Chiều rang mới mỗi thứ Hai." là dấu hiệu: thấy câu này nghĩa là Claude đã làm theo skill.

Description cụ thể nói rõ skill làm gì, dùng khi nào, và không dùng khi nào:

Viết hoặc sửa mô tả sản phẩm cho trang bán hàng của cửa hàng cà phê Mây Chiều theo chuẩn của cửa hàng (60 đến 80 chữ, ba ý hương vị, cách dùng, bảo quản). Dùng khi người dùng muốn viết, sửa hoặc giới thiệu một sản phẩm để đăng lên trang bán hàng, web shop hay sàn. Không dùng cho email, bài mạng xã hội, mô tả công việc hay mô tả ảnh.

Mỗi câu hỏi được gửi bằng lệnh dưới đây, chạy trong thư mục dự án. Lệnh chỉ mở công cụ Skill và in từng bước ra dạng JSON, để mình thấy Claude có gọi skill hay không:

claude -p "Viết mô tả sản phẩm cho gói cà phê Arabica Cầu Đất 250g." --model sonnet --tools Skill --setting-sources project --strict-mcp-config --no-session-persistence --output-format stream-json --verbose

Hỏi "What skills are available?" thì Claude liệt kê mo-ta-san-pham cùng các Claude Code skills có sẵn như code-review, simplify, init. Tức là skill đã được nạp.

Claude tự gọi skill khi nào: description mơ hồ và cụ thể

Mười câu gồm năm câu nên gọi skill (viết mô tả, đoạn giới thiệu cho trang bán hàng, nội dung cho web shop, một câu tiếng Anh, sửa một mô tả dở) và năm câu không nên (email xin lỗi, hỏi kiến thức, mô tả công việc, mô tả ảnh, caption Facebook).

• Mơ hồ: gọi đúng 10/10 lần nên gọi, kể cả câu tiếng Anh. Gọi nhầm 2/10, cả hai đều ở câu "Viết mô tả cho bức ảnh". Chữ "mô tả" trùng với description là đủ để Claude gọi.
• Cụ thể: vẫn gọi đúng 10/10, hết nhầm ở câu ảnh. Nhưng câu "Viết mô tả công việc để tuyển nhân viên pha chế" bị gọi nhầm 1 trong 2 lần, dù description đã ghi "không dùng cho mô tả công việc". Ở lần đó, Claude đọc skill xong tự nói skill không hợp, rồi viết luôn bản tin tuyển dụng.

Description cụ thể giúp bớt gọi nhầm, nhưng không loại hết. Với skill có tác dụng phụ (gửi email, đăng bài, xoá dữ liệu), đừng chỉ trông vào description.

Gọi đúng skill mà vẫn không viết

Đây là điều mình không lường trước. Ở cả 20 lần skill được gọi đúng lúc, Claude không viết mô tả nào. Lần nào nó cũng hỏi lại, kiểu "Để viết đúng chuẩn, mình cần thêm vài thông tin cụ thể...", rồi liệt kê ba mục hương vị, cách dùng, bảo quản.

Lý do nằm ở chính skill: một dòng đòi đủ ba ý, dòng khác cấm dùng thông tin ngoài những gì người dùng đưa ra. Câu hỏi "Viết mô tả cho gói Arabica Cầu Đất 250g" không cho biết hương vị hay cách bảo quản, nên Claude làm đúng cả hai luật bằng cách không viết gì. Mình sửa đúng một dòng:

- Không tự thêm xuất xứ, hạn dùng, chứng nhận. Nếu người dùng chưa đưa đủ thông tin cho một ý, vẫn viết bản nháp và ghi [cần bổ sung: ...] vào đúng chỗ đó, không hỏi lại.

Chạy lại năm câu nên gọi: 5/5 lần Claude gọi skill, viết một đoạn mô tả và kết đúng câu "Mây Chiều rang mới mỗi thứ Hai.". Bốn lần có chỗ đánh dấu [cần bổ sung: ...]. Lần còn lại, với gói Arabica, Claude tự điền hương vị "chua thanh, hậu ngọt" và tỷ lệ pha 1:15 với nước 92 đến 96 độ, những thứ người dùng chưa hề cung cấp. Bỏ luật "chỉ dùng thông tin người dùng đưa ra" thì Claude viết được, nhưng bạn lại phải kiểm những chi tiết nó tự thêm.

Sau khi sửa, câu hỏi tiếng Anh cũng được trả lời bằng tiếng Việt, có lẽ vì phần hướng dẫn của skill viết bằng tiếng Việt.

Mỗi lần gọi skill tốn thêm bao nhiêu

Claude Code báo số token đầu vào của từng lần chạy (gồm cả phần đọc lại từ bộ nhớ đệm):

• Câu không gọi skill: khoảng 12.700 token với description mơ hồ, 12.900 với description cụ thể. Description dài hơn khoảng 175 token, và phần này cộng vào mọi yêu cầu, kể cả khi skill không được dùng.
• Câu có gọi skill: khoảng 26.000 đến 26.500 token, gần gấp đôi. Phần hướng dẫn của skill chỉ vài trăm chữ. Phần tăng thêm chủ yếu đến từ việc Claude phải chạy thêm một lượt sau khi gọi công cụ Skill.

Với gói thuê bao, con số này ảnh hưởng tới hạn mức sử dụng; nếu dùng API, nó là tiền.

Chỉ cho người dùng gọi: disable-model-invocation

Thêm disable-model-invocation: true vào frontmatter thì skill chỉ chạy khi bạn tự gõ lệnh:

• "Viết mô tả sản phẩm cho gói cà phê Arabica Cầu Đất 250g." Claude không gọi skill, viết một bản chung chung có lời dẫn, tiêu đề in đậm, và tự thêm "độ cao trên 1.500m". Số token đầu vào còn 12.719, vì description không nằm trong ngữ cảnh.
• "/mo-ta-san-pham gói cà phê Arabica Cầu Đất 250g": skill chạy, đoạn mô tả kết đúng câu dấu hiệu.

Tài liệu khuyên dùng cách này cho những việc có tác dụng phụ hoặc cần chọn thời điểm, như triển khai hay gửi tin nhắn.

Viết prompt skill cho Claude: rút ra từ lần thử

• Viết description skill Claude Code theo ba ý: việc gì, dùng khi nào, không dùng khi nào. Trong lần thử này, nó giảm gọi nhầm nhưng không loại hết.
• Đọc lại phần hướng dẫn tìm các luật mâu thuẫn nhau. Claude Sonnet 5 làm theo đúng chữ, nên khi hai luật chặn nhau, nó chọn hỏi lại thay vì làm. Bài cách viết prompt cho Claude có thêm ví dụ về kiểu làm theo đúng chữ này.
• Đặt một câu dấu hiệu trong skill để kiểm Claude có thật sự làm theo không.
• Việc có tác dụng phụ thì dùng disable-model-invocation: true và tự gõ lệnh.
• Thử skill bằng một bộ câu hỏi cố định, có cả câu bẫy, mỗi lần sửa description thì chạy lại.

Nếu bạn cần một AI agent chạy ngoài Claude Code, không tốn phí API, bài tạo AI agent miễn phí bằng n8n và Ollama dựng một agent tư vấn bán hàng trên máy.

Những gì mình chưa kiểm

• Skill cá nhân trong ~/.claude/skills, skill đồng bộ từ claude.ai, và nhiều skill cạnh tranh cùng một câu hỏi.
• Skill có tệp đi kèm, chạy lệnh để lấy dữ liệu, hoặc chạy trong subagent.
• Các model khác ngoài Claude Sonnet 5, và số lần chạy đủ lớn để ra tỷ lệ.