Claude Code bỏ qua skill của tôi 5 lần. 1 dòng đã sửa được

Một skill Claude Code có thể chạy hoàn hảo khi bạn gọi tên mà vẫn không bao giờ tự load khi bạn nhờ bằng lời thường. Skill của chúng tôi chạy mỗi lần ta gõ tên nó, và bị bỏ qua mỗi lần ta nhờ cùng việc đó bằng lời thường. Chúng tôi xem nó bị bỏ qua, đọc lý do, rồi viết lại đúng một dòng đã sửa được nó.

Skill là một bộ hướng dẫn được lưu sẵn, Claude Code tự lấy ra khi yêu cầu của bạn khớp. Thứ quyết định việc khớp là một dòng Claude đọc trước khi chọn, chứ không phải hướng dẫn của bạn. Sáu bước dưới đây đưa bạn từ cái prompt cứ phải gõ lại đến một skill tự load, kèm một bài test hai mươi yêu cầu để bắt skill bị bỏ qua trước khi team bạn phát hiện.

Test (cùng một yêu cầu, phiên mới)	Skill có load không
Gọi bằng tên (/release-notes)	2 of 2
Lời thường, description gốc	0 of 5
Lời thường, description đã viết lại	5 of 5

Skill là một thư mục chứa một file duy nhất, SKILL.md. File bắt đầu bằng một phần đầu ngắn (một name và một description một câu), tiếp theo là hướng dẫn. Nó hoạt động như một hàm: bên gọi đọc chữ ký và docstring, còn phần thân chỉ chạy khi được gọi. Lưu nó trong thư mục home để dùng ở mọi dự án, hoặc trong repository để ai làm việc ở đó cũng có.

Hãy bắt đầu từ công việc, không phải từ file. Chọn cái prompt bạn cứ phải gõ lại và viết ra đúng kết quả bạn muốn. Của chúng tôi là release notes hằng tuần: các commit từ thứ Hai, nhóm theo khu vực, bỏ phần việc vặt, mỗi thay đổi một dòng kèm số pull request. Trên repository mã nguồn mở Hono, cái prompt dài đó cho ra bản ghi chú sạch cho tám bản sửa lỗi trong tuần, và kết quả đó trở thành mục tiêu mà skill phải đạt.

Tạo .claude/skills/release-notes/SKILL.md trong dự án: một thư mục skills nằm trong thư mục ẩn .claude, một thư mục đặt theo tên skill, và file skill nằm bên trong. Thư mục này quan trọng. Một file release-notes.md để lẻ sẽ không load chút nào, và tài liệu liệt kê đó là điều đầu tiên cần kiểm tra.

Phần đầu là vài dòng có nhãn nằm giữa hai hàng gạch ngang, và nó phải bắt đầu ở dòng đầu tiên của file, nếu không Claude Code sẽ bỏ qua. Phần đầu của chúng tôi có name release-notes và description mà hầu hết mọi người sẽ viết:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Bên dưới phần đầu là hướng dẫn dưới dạng các bước đánh số, giống những gì bạn sẽ giao cho một đồng nghiệp mới. Skill của chúng tôi có năm bước: tìm các commit từ thứ Hai, bỏ commit chore và docs, nhóm theo scope của conventional-commit, viết một dòng đơn giản cho mỗi thay đổi, và xuất một khối có tiêu đề kèm phần tóm tắt ngắn ở trên cùng. Anthropic khuyên giữ phần này ngắn. Bạn không cần khởi động lại: Claude Code nhận skill mới hoặc đã sửa ngay trong phiên bạn đang dùng.

Test bằng tên: gõ dấu gạch chéo, chọn skill trong menu, nhấn enter. Trong các phiên mới, skill của chúng tôi lần nào cũng đọc commit log, nhóm các bản sửa theo khu vực và viết ghi chú đúng như mong muốn. Vấn đề là bạn, và mọi người trong team, đều phải nhớ tên nó.

Đồng nghiệp sẽ không gõ tên skill. Họ sẽ mở một phiên mới và nhờ theo cách họ nhờ bạn. Vậy hãy test đúng như thế: mở một phiên mới (một cuộc trò chuyện mới chưa load gì) và nhờ việc đó bằng lời của chính bạn. Phải là phiên mới, vì một skill đã dùng rồi sẽ nằm lại trong cuộc trò chuyện, và test trong phiên đó chẳng chứng minh được gì.

Chúng tôi gõ "what did we ship this week?". Claude tự chạy commit log và viết một bản tóm tắt theo cách riêng của nó, không thấy dấu vết nào của skill. Các câu trả lời không tệ, nhưng khác nhau giữa các lần chạy: một lần tính từ thứ Hai, lần khác tính từ release tag gần nhất và kéo vào một thay đổi docs mà skill lẽ ra đã bỏ. Qua năm phiên mới, skill bị bỏ qua cả năm lần.

Năm lần chạy chỉ là một demo, không phải thống kê. Nhưng một skill chạy được khi gọi tên mà lần nào cũng bị bỏ qua khi dùng lời thường thì chưa làm đúng việc của nó, và vì nó đã qua bài test gọi tên ở bước hai, bạn sẽ chẳng bao giờ nghĩ đến việc đi kiểm tra.

Trước khi đổi một chữ nào, hãy chạy ba phép kiểm tra:

1. /skills liệt kê mọi skill mà phiên có thể thấy. Tìm skill của bạn trong đó. Skill của chúng tôi có trong danh sách và đang bật, nhưng môi trường có 277 skill, và vài skill từ plugin khớp với "release" trước skill của ta.
2. claude --debug ghi một log chi tiết về những gì Claude Code load. Tìm các dòng về skills. Log của chúng tôi cho thấy skill của dự án đã load, và cũng có một cảnh báo rằng danh sách skill vượt ngân sách, nên một số description bị cắt.
3. claude plugin validate .claude/skills kiểm tra phần đầu có đúng định dạng không. Bước này quan trọng: phần đầu hỏng vẫn cho skill chạy khi gọi tên, nhưng Claude không còn tự khớp được nó nữa. Của chúng tôi đã qua.

