5 nguyên tắc để viết Skill thực sự hoạt động trong Claude Code

TL;DR

Nhiều người viết Skill bằng cách nhồi mọi thứ - quy tắc, ví dụ, chú ý - vào một file duy nhất. Trông đầy đủ, nhưng thực tế không dùng được. Skill đúng nghĩa phải làm được ba việc: tự trigger đúng lúc, chạy theo quy trình cố định, và cho kết quả tốt hơn khi không có Skill. Bài này đi qua 5 nguyên tắc để đạt được điều đó - từ cách thiết kế description, phân lớp file, giới hạn quyền tool, chọn model phù hợp, đến vòng eval-iterate.

Skill là gì - và tại sao nó khác

Agent Skills được Anthropic ra mắt ngày 16/10/2025 và trở thành open standard vào 18/12/2025, hỗ trợ trên Claude.ai, Claude Code, Claude Agent SDK và Developer Platform. Về cơ bản, một Skill là một thư mục chứa file SKILL.md cùng các file hỗ trợ.

Điểm khác biệt quan trọng so với CLAUDE.md và slash command:

Loại	Khi nào vào context	Ai trigger	Dùng cho
`CLAUDE.md`	Luôn có mặt, toàn bộ nội dung	Luôn active	Facts, conventions, background
Skill	Description luôn trong context; full body chỉ khi invoke	Claude auto hoặc `/name`	Procedural workflows, checklists
Slash command	Không vào context tới khi user gọi	Manual only	Actions có side effects (deploy, commit)

Cơ chế cốt lõi là progressive disclosure: khi khởi động, agent chỉ load name và description của mỗi Skill vào system prompt (bị cap ở 1,536 ký tự). Full SKILL.md chỉ được đọc khi agent xác định Skill phù hợp với task hiện tại. Nhờ vậy, tài liệu tham khảo dài hàng nghìn từ có thể bundle vào Skill mà không tốn token - cho tới khi thực sự cần.

Khi nào chuyển từ CLAUDE.md sang Skill? Khi một section trong CLAUDE.md bắt đầu phình thành quy trình nhiều bước thay vì fact đơn giản - đó là signal rõ ràng.

Description quyết định Skill có được gọi hay không

Description là giao diện duy nhất giữa Skill và thế giới bên ngoài khi Skill chưa được load. Nó quyết định agent có nhận ra Skill phù hợp với yêu cầu của user hay không.

Vấn đề phổ biến: description quá generic. Một Skill "tạo cover image" với description Create an image. sẽ không được trigger khi user nói:

"Làm cho tôi một ảnh bìa bài viết này"
"Tạo thumbnail kiểu công nghệ"
"Cần một banner cho bài dài"

Description nên phản ánh cách người dùng thực tế diễn đạt nhu cầu, không phải cách bạn mô tả chức năng. Ngoài description, frontmatter còn có field when_to_use để bổ sung trigger phrases và ví dụ cụ thể - tổng cộng bị cap 1,536 ký tự.

Hai flag quan trọng để kiểm soát ai trigger Skill:

disable-model-invocation: true - chỉ user mới invoke được, description không vào context (tiết kiệm token). Dùng cho /deploy, /commit - actions có side effects không muốn Claude tự quyết.
user-invocable: false - chỉ Claude tự trigger, không hiện trong menu /. Dùng cho background knowledge (ví dụ: legacy-system-context).

Khi bạn có nhiều Skill hoặc một Skill rất dài và ít dùng (ví dụ: skill viết resume, skill tổng kết năm), nên set disable-model-invocation: true để giảm constant context overhead.

Phân lớp file - SKILL.md là entry point, không phải kho chứa

SKILL.md nên giữ dưới 500 dòng. Vượt quá con số này, context bị ngốn tức thì, performance Claude Code giảm, thinking time tăng, và có thể trigger Compact khiến agent "mất trí nhớ" giữa chừng.

Cấu trúc đúng là phân lớp:

