Agent Skills và SKILL.md: Đo lường cơ chế tiết lộ dần

Chương 14 đặt ra quy tắc cho nửa sau của khóa học này — kết nối, thử lại và hủy là TypeScript — và nêu năm ngoại lệ. Đây là một trong số đó, và lý do không phải là sở thích.

Một skill là một file Markdown. Không phải một file cấu hình chương trình, không phải một file để chương trình biên dịch: mà là một tài liệu model đọc, giống như cách nó đọc tin nhắn bạn gõ. Gán cho chương này một ngôn ngữ lập trình nghĩa là chưa hiểu định dạng, và sự hiểu nhầm đó là hiểu nhầm phổ biến nhất về skill. Mọi thứ bên dưới là Markdown và YAML, cộng với một shell script nhỏ tồn tại chính để cho thấy code nên và không nên nằm ở đâu bên trong một skill.

Đây là một hướng dẫn thật: cách một công ty viết release notes. Nó là một quy trình, không phải một sở thích — nó có một tập bước theo thứ tự, một taxonomy, một giọng văn, một template và một script thu thập nguyên liệu thô.

Đưa toàn bộ vào system prompt, như cách hầu hết đội ngũ làm, và phép tính của Chương 16 sẽ tiếp quản. System prompt là một tiền tố, và một tiền tố được trả phí trên mọi call. Đo bằng o200k_base trên thư mục viết cho chương này:

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

Rẻ hơn hai mươi bốn lần khi được dùng, rẻ hơn ba mươi bảy lần khi không dùng. Mức giá là của Chương 16: $2,00 cho mỗi triệu input token.

Giờ là phản biện trung thực, vì một chương bỏ qua nó sẽ thành quảng cáo. Prompt caching gần như khép lại khoảng cách tiền bạc. System prompt ổn định và nằm đầu tiên, khiến nó là ứng viên cache tốt nhất có thể; ở mức $0,20 mỗi triệu input đã cache, cùng 68.640 token đó tốn $0,0168 thay vì $0,1373. Vẫn gấp ba lần skill, nhưng không còn khác một bậc độ lớn.

Tiền chưa bao giờ là lập luận mạnh nhất. Lập luận này mới là:

Caching làm cho một tiền tố vĩnh viễn rẻ hơn. Nó không làm tiền tố đó nhỏ hơn.

Ở lượt 40, phiên bản system-prompt vẫn có 1.716 token chính sách release-note nằm trong window trong một cuộc trò chuyện về chuyện hoàn toàn khác, cạnh tranh với thứ mà Chương 24 gọi là ngân sách attention của model. Phiên bản skill có 46. Cache nhầm thứ, và bạn đã mua được giảm giá cho một sự phân tâm.

Viết dưới dạng công thức, với $n$ lượt, $L_1$ là metadata, $L_2$ là body, $L_3$ là toàn bộ gói và $R$ là tập các file đi kèm thực sự được đọc:

Toàn bộ chương này là khác biệt giữa việc nhân hạng tử thứ hai với $n$ và nhân nó với một hoặc với không.

Một skill là một thư mục. Đặc tả đủ ngắn để nêu trọn vẹn:

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.md phải bắt đầu bằng YAML frontmatter, và đúng hai trường là bắt buộc: name và description.¹ Bốn trường nữa là tùy chọn và không có trường nào khác được định nghĩa:

Đây là skill release-notes, đầy đủ, với body dưới ba mươi dòng:

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

Hãy đọc xem body đó là gì. Nó không phải là chính sách — nó là một mục lục kèm thứ tự thao tác. Chính sách nằm trong ba file mà nó nêu tên nhưng không đưa vào. Và bước một giao việc cho một script, vì code của script không bao giờ đi vào context window: chỉ output của nó đi vào.²

Mô hình tải có một cái tên và ba giai đoạn. Đặc tả nêu chúng kèm một ngân sách token:¹