Kiểm tra	Nó cho bạn biết gì	Kết quả của chúng tôi
/skills	Skill có hiện và đang bật không?	Có trong danh sách, đang bật (277 skill)
--debug	Nó có load không? Danh sách có bị cắt không?	Đã load; cảnh báo danh sách vượt ngân sách
plugin validate	Phần đầu có parse được không?	Đạt

Khi file đã load và phần đầu hợp lệ, nguyên nhân nằm ở description. Cho tới khi quyết định load một skill, Claude không đọc hướng dẫn của bạn. Nó đọc một dòng cho mỗi skill, gồm name và description, rồi khớp với lời của bạn. Skill của chúng tôi ghi "generates changelog documents from repository history"; yêu cầu thì là "what did we ship this week". Hai câu này không chung một từ nào. Claude chưa bao giờ đọc hướng dẫn của chúng tôi; nó đọc một dòng, và dòng đó không dùng từ của chúng tôi.

Cảnh báo ngân sách nghĩa là Claude Code cắt bớt description cho vừa, skill ít dùng nhất bị cắt trước, và một skill mới tinh luôn là skill ít được dùng nhất. Hãy kiểm tra xem skill của bạn có sống sót không: skill của chúng tôi có, vì các yêu cầu dùng chính từ của nó vẫn load được nó.

Hãy viết description cho khoảnh khắc có người nhờ, không phải cho cái file. Nói skill làm gì, khi nào dùng, và những từ người ta thật sự gõ. Description của chúng tôi trở thành:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Hướng dẫn viết skill của Anthropic thêm một quy tắc: viết ở ngôi thứ ba ("Writes"), đừng bao giờ viết "I can help" hay "You can use this".

Sau đó hãy chứng minh trong một phiên mới với cùng yêu cầu. "What did we ship this week?" lần này load skill trước khi Claude đụng vào bất cứ thứ gì, và ghi chú ra đúng định dạng của chúng tôi, trong năm trên năm phiên mới.

Hãy chạy thêm một baseline: tắt skill bằng một skill override trong file cài đặt cục bộ (nó ẩn skill mà không xóa). Khi tắt, Claude quay lại bản tóm tắt của riêng nó; khi bật, skill được load. Chính skill tạo ra khác biệt, không phải may mắn.

Giới hạn: một description khớp quá rộng sẽ khiến skill kích hoạt ở chỗ không nên. Hãy thêm những từ bạn thật sự dùng, không phải mọi từ bạn nghĩ ra được.

Một yêu cầu chứng minh được bản sửa; nhưng một skill cả team dựa vào sẽ được nhờ theo nhiều cách. Skill-creator của Anthropic mô tả bài test: hai mươi yêu cầu, gồm những yêu cầu nên load skill và những near miss không nên. Near miss nghe gần giống nhưng là một việc khác, ví dụ "write a commit message for my staged changes". Chạy mỗi yêu cầu trong một phiên mới riêng và ghi lại skill có load không. Script riêng của skill-creator không thấy skill trên phiên bản Claude Code của chúng tôi, nên chúng tôi chạy cùng hai mươi yêu cầu đó bằng một script ngắn tự viết.

Description	Yêu cầu nên load mà đã load	Near miss đã load
Gốc	4 of 10	0 of 10
Đã viết lại	10 of 10	0 of 10

Trước khi viết lại, skill chỉ load với các yêu cầu đã chứa sẵn "release notes", "changelog" hoặc "release": đó là việc khớp từ ở bước bốn, hiện ra rõ ràng. Sau khi viết lại, nó load ở mọi yêu cầu nên load và vẫn không dính near miss nào.

Với skill không được phép trượt, hãy ép nó. Gõ tên nó, hoặc thêm một hook (một script nhỏ Claude Code chạy vào một thời điểm cố định, ở đây là mỗi lần bạn gửi tin nhắn) có đầu ra bảo Claude dùng skill cho việc đó. Có hook, ngay cả description gốc cũng load ở yêu cầu bằng lời thường. Giới hạn: mỗi lần chạy test đều tốn lượng dùng thật và hook thêm một dòng vào mỗi tin nhắn, nên chỉ để dành cho vài skill thật sự phải kích hoạt. Hãy chạy lại danh sách của bạn mỗi khi đổi description.

Skill release-notes của chúng tôi chạy mọi lần khi gọi tên, bị bỏ qua trong mọi phiên mới khi dùng lời thường, và một dòng viết lại khiến nó load mọi lần. Lý do: Claude đọc một dòng cho mỗi skill trước khi quyết định, và nó khớp theo lời bạn nói, không phải ý định của bạn.

Skill đáng dùng cho một việc bạn lặp lại với kết quả cố định: ghi chú hằng tuần, mô tả pull request, checklist release. Nó không đáng cho một câu hỏi dùng một lần, và nó không phải công cụ cho một quy tắc phải luôn đúng; đó là việc của hook. Một đống skill không ai dùng cũng tốn kém, vì có quá nhiều skill thì Claude Code bắt đầu cắt description, cái ít dùng nhất trước. Một description tốt làm tăng khả năng, nhưng không khiến skill kích hoạt cho một việc nó không được làm ra để xử lý, và vài lần chạy chỉ là demo, nên danh sách yêu cầu test của bạn mới là phép kiểm tra thật.

Quy tắc duy nhất: viết description bằng chính những từ bạn gõ khi nhờ làm việc đó.