TL;DR

  • Skill là on-demand loading - chỉ load khi user prompt khớp description, khác với CLAUDE.md (luôn active) và slash command (manual invoke).
  • Description quyết định Skill có được trigger hay không - bị giới hạn 1,536 ký tự, đặt key use case lên đầu.
  • SKILL.md nên dưới 500 dòng, chia tài liệu thành references/, scripts/, assets/ để load theo nhu cầu.
  • Viết xong Skill không có nghĩa là nó đúng - cần eval, A/B test và vòng lặp cải thiện để biết nó thực sự có giá trị hơn baseline.

Bẫy phổ biến: nhồi hết vào 1 file

Nhiều người viết Skill theo phản xạ tự nhiên: quét hết background, rules, các trường hợp ngoại lệ và ví dụ vào một file SKILL.md duy nhất. Trông có vẻ đầy đủ. Nhưng thực tế, đây là cách nhanh nhất để làm AI agent hoạt động kém hơn.

Khi nhận quá nhiều context, điều gì xảy ra bên trong mô hình? Attention dilutes - hướng dẫn nằm ở token thứ 50,000 sẽ bị xử lý khác với hướng dẫn ở token thứ 500. Contradictions compound - càng nhiều nội dung thì càng nhiều khả năng xung đột. Signal-to-noise ratio giảm - tài liệu không liên quan đến task hiện tại không ngồi im, nó cạnh tranh trực tiếp với những gì Agent đang cần làm.

Đây chính là "context rot" - và progressive disclosure là chiến lược chính để ngăn nó xảy ra.

On-demand loading - nền tảng đúng nghĩa của Skill

Để viết Skill tốt, cần hiểu rõ nó khác gì các công cụ khác trong Claude Code.

CLAUDE.md là "memory card" của dự án - được load vào context ngay khi bắt đầu mỗi session, luôn hiện diện. Phù hợp cho global facts, build commands, kiến trúc tổng quát. Nhược điểm: nếu nhét quá nhiều, gây context drift ở session dài.

Slash command là macro thủ công - người dùng phải gõ /tên-command mới chạy. Đơn giản, tường minh, nhưng cần kích hoạt bằng tay.

Skill nằm ở giữa: không phải luôn active, không cần gõ lệnh tay. Nó có 3 cấp độ loading:

  • Level 1 - Metadata (luôn load): YAML frontmatter - khoảng 100 tokens/skill, giúp Claude biết skill nào tồn tại và khi nào dùng.
  • Level 2 - Instructions (load khi trigger): toàn bộ nội dung SKILL.md - chỉ được nạp khi user prompt khớp description.
  • Level 3 - Supporting files (load khi cần): references/, scripts/, assets/ - chỉ được đọc khi bước nào đó trong quy trình yêu cầu.

Một chi tiết quan trọng: description + when_to_use bị cắt sau 1,536 ký tự trong skill listing. Nếu để key use case ở cuối, nó có thể bị cắt mất. Luôn đặt mục đích chính lên đầu.

Ngoài ra, sau khi conversation bị auto-compact, mỗi skill chỉ được giữ lại tối đa 5,000 tokens và toàn bộ các skill tái attach chia sẻ budget chung 25,000 tokens. Skill cũ có thể bị drop hoàn toàn nếu bạn đã invoke quá nhiều skill trong 1 session.

5 nguyên tắc viết Skill chất lượng cao

1. Description là selector, không phải tutorial

Mục đích của description là giúp Agent quyết định có dùng Skill hay không - không phải mô tả đầy đủ cách làm. Viết description như 1 wall of text buộc Agent phải xử lý toàn bộ đó với mọi task, kể cả những task không liên quan.

Quan trọng hơn: hãy viết các cụm từ mà người dùng thực sự sẽ nói. Người dùng không gõ "hãy chạy skill viết long-form X". Họ sẽ nói: "mở rộng ý tưởng này thành bài viết", "viết thread dài về chủ đề này", "giúp tôi expand nội dung này". Những trigger phrase đó phải có trong description.

Nếu Skill quá dài hoặc dùng tần suất thấp - chỉ viết một năm vài lần, chỉ dùng khi tìm việc - đặt disable-model-invocation: true để xuống cấp thành slash command: tiết kiệm context, giảm misfire.

2. Minimum privilege cho tools

Skill có thể giới hạn công cụ được phép dùng qua trường allowed-tools. Nguyên tắc đơn giản: chỉ cấp quyền tối thiểu để hoàn thành nhiệm vụ.

Skill chỉ đọc và tóm tắt tài liệu không cần Bash. Skill chỉ gợi ý không cần Write. Skill xử lý file không cần thực thi lệnh hệ thống. Công cụ càng nhiều không có nghĩa là càng mạnh - đôi khi chỉ là càng nhiều rủi ro.