1. Metadata, khoảng 100 token: name và description, được tải khi khởi động cho mọi skill đã cài.
2. Instructions, khuyến nghị dưới 5.000 token: body SKILL.md, được tải khi skill được kích hoạt.
3. Resources, khi cần: các file đi kèm, chỉ được tải khi có thứ gì đó yêu cầu chúng.

Tài liệu tham chiếu đặt một cột thứ tư trên cùng bảng — khi nào được tải, chi phí token, nội dung — và hàng quan trọng là hàng thứ ba: không tốn gì cho đến khi được truy cập.³ Câu tóm tắt toàn bộ chương cũng nằm ở đó:

Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.³

Bảng đo ở đầu chương này là tuyên bố đó được kiểm tra trên năm skill không ai viết riêng cho bài này. Hai hàng đáng được đọc đối chiếu với nhau.

next-best-practices có body 966 token liên kết tới mười chín file chứa 19.374 token. Yêu cầu nó sửa lỗi hydration và agent đọc body cộng với hydration-error.md: 1.409 token trên 20.340, hệ số mười bốn, và mười tám file còn lại không bao giờ được mở.

next-cache-components có body 2.334 token và không có file đi kèm nào. Nó là một skill hợp lệ và được viết tốt, và nó không có level 3 để tiết lộ. Đó là giới hạn trung thực của kỹ thuật này: tiết lộ dần chỉ tiết kiệm nếu có thứ gì đó để trì hoãn. Một skill có tri thức không thể phân rã sẽ trả toàn bộ body khi kích hoạt, và đòn bẩy còn lại duy nhất là không kích hoạt nó.

Level 1 là một quyết định routing được đưa ra từ một câu. Không điều gì khác về skill ảnh hưởng đến việc nó có bao giờ được mở hay không — không phải chất lượng body, không phải ví dụ, không phải script. Vì vậy description không phải documentation. Nó là query surface, và nó có thể sai.

Đặc tả nói điều đó dưới dạng một ví dụ tốt và một ví dụ tệ, và ví dụ tệ chỉ có bốn từ: description: Helps with PDFs.¹ Điều đó đáng được đo thay vì cứ chấp nhận.

Sáu skill, mỗi skill có một description hợp lý nói nó làm gì và khi nào dùng. Hai mươi bốn request, bốn request cho mỗi skill, được diễn đạt như một người thật sẽ diễn đạt và không bao giờ nêu tên skill. Model thấy sáu dòng trong system prompt và phải trả lời bằng một tên hoặc bằng NONE. Greedy decoding, nên nó tái lập được. Sau đó là cùng hai mươi bốn request với cùng sáu skill, và các description bị cắt xuống còn chủ đề trần trụi.

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

Hãy đọc các khoảng trước, như Chương 4 đã nhấn mạnh và Chương 29 sẽ lại nhấn mạnh: chúng chồng lấp, và hai mươi bốn ca không thể xếp hạng hai hệ thống chỉ bằng tổng hợp của chúng. So sánh theo cặp mới là thứ chốt lại, và đó là công cụ của Chương 15: trong mười ca hai nhánh bất đồng, chín ca thuộc về description giàu thông tin và một ca thuộc về description mỏng. Điều đó được xác lập ở ngưỡng thông thường.

Giờ hãy đọc dòng cuối, cũng là phát hiện thực sự. Với description mỏng, model trả lời NONE ở chín trên hai mươi bốn request. Không phải skill sai: mà là không có skill. Đây là bốn trong số đó, nguyên văn:

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

Một skill sql-review hoàn hảo đã được cài đặt, có body, ví dụ và checklist, và nó không bao giờ được mở, ba lần liên tiếp, trên ba câu hỏi mà nó được viết ra để xử lý. Level 2 và 3 không liên quan gì với một skill mà level 1 không bao giờ chạm tới.

