Cách xây dựng skill hiệu quả cho Claude Code theo chuẩn Anthropic

TL;DR

• Một skill Claude Code là một thư mục chứa SKILL.md, mở đầu bằng YAML frontmatter tối thiểu name + description.
• Trường description là thứ duy nhất Claude đọc để quyết định tự động kích hoạt skill, không phải nội dung bên trong file.
• Progressive disclosure chia skill thành 3 cấp tải: metadata luôn nạp, nội dung SKILL.md nạp khi liên quan, file phụ trong references/, scripts/, assets/ chỉ đọc khi thực sự cần.
• YAML hỏng không làm skill biến mất: nó vẫn gọi thủ công được bằng /skill-name, nhưng Claude mất hoàn toàn khả năng tự động kích hoạt vì description parse ra rỗng.

Vấn đề: skill viết xong nhưng không bao giờ được gọi

Một trong những lỗi khó phát hiện nhất khi làm việc với Claude Code không nằm ở logic bên trong skill, mà ở đúng vài dòng đầu tiên của file: khối YAML frontmatter. Trong một đợt audit thư mục .claude/skills/ của một dự án thực tế với gần 100 skill, ba lỗi cùng một nhóm nguyên nhân đã lộ ra: skill vẫn gọi thủ công bằng /ten-skill được, nhưng gần như không bao giờ tự động kích hoạt theo ngữ cảnh hội thoại.

Tài liệu chính thức của Claude Code mô tả đúng cơ chế đứng sau hiện tượng này: nếu frontmatter YAML bị hỏng, Claude Code vẫn nạp nội dung skill với metadata rỗng, lệnh /ten-skill vẫn chạy được, nhưng Claude không còn gì để đối chiếu khi quyết định có nên tự động dùng skill hay không via Claude Code Docs. Nói cách khác: skill không chết, nó chỉ trở nên vô hình.

SKILL.md không chỉ là markdown thuần

Theo chuẩn Agent Skills do Anthropic phát triển và mở thành open standard, một skill là một thư mục, không phải một file đơn lẻ via anthropics/skills. Cấu trúc tối thiểu:

SKILL.md là entrypoint bắt buộc duy nhất. Ba thư mục còn lại đều tùy chọn: scripts/ chứa code Claude có thể thực thi, references/ chứa tài liệu tham khảo chi tiết, assets/ chứa template hoặc resource. Đội ngũ Claude Code nhấn mạnh điều này trong bài viết tổng kết kinh nghiệm nội bộ: một hiểu lầm phổ biến là nghĩ skill chỉ là markdown, trong khi thực chất chúng là thư mục mà agent có thể tự khám phá và thao tác via Claude Blog.

Lý do cấu trúc này quan trọng nằm ở nguyên tắc progressive disclosure, nguyên tắc thiết kế cốt lõi giúp Agent Skills vừa linh hoạt vừa mở rộng được theo quy mô via Anthropic Engineering, vận hành theo 3 cấp tải:

• Cấp 1 - Metadata: name và description nạp vào system prompt ngay từ đầu session, cho mọi skill đang có, bất kể có dùng hay không.
• Cấp 2 - Nội dung SKILL.md: chỉ nạp khi Claude xác định skill liên quan đến task hiện tại, dựa trên việc đối chiếu yêu cầu người dùng với description.
• Cấp 3 - File phụ: nội dung trong references/, scripts/, assets/ chỉ được đọc khi skill đang chạy thực sự cần đến bước đó.

Hệ quả trực tiếp: một skill có thể chứa hàng nghìn dòng tài liệu chi tiết trong references/ mà gần như không tốn context nếu người dùng chưa bao giờ chạm tới nhánh việc đó. Đây cũng là lý do tài liệu khuyến nghị: khi SKILL.md trở nên cồng kềnh, hãy tách nội dung sang file riêng thay vì nhồi hết vào một chỗ.

Description quyết định mọi thứ, không phải nội dung bên trong

Vì cấp 1 luôn được nạp còn cấp 2 chỉ nạp có điều kiện, trường description chính là cánh cửa duy nhất để một skill được cân nhắc. Claude dùng trường này để quyết định khi nào áp dụng skill; nếu bỏ trống, hệ thống tự lấy đoạn văn đầu tiên của nội dung markdown làm thay thế, vốn hiếm khi đủ tín hiệu.

Một vài ràng buộc kỹ thuật đáng nhớ: name tối đa 64 ký tự, chữ thường-số-gạch ngang, không chứa từ khóa dành riêng như "anthropic" hay "claude". description tối đa 1024 ký tự, không được rỗng, và quan trọng nhất là phải nêu được cả hai vế: skill này làm gì, và khi nào nên dùng nó. Trường when_to_use đi kèm để bổ sung trigger phrase cụ thể, nhưng cộng dồn vào cùng giới hạn hiển thị 1536 ký tự với description, nên nội dung quan trọng nhất nên đặt lên đầu.

Đội ngũ Claude Code còn đưa ra một nguyên tắc thực dụng hơn: viết description để kích hoạt quá trình ra quyết định của Claude, không phải để con người đọc cho dễ hiểu, và nên gài từ khóa hành động cụ thể để tăng khả năng phát hiện đúng lúc. Một description mô tả đúng chức năng nhưng thiếu ngữ cảnh kích hoạt vẫn có thể khiến skill bị bỏ qua trong thực tế, dù kỹ thuật vẫn hợp lệ.

