Agent Skills Deep Dive
Tạo capability tái sử dụng bằng AGENTS.md, SKILL.md, scripts, references, assets và eval.
AGENTS.md đặt luật chơi thường trực; SKILL.md đóng gói workflow chỉ nạp khi phù hợp; scripts biến bước cần tính xác định thành code; harness khám phá và thực thi chúng.
Những điều cần nắm chắc
Instruction, skill, script, tool và sub-agent giải quyết các lớp vấn đề khác nhau.
Description của skill là routing contract, không phải câu quảng cáo.
Script không tự chạy chỉ vì nằm trong thư mục skill.
Skill cần eval cho trigger đúng, trigger sai và failure recovery.
Agent Skills Studio
Thay đổi skill contract, quan sát context được nạp và pressure-test behavior. Mọi phép tính chạy trong trình duyệt, không gửi prompt ra ngoài.
Animated runtime trace
Từ prompt đến khi script thực sự chạy
Đây là mental model của agent loop: instruction tạo quyết định, còn harness mới tạo execution và kiểm soát side effect.
Harness đưa name, description và path vào danh sách skill. Model so khớp task; chưa đọc toàn bộ SKILL.md.
Clickable package anatomy
File nào được ai đọc, vào lúc nào?
SKILL.md- Ai đọc?
- Mọi host hỗ trợ Agent Skills
- Khi nào?
- Được đọc đầy đủ sau khi skill được chọn.
- Ảnh hưởng context
- Frontmatter name/description phục vụ discovery; phần body định nghĩa workflow, input, output và done-condition.
- Ảnh hưởng side effect
- Chỉ thay đổi quyết định của model. Bản thân Markdown không chạy command và không cấp permission.
Failure mode: Description mơ hồ gây route sai; body mơ hồ gây workflow thiếu bước.
Nội dung bài viết
1. Instruction không đồng nghĩa capability
Một prompt như “review accessibility thật kỹ” chỉ nêu ý định. Capability tái sử dụng phải mô tả phạm vi, trigger, workflow, nguồn tham chiếu, tool, định dạng đầu ra và bước xác minh.
Quy tắc luôn đúng với repository thuộc về AGENTS.md. Workflow chuyên môn chỉ cần theo tình huống thuộc về skill. Phép tính hoặc transformation cần tính xác định nên nằm trong script. Truy cập dịch vụ bên ngoài thuộc về tool hoặc MCP.
2. AGENTS.md, AGENTS.override.md và CLAUDE.md
Codex đọc AGENTS.md trước khi làm việc và ghép chỉ dẫn từ global scope xuống repository rồi đến thư mục hiện tại. Chỉ dẫn gần code đang làm việc hơn có độ ưu tiên cao hơn; AGENTS.override.md thay thế file thường ở cùng scope.
CLAUDE.md phục vụ nhóm nhu cầu tương tự nhưng là convention của Claude Code. Codex không mặc định coi mọi CLAUDE.md là instruction file; có thể cấu hình fallback filename nếu dự án thực sự cần hỗ trợ convention khác.
- AGENTS.md: agent phải tuân thủ quy tắc nào trong phạm vi này?
- SKILL.md: khi workflow này được kích hoạt, agent phải làm như thế nào?
- README: con người cần biết gì để hiểu và sử dụng dự án?
3. Anatomy của một Agent Skill
Một skill là thư mục có SKILL.md bắt buộc. scripts, references, assets và agents/openai.yaml đều tùy chọn; chỉ thêm chúng khi giúp workflow rõ hơn hoặc đáng tin cậy hơn.
SKILL.md chứa metadata định tuyến và instruction. references tách tài liệu dài khỏi workflow chính. assets chứa template hoặc tài nguyên đầu ra. scripts chứa executable code. agents/openai.yaml có thể mô tả UI metadata, invocation policy và dependency.
4. Discovery và progressive disclosure
Harness không nhét toàn bộ mọi skill vào context. Codex bắt đầu từ name, description và path; chỉ khi người dùng gọi trực tiếp hoặc task khớp description thì toàn bộ SKILL.md mới được đọc.
Description quá rộng gây kích hoạt nhầm; description chỉ mang tính quảng cáo khiến skill bị bỏ lỡ. Một description tốt nêu action, artifact, trigger và cả trường hợp không nên dùng.
5. script.py dùng để làm gì?
script.py chỉ là ví dụ tên file; skill có thể dùng Python, TypeScript, shell hoặc binary phù hợp. Script dành cho validation, conversion, extraction, rendering và phép tính cần kết quả lặp lại.
SKILL.md phải nói rõ command, working directory, input, output, exit code và failure handling. Script cần validate input, tránh in secret, không lách sandbox và không ghi đè dữ liệu ngoài phạm vi.
6. Quy trình tạo skill từ con số 0
Bắt đầu từ một workflow thực sự lặp lại. Thu thập ba đến năm prompt đại diện, output mong muốn và lỗi thường gặp. Đây chính là eval set ban đầu.
Viết contract trước: goal, trigger, non-trigger, input, output, quyền, side effect và definition of done. Sau đó tạo skill instruction-only nhỏ nhất; chỉ thêm reference hoặc script tại nơi model thiếu ổn định.
- Chọn workflow có đầu ra kiểm chứng được.
- Định nghĩa trigger và near-miss prompt.
- Viết SKILL.md instruction-only trước.
- Thêm reference cho kiến thức dài và script cho bước deterministic.
- Chạy eval rồi điều chỉnh boundary dựa trên failure thật.
7. Test skill như test một sản phẩm
Routing eval kiểm tra skill có được chọn đúng không. Execution eval kiểm tra sau khi chọn, agent có tuân thủ workflow và tạo đúng artifact không. Hai nhóm lỗi này cần được chẩn đoán riêng.
Ngoài happy path, phải kiểm tra prompt gần giống nhưng ngoài phạm vi, input thiếu, script lỗi, tool không có quyền, reference vắng mặt và yêu cầu có side effect.
8. Workshop frontend-production-review
Học viên tạo skill review thay đổi React/Next.js về accessibility, responsive layout, state UX và performance. AGENTS.md giữ quy tắc repository; SKILL.md điều phối review; references chứa checklist; script đọc bundle report; assets chứa report template.
Definition of Done: gọi trực tiếp được, tự kích hoạt đúng prompt review, không kích hoạt cho yêu cầu xây UI mới, báo lỗi rõ khi thiếu input và tạo finding có severity cùng evidence.
Code & cấu trúc tham khảo
Cấu trúc skill
1.agents/skills/frontend-production-review/2├── SKILL.md3├── references/4│ └── accessibility-checklist.md5├── scripts/6│ └── inspect_bundle.py7├── assets/8│ └── review-template.md9└── agents/10 └── openai.yamlTakeaway: SKILL.md là bắt buộc; các thành phần khác chỉ xuất hiện khi phục vụ workflow.
SKILL.md có routing boundary
1---2name: frontend-production-review3description: Review existing React or Next.js UI changes for accessibility, responsive behavior, state UX, and performance. Use for audit requests; do not use to build a new interface.4---56# Frontend Production Review78## Workflow91. Inspect changed UI files and repository instructions.102. Read references/accessibility-checklist.md.113. Run scripts/inspect_bundle.py only when a report exists.124. Classify findings and cite evidence.1314## Boundaries15- Do not modify files unless the user asks for a fix.16- Report missing evidence instead of inventing it.Takeaway: Description điều khiển routing; body điều khiển execution; boundary ngăn skill tự mở rộng quyền.
Script deterministic có contract rõ
1#!/usr/bin/env python32import json3import sys4from pathlib import Path56if len(sys.argv) != 2:7 raise SystemExit('usage: inspect_bundle.py <report.json>')89report = Path(sys.argv[1]).resolve()10if not report.is_file():11 raise SystemExit(f'report not found: {report}')1213data = json.loads(report.read_text(encoding='utf-8'))14routes = sorted(data['routes'], key=lambda item: item['bytes'], reverse=True)15print(json.dumps({'largestRoutes': routes[:5]}))Takeaway: Script validate input, báo lỗi bằng exit code và trả output có cấu trúc để agent tổng hợp.
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.
Build skills — Official OpenAI Docs
Cấu trúc, progressive disclosure, discovery và phân phối skills.
Custom instructions with AGENTS.md
Discovery chain, precedence, overrides và verification.
Agent Skills specification
Portable format cho SKILL.md, metadata và bundled resources.
OpenAI Skills repository
Các skill thực tế được duy trì bởi OpenAI để nghiên cứu instruction và resource layout.
Google Skills repository
Skill catalog mã nguồn mở cho Google Cloud với governance và eval workflow.
Anthropic Skills repository
Ví dụ skill, document creation workflow và progressive disclosure từ Anthropic.
Superpowers
Skill framework áp process discipline, TDD, planning và delegated development.