Chi phí để sửa: 214 token, chênh lệch giữa 295 và 81, trải trên sáu skill. Đó là phát hiện của Chương 18 đi tới từ phía ngược lại. Ở đó, chỉ thay description của một công cụ đã đưa định dạng ngày từ 2 đúng trên 24 lên 24 đúng trên 24. Ở đây, chỉ thay description của một skill đưa activation từ 10 trên 24 lên 18. Trong cả hai trường hợp, cách sửa rẻ nhất trong hệ thống là một câu, và trong cả hai trường hợp câu đó phải nêu trigger chứ không chỉ nêu chủ đề: không phải thứ đó là gì, mà là người dùng vừa nói gì khi nó áp dụng.

Một lưu ý mà chương này nợ chính tiêu chuẩn của mình. Đây là model nửa tỷ parameter, và frontier model routing tốt hơn 75 % rất nhiều. Hãy đọc cơ chế, không phải độ lớn: tín hiệu routing chỉ dài một câu bất kể model nào đọc nó, và không model nào có thể chọn dựa trên thông tin bạn không đặt vào câu đó.

Lỗi thứ hai trái ngược với lỗi thứ nhất. Skill được tìm thấy, các level được chia đúng, và agent vẫn đọc tất cả.

vercel-react-best-practices là một skill thực sự được xây dựng tốt. Body 1.670 token của nó là một bảng ưu tiên gồm tám category và một tham chiếu nhanh nêu tên 70 file quy tắc, mỗi file một dòng. Các quy tắc nằm trên disk bên cạnh nó: 70 file, nhỏ nhất 132 token, trung vị 319, lớn nhất 1.052. Hỏi nó một câu về barrel imports và chi phí trung thực là body cộng một file — dưới 2.400 token so với một bundle 53.670.

Rồi dòng cuối của body nói thế này:

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md là 26.362 token. Nó là 70 file quy tắc được nối lại: tổng của chúng là 25.784, và phần chênh lệch là các heading giữa chúng. Vậy skill cho agent một lựa chọn giữa việc đọc một quy tắc trung vị 319 token và đọc cùng nội dung đó, toàn bộ, với giá đắt gấp tám mươi ba lần — và nó đưa ra lựa chọn đó trong một câu không gắn chi phí và không có điều kiện khi nào nên làm.

Đó không phải bug và file không sai; một tài liệu đã biên dịch thật sự hữu ích cho con người, và cho một agent được yêu cầu audit cả codebase. Nó là một file level-3 với lời mời level-2, và bài học khái quát vượt khỏi skill này: mọi đường dẫn ra khỏi một SKILL.md nên nói nó tốn gì và khi nào đáng dùng, vì model không có cách nào biết rằng một filename đắt gấp tám mươi ba lần filename phía trên nó.

Cùng thư mục đó mang một bài học nhỏ hơn về sự lỗi thời. Body nói "70 rules across 8 categories" và liệt kê 70; thư mục rules/ chứa 72 file, trong đó hai file là scaffolding (_template.md và _sections.md); còn sidecar metadata.json nói "40+ rules". Ba con số cho cùng một tập trong một thư mục, một cái đúng, một cái là phép tính, và một cái còn sót lại từ phiên bản cũ. Một skill là một tài liệu, và tài liệu mục rữa đúng như một comment trong code đã trôi xa khỏi đoạn code bên cạnh nó — khác ở chỗ tài liệu này được đọc bởi một cỗ máy sẽ không nhướng mày.

Đặc tả mở định nghĩa sáu trường frontmatter. Reference implementation, Claude Code, chấp nhận hai mươi.² Năm nhóm đáng biết tên, vì đó là nơi định dạng ngừng chỉ là một tài liệu:

Arguments (arguments, argument-hint) cho phép một người truyền các giá trị được thay vào body, khiến skill có thể dùng như một slash command. Scoping (paths) giới hạn activation vào các file khớp glob. Và dynamic context injection là thứ thay đổi mô hình tư duy: một dòng dạng !`git diff HEAD` chạy trước khi body được gửi, và output của nó được thay vào text. Tài liệu là một template, và một phần của nó được tính tại thời điểm đọc.

Giờ là cái bẫy, và nó được nêu trong cùng tài liệu: bên ngoài Claude Code — trên sản phẩm web, qua Skills API, trong packaging — chỉ sáu trường được đặc tả là được phép, và mọi trường khác là hard error khi upload.² Vì vậy một skill hoạt động hoàn hảo trong một sản phẩm lại không cài được trong một sản phẩm khác thuộc cùng vendor, và nó fail ở frontmatter chứ không phải ở thứ gì bạn có thể kiểm thử bằng cách đọc prose. Nếu bạn muốn một skill portable, sáu trường là toàn bộ ngân sách. Nếu không, hãy nói vậy trong compatibility, trường tồn tại chính vì việc này.

Bốn thứ liên tục bị nhầm lẫn với nhau, và nhầm lẫn này không phải là câu nệ từ vựng: chọn sai sẽ tốn tiền ở mọi lượt, hoặc làm bạn mất một bảo đảm mà bạn tưởng mình có.

Hai hàng in đậm là toàn bộ khác biệt. Một skill được đọc; một công cụ được invoked. Một skill là prose đi vào context window và cạnh tranh attention với mọi thứ khác trong đó; model có thể làm theo, đọc sai, hoặc bỏ qua, và không gì trong hệ thống nhận ra. Một công cụ là một call rời khỏi tay model hoàn toàn: code của bạn nhận argument, validate chúng, kiểm tra quyền và quyết định. Chương 18 diễn đạt là model đề xuất còn code của bạn định đoạt, và sự phân chia đó chính xác là thứ skill không có.

Vậy sáu trường hợp thật, được phân giải:

Lịch sử ngắn, được ghi ngày tháng bất thường rõ, và là phần hầu như không ai kể.

Agent Skills được công bố vào 16 tháng 10 năm 2025 như một tính năng của một vendor, được định nghĩa trong thông báo đó là "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks", với ba level được mô tả qua một phép so sánh đáng giữ lại: "like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix".⁴

Vào 18 tháng 12 năm 2025, cùng trang đó được cập nhật để công bố định dạng này như một tiêu chuẩn mở, với đặc tả riêng tại agentskills.io, governance mở cho đóng góp, và một reference validator.³ Đọc vào 7 tháng 9 năm 2026, showcase client của tiêu chuẩn liệt kê bốn mươi sáu sản phẩm — editor, terminal, cloud platform và mobile runtime, bao gồm các coding agent first-party của Anthropic, OpenAI, Google và Mistral — mỗi sản phẩm liên kết tới tài liệu thiết lập riêng.¹

Sự hội tụ với MCP đang được thực hiện công khai, với những con số bạn có thể kiểm tra:

Điều thú vị là việc đóng, không phải các đề xuất. SEP-2076 đề nghị một primitive thứ tư bên cạnh tools, resources và prompts. Working group hình thành từ nó quyết định câu trả lời là không: skill cưỡi trên primitive resources vốn đã tồn tại, như một extension opt-in.⁵ Chương 26 đo cùng bản năng đó trong changelog của chính protocol, nơi sampling, roots và logging bị deprecated thay vì được giữ. Một standards body xóa bỏ đề xuất do chính mình viết ra là đang hành xử tốt, và lý do kể câu chuyện này với các con số đặt phía trước là các bản tóm tắt bạn sẽ đọc ở nơi khác vẫn mô tả skill như một MCP primitive.

Giờ bạn có thể viết một SKILL.md, chia nó thành ba level tự trả được chi phí, đọc frontmatter của skill người khác và biết trường nào sẽ không sống sót khi upload sang nơi khác, và trả lời câu hỏi mà toàn bộ chương này được xây quanh — system prompt, skill, công cụ, hay server — bằng lý do thay vì thói quen.

Điều bạn chưa thể làm là biết liệu cái của bạn có hoạt động hay không.

Mọi tuyên bố quan trọng trong chương này đều là phép đo, và tuyên bố quan trọng nhất là một độ chính xác: 18 trên 24 so với 10 trên 24, có khoảng cho mỗi bên và một kiểm định theo cặp giữa chúng, vì hai tổng hợp chồng lấp không quyết định gì. Công cụ đó được mượn. Description của một skill là routing key, body của nó là một quy trình mà model có thể hoặc không thể làm theo, và cả hai đều là những thuộc tính bạn chỉ có thể biết bằng cách chạy thứ đó nhiều lần và chấm điểm thứ trả về — tức một golden set, một grader bạn viết trước khi chạy, và metric hỏi liệu nó có hoạt động mọi lần chứ không phải ít nhất một lần hay không.

Chương 29 là chuyện đó, và nó mở bằng con số mà phương pháp của chương này phụ thuộc vào: một agent thành công bảy lần trên mười trông như 70 %, và pass^10 của nó — xác suất nó thành công cả mười lần — là không. Chương đó cũng đo ba grader trên cùng hai trăm transcript và nhận 0 %, 13 % và 26 % mà không regenerate một token nào. Trước khi bạn tin câu vừa viết vào một description, bạn cần công cụ có thể cho biết nó tệ hơn câu bạn thay thế.

Mọi token count trong chương này được tạo cục bộ bằng tiktoken 0.14.0 và encoding o200k_base, vào 7 tháng 9 năm 2026: trên năm skill bên thứ ba được liệt kê ở đầu chương này, và trên skill release-notes được viết cho chương này, có toàn bộ text được tái hiện một phần ở trên. Level 1 được đo là dòng đơn - name: description mà host render vào system prompt; level 2 là body SKILL.md sau frontmatter; level 3 là mọi file khác trong thư mục. Chi phí dùng các mức giá đo được ở Chương 16 cho gpt-5.6-terra, $2,00 mỗi triệu input token và $0,20 mỗi triệu input token đã cache, áp dụng cho các count đó — chúng là phép tính trên token đã đo, không phải quan sát từ hóa đơn live. Không có paid API nào được gọi để viết chương này.

Thí nghiệm activation chạy Qwen/Qwen2.5-0.5B-Instruct ở half precision trên một GPU phổ thông, greedy decoding, 24 request trên sáu skill, hai lần — một lần với description nêu skill làm gì và khi nào áp dụng, một lần với description bị cắt còn chủ đề trần trụi theo kiểu "poor example" của chính đặc tả. Các khoảng là Wilson ở 95 %; so sánh theo cặp là exact sign test hai phía trên mười ca bất đồng; khoảng Wilson là của Chương 4 và exact paired sign test là của Chương 15, cả hai được dùng lại nguyên vẹn. Hãy đọc các độ lớn như thuộc tính của một model rất nhỏ và phương pháp như thứ có thể chuyển giao.

Năm skill được đo ở đây là package bên thứ ba, không được viết cho chương này: next-best-practices và next-cache-components từ vercel-labs/next-skills, và vercel-composition-patterns, vercel-react-best-practices và vercel-react-native-skills từ vercel-labs/agent-skills. Các count nội bộ của chúng — 70 file quy tắc, AGENTS.md ở mức 26.362 token, metadata.json ghi ngày tháng 1 năm 2026 và tuyên bố "40+ rules" — được đọc từ các file trên disk vào 7 tháng 9 năm 2026 và là thuộc tính của phiên bản đã xuất bản đó, không phải phê bình tác giả của chúng: mỗi điều trong số đó là kiểu drift xuất hiện trong bất kỳ documentation tree nào được chỉnh sửa thường xuyên hơn được đếm.