3. Chọn model phù hợp cho từng loại task

Không phải tất cả task đều cần model mạnh nhất. Dùng trường model trong frontmatter để override model cho session đang chạy:

  • Viết tài liệu, long-form: model có khả năng writing và structure tốt.
  • Phân tích dữ liệu, bảng biểu: model lý luận ổn định, chi phí vừa phải.
  • Crawl thông tin, batch processing: model nhanh rẻ là đủ.
  • Code review, kiến trúc hệ thống: model có reasoning depth tốt hơn.

Chọn model không phải khoe khoang - là cân bằng giữa chi phí, tốc độ và độ tin cậy.

4. Progressive disclosure - chia nhỏ SKILL.md

SKILL.md nên dưới 500 dòng và đóng vai trò như file đầu vào, không phải encyclopedia. Tại sao giới hạn 500 dòng? Vì vượt qua đó, thông thường là dấu hiệu bạn đang nhét quá nhiều thứ vào một chỗ.

Cấu trúc nên dùng:

ten-skill/
  SKILL.md              # quy trình, điều kiện trigger, danh sách tool
  references/
    huong-dan-chi-tiet.md
    cac-truong-hop-ngoai-le.md
  scripts/
    kiem-tra-dinh-dang.py
    xu-ly-hang-loat.sh
  assets/
    mau-output.md
    vi-du-chuan.json

Agent đọc SKILL.md trước để biết tổng thể quy trình. Khi cần thông tin chi tiết, nó mới đọc references. Khi cần thực thi tác vụ xác định, nó mới chạy script. Đây là progressive disclosure - load theo nhu cầu, không load trước hết tất cả.

5. Xác minh trước khi dùng thật

Viết xong Skill không có nghĩa là nó chạy được. Trước khi dùng, cần kiểm tra 3 thứ:

  • Có chạy được không? Đường dẫn file đúng không? Quyền tool đủ chưa? Script có thực thi được không?
  • Có trigger đúng không? Thử với những câu người dùng thực sự hay nói - không chỉ "hãy chạy skill X".
  • Kết quả có tốt hơn khi không dùng Skill? Đây là câu hỏi dễ bị bỏ qua nhất. Nếu dùng và không dùng đều cho kết quả 7/10, Skill này không củng cố thêm giá trị gì.

Vòng lặp eval: đừng tin vào cảm giác

Skills 2.0 ra mắt 3/3/2026 bổ sung hệ thống đo lường chính thức vào vòng đời Skill. Thay vì "nhìn có vẻ ổi", giờ có thể đo lường bằng số liệu.

Hệ thống xây dựng xung quanh 2 khái niệm:

  • Criteria: đo một chiều chất lượng cụ thể - binary (pass/fail), scored (1-10), hoặc reference-based (so sánh với output mẫu).
  • Rubric: nhóm nhiều criteria có trọng số, tính trung bình có trọng để ra điểm tổng.

Vòng lặp cơ bản:

  1. Chuẩn bị test dataset 30-50 inputs đa dạng, bao gồm cả edge case - không dùng dữ liệu đã dùng để tinh chỉnh Skill.
  2. Chạy batch eval để lấy baseline score.
  3. Thay đổi một biến (prompt hoặc model, không đổi cả hai cùng lúc).
  4. Chạy A/B test - 2 phiên bản cùng chạy trên cùng 1 input set. Comparator agents chấm điểm blind, không biết phiên bản nào là phiên bản nào.
  5. Kết quả có giá trị khi confidence > 0.90 trên 50+ examples. Chênh lệch 0.3 điểm trở lên mới đáng xét.

Sau khi Skill lên production, bật production monitoring để sample live traffic và cảnh báo khi score giảm quá ngưỡng đặt sẵn.

Nhìn về phía trước

Anthropic chia sẻ trong blog tháng 3/2026: "As models improve, the line between skill and specification may blur. Today SKILL.md is an implementation plan - how to do something. Over time, a natural-language description of what the skill should do may be enough."

Evals hiện tại đã mô tả "what" - kết quả tốt trông như thế nào. Tương lai, mô tả đó có thể chính là Skill. Đây là xu hướng cần theo dõi khi xây dựng hệ thống skill trong năm 2026.

Một Skill tốt không phải là 1 file prompt được đặt tên đẹp. Nó là 1 workflow có thể kiểm tra, đo lường và cải thiện liên tục - giống như phần mềm: viết code, viết test, đo performance, refactor. Sự khác biệt giữa Skill và Prompt nằm chính ở điểm đó.

Nguồn: Claude Code Skills docs, Improving skill-creator - Anthropic blog.