my-skill/
  SKILL.md              # entry point: trigger, nguyên tắc, bước thực hiện
  references/           # tài liệu dài, style guide, case phức tạp
  scripts/              # code thực thi (deterministic, ổn hơn để model generate)
  assets/               # template, schema, ví dụ output

Trong SKILL.md, chỉ cần reference tới các file này và mô tả khi nào cần đọc chúng. Agent sẽ tự quyết định có cần load references/comparison-table.md hay không dựa trên context của task - thay vì luôn nạp toàn bộ vào memory.

Nguyên tắc: đưa vào SKILL.md những gì agent cần biết để bắt đầu task; để lại những gì agent chỉ cần trong một số scenario.

Quyền tool và model - ít là đủ

Field allowed-tools pre-approve tools khi Skill active, không cần confirm từng lần. Nhưng nó không restrict - mọi tool vẫn callable theo permission settings chung.

Nguyên tắc: chỉ cho Skill quyền tối thiểu cần để hoàn thành task.

Skill chỉ đọc & phân tích code: allowed-tools: Read Grep
Skill tạo báo cáo: allowed-tools: Read Write
Skill chạy script Python: allowed-tools: Bash(python3 *)
Skill batch xử lý file: allowed-tools: Read Write Edit Bash

Tool càng nhiều không phải càng mạnh - đôi khi chỉ là rủi ro cao hơn.

Field model cho phép override model cho turn đó (không lưu vào session). Ví dụ thực tế:

Skill viết tài liệu kỹ thuật: model mạnh về writing & summarization
Skill data analysis: model inference tốt nhưng cost thấp hơn
Skill batch crawl/extract: model nhanh & rẻ là đủ
Skill viết bài dài: model có khả năng reasoning & structure tốt

Field effort (low/medium/high/xhigh/max) cho phép tune thêm reasoning level. Skill đơn giản không cần effort max.

Eval - vòng lặp không thể bỏ qua

Skill viết xong không có nghĩa là nó hoạt động. Anthropic khuyến cáo tư duy: không publish Skill chỉ dựa trên cảm giác. Cần test data, chạy eval, xem kết quả, rồi iterate.

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

Verify có chạy được không - file path đúng, tool permission đủ, script execute được, template load được
Verify trigger đúng không - chuẩn bị 5-10 câu user thực tế có thể nói; test cả chiều nên trigger lẫn không nên trigger (class-imbalanced eval là sai)
Chuẩn bị test data - mô tả trước "thế nào là output tốt"; để agent tự generate batch test cases đầu tiên, bạn chỉ cần review
Chấm điểm 0-10 - 0-2: sai hoàn toàn; 5-6: tạm dùng được; 7-8: ổn định; 9-10: đạt chuẩn. Minimum: case chính phải đạt ít nhất 5
So sánh với baseline - chạy cùng task có Skill vs. không có Skill; nếu điểm ngang nhau, Skill chưa add value thực sự
Iterate theo điểm thấp - trigger fail: bổ sung description; output format không ổn: thêm ví dụ vào assets/; logic không deterministic: viết thành script

Anthropic phân loại grader thành 3 loại: code-based (nhanh, rẻ, deterministic - dùng cho format check, tool call verification), model-based (flexible, handle open-ended output), và human (gold standard, dùng để calibrate model grader). Skill quan trọng nên có cả ba.

Kế tiếp

Agent Skills hiện hỗ trợ trên Claude.ai, Claude Code, Agent SDK và Developer Platform. Roadmap của Anthropic bao gồm: full lifecycle management (create, edit, discover, share), tích hợp MCP để build complex workflows với external tools, và dài hạn - cho phép agent tự tạo & evaluate Skills dựa trên pattern thành công của chính nó.

Nếu bạn đang viết Skill lần đầu, bắt đầu từ đây: đọc Anthropic Engineering: Agent Skills và Claude Code Skills Docs. Sau đó chạy agent trên một task thực tế, quan sát nó fail ở đâu - đó mới là nơi Skill thực sự cần thiết.

Nguồn: Anthropic Engineering, Claude Code Docs, Demystifying Evals.