Phân biệt CLAUDE.md, SKILL.md, bootstrap và memory

Bốn cơ chế này thường bị gộp chung vì đều là "tài liệu hướng dẫn agent", nhưng phục vụ vai trò khác hẳn nhau:

• CLAUDE.md: bộ nhớ nền toàn project, nạp vào mọi session không điều kiện. Tài liệu chính thức khuyên tạo skill đúng lúc một đoạn trong CLAUDE.md phình to thành một quy trình nhiều bước thay vì một fact ngắn gọn, vì nội dung skill chỉ tốn context khi thực sự dùng đến, còn CLAUDE.md thì luôn tốn.
• SKILL.md: quy trình cho một loại task cụ thể, chỉ nạp khi description khớp với yêu cầu hiện tại.
• Bootstrap/scaffold: hành động thiết lập một lần, dựng cấu trúc ban đầu hoặc tạo config khởi tạo, không phải nội dung đọc lại mỗi lần.
• Memory: dữ liệu tích lũy qua thời gian, thường lưu dưới dạng log nối tiếp hoặc file JSON, giúp agent nhớ ngữ cảnh giữa các phiên làm việc khác nhau, ví dụ nội dung đã đăng lần trước hoặc code đã review.

Nguyên tắc phân bổ ngắn gọn: fact luôn đúng và áp dụng toàn cục vào CLAUDE.md, quy trình riêng cho một loại task vào SKILL.md, cách làm chi tiết đẩy xuống file tham khảo hoặc script, còn thứ học được qua thời gian thì để cho memory.

Case study: 3 lỗi thật phát hiện khi audit skill

Ba lỗi dưới đây đến từ việc rà soát trực tiếp một bộ skill đang chạy trong production.

Lỗi 1 - YAML hỏng vì field lạc chỗ. Một skill có cấu trúc frontmatter dạng block scalar YAML (description: >-) nhưng dòng ngay phía dưới lại là một key khác (argument-hint:) đặt ở cột 0 thay vì được thụt lề vào trong khối description. Theo cú pháp YAML, dòng ở cột 0 luôn được hiểu là một key anh em, không phải nội dung của block scalar phía trên. Kết quả: description parse ra rỗng hoàn toàn.

Đây chính là kịch bản mà tài liệu chính thức mô tả: skill vẫn chạy được thủ công, nhưng Claude "không có gì để đối chiếu" khi quyết định tự động dùng skill hay không. Cách phát hiện thực tế: chạy Claude Code với cờ --debug để xem lỗi parse, hoặc đơn giản hơn, tự hỏi "nếu tôi gõ đúng câu mô tả nhu cầu, skill này có được liệt kê không".

Lỗi 2 - Description chứa sai loại nội dung. Một skill khác có description đọc như sau: "Path to markdown file, plan directory, or plans collection". Đây không phải mô tả chức năng, mà là nội dung đáng lẽ thuộc về trường argument-hint, tức gợi ý về tham số truyền vào chứ không phải tín hiệu ngữ nghĩa cho việc kích hoạt. Hậu quả tương tự lỗi 1 dù nguyên nhân khác: Claude không có manh mối nào về việc đây là một skill xem trước markdown.

Lỗi 3 - File scaffold mồ côi lẫn vào danh sách skill đang hoạt động. Một file mẫu dùng để copy khi tạo skill mới, với description còn nguyên placeholder dạng "Replace with description of the skill...", lại nằm ngay trong thư mục .claude/skills/ đang hoạt động. Không có công cụ nào trong hệ thống tham chiếu nó làm khuôn mẫu thực sự, nhưng nó vẫn bị liệt kê như một skill khả dụng. Cách sửa đúng: đặt user-invocable: false để ẩn khỏi menu /, kèm description nói rõ đây là scaffold.

Checklist trước khi ship một skill

• Frontmatter parse được: chạy thử với --debug, hoặc tối thiểu đọc lại từng dòng YAML bằng mắt, đặc biệt khi dùng block scalar >- hoặc |.
• description nêu đủ hai vế: skill làm gì và khi nào dùng, đặt use case quan trọng nhất lên đầu vì nội dung bị cắt ở 1536 ký tự.
• Không nhồi hint về tham số vào description. Hint tham số thuộc về argument-hint.
• SKILL.md chỉ là bản đồ. Nội dung chi tiết, gotchas, ví dụ dài đẩy sang references/.
• Ghi lại "gotchas" thực tế đã vấp phải khi dùng skill. Đây là nội dung tín hiệu cao nhất theo kinh nghiệm nội bộ của Claude Code team, giúp skill tốt lên dần qua từng lần chỉnh sửa thay vì đúng hoàn toàn ngay từ đầu.
• File scaffold, template hoặc bản nháp không có chức năng thật: đặt user-invocable: false, đừng để lẫn vào danh sách skill khả dụng.

Kết

Phần lớn lỗi khiến một skill "vô hình" không nằm ở logic nghiệp vụ bên trong, mà ở vài dòng frontmatter đầu file, nơi rất dễ bị bỏ qua vì trông như chi tiết vặt. Vì Claude chỉ có đúng một cánh cửa để quyết định tự động dùng skill hay không, tức trường description, một lỗi nhỏ ở đó đủ sức vô hiệu hóa toàn bộ công sức viết nội dung bên trong. Kiểm tra frontmatter trước, viết nội dung sau, không phải ngược lại.