Anatomy & Progressive Disclosure
Thiết kế SKILL.md, scripts, references và assets theo ba tầng context thay vì biến skill thành một prompt khổng lồ.
Catalog giúp model quyết định có nên đọc; SKILL.md điều phối workflow; resource chỉ được tải tại đúng nhánh cần nó.
Những điều cần nắm chắc
Name và description là retrieval interface của skill.
SKILL.md nên giữ đường đi chính, không chứa toàn bộ encyclopedia.
Reference phải có điều kiện đọc cụ thể, không tạo chuỗi link sâu.
Asset là input/output template; script là executable, hai loại không thể hoán đổi.
Case study trực quan
Visual được lưu local để GitHub Pages tải ổn định; mỗi case đều giữ link nguồn và chỉ ra cách biến pattern thành implementation.
Google tổ chức một skill như một sản phẩm có owner và eval
Cây thư mục này cho thấy một skill production không chỉ có instruction. Google giữ SKILL.md ở trung tâm, tách reference, script và asset; đồng thời bổ sung OWNERS, EVAL.yaml và dữ liệu nội bộ cho governance. Đây là implementation của Google, không phải toàn bộ field đều là yêu cầu của Agent Skills specification.
Vì sao pattern này hiệu quả?
- Instruction, knowledge, executable và output material có lifecycle riêng nên có thể review độc lập.
- OWNERS biến freshness thành trách nhiệm cụ thể thay vì hy vọng cộng đồng tự cập nhật.
- Eval suite đặt cạnh skill giúp thay đổi instruction đi cùng regression evidence.
Triển khai tối thiểu
- 1Bắt đầu bằng SKILL.md với trigger, workflow và done-condition tối thiểu.
- 2Chỉ tách reference hoặc script khi một decision branch thật sự cần chúng.
- 3Thêm owner, version và eval manifest theo convention của chính team/harness.
- 4Chạy schema, link và routing checks trong CI trước khi phân phối.
Caveat: Không copy nguyên cây thư mục này rồi gọi là portable standard. OWNERS, EVAL.yaml và _internal là governance convention của Google; portable contract vẫn phải được kiểm tra với Agent Skills specification và host mục tiêu.
Nội dung bài viết
Ba tầng disclosure và ba loại failure
Tầng catalog chỉ chứa metadata để routing. Nếu description kém, skill không được gọi hoặc bị gọi nhầm. Tầng instruction nạp toàn bộ SKILL.md sau activation; nếu workflow mơ hồ, execution lệch. Tầng resource chỉ nạp file hoặc chạy script theo nhánh; nếu pointer không nói khi nào đọc, context bị phình hoặc evidence bị bỏ sót.
Vì ba tầng có failure mode khác nhau, eval cũng phải tách routing eval, workflow eval và resource/tool eval.
Cấu trúc portable tối thiểu
Đặc tả Agent Skills yêu cầu thư mục có SKILL.md và frontmatter name/description. scripts, references và assets là convention tùy chọn. Một số harness bổ sung metadata riêng như agents/openai.yaml hoặc plugin manifest; đó là extension của runtime, không phải phần portable bắt buộc.
Giữ reference cách SKILL.md một cấp giúp agent resolve path ổn định. Nếu reference A lại trỏ B rồi B trỏ C, activation trở thành cuộc săn tài liệu và khó đánh giá context thực tế.
Budget context bằng decision point
Không tách file chỉ vì SKILL.md dài. Hãy tách khi nội dung chỉ cần ở một decision branch: ví dụ đọc accessibility checklist khi diff chứa UI, hoặc đọc API error catalog khi request trả non-2xx.
Một pointer tốt gồm điều kiện, path và mục tiêu đọc. “Xem references/” là pointer yếu; “Nếu bundle report tồn tại, đọc references/budget-policy.md trước khi phân loại regression” là pointer có thể thực thi và test.
Code & cấu trúc tham khảo
Skill package có disclosure boundary
1.agents/skills/frontend-production-review/2├── SKILL.md3├── references/4│ ├── accessibility.md5│ └── performance-budgets.md6├── scripts/7│ └── inspect_bundle.py8├── assets/9│ └── finding-template.md10└── agents/11 └── openai.yaml # runtime-specific, optionalTakeaway: Portable core nằm ở SKILL.md; metadata runtime-specific phải được gọi đúng tên và không giả làm standard.
Tài liệu đọc thêm
Repo, đặc tả và bài viết gốc để đi sâu sau bài học.
Agent Skills overview
Discovery, activation và execution theo progressive disclosure.
Google Antigravity Skills
Workspace/global skill locations và frontmatter trong Antigravity.
OpenAI Build Skills
Cấu trúc và workflow xây skill trong hệ sinh thái OpenAI.
Google Skills repository
Các skill production cho Google Cloud để nghiên cứu package layout và instruction style.
OpenAI Skills repository
Skill chính thức của OpenAI, hữu ích để so sánh portable core và OpenAI metadata.
Google — Build, test and scale Agent Skills
Governance, CI, ownership và continuous eval cho một skill catalog lớn.