Cách viết Skill cho AI Agent: Cấu trúc, Trigger, Validate

TL;DR

Bài này hướng dẫn cách tạo skill cho AI agent: từ cấu trúc thư mục, cách viết instruction để agent hiểu, đến quy trình validate. Giúp skill của bạn chạy đúng, dễ maintain, và không ngốn token.

Nói đơn giản: Hướng dẫn cách viết “công thức” để AI agent biết làm gì, khi nào làm, và làm đúng.

Bài này dành cho ai?

1. Dev đang build AI agent hoặc workflow

Vấn đề: Viết instruction cho AI mà nó hiểu sai, làm sai, hoặc hỏi liên tục Khi nào cần: Khi cần tạo skill để agent có thể reuse cho nhiều task tương tự Được gì: Skill chạy tự động, ít token, dễ maintain

2. Người muốn tự động hóa workflow với AI

Vấn đề: AI làm việc không nhất quán, mỗi lần phải prompt lại từ đầu Khi nào cần: Khi có task lặp đi lặp lại (vd: migrate project, generate code theo template) Được gì: Workflow có thể lưu lại và xài nhiều lần

3. AI product builder

Vấn đề: Skill không discoverable, agent không biết khi nào nên dùng Khi nào cần: Khi build hệ thống agent cần chọn skill phù hợp từ nhiều options Được gì: Agent routing chính xác, ít false trigger

Các điểm chính

1. Skill cần theo cấu trúc thư mục cố định Mỗi skill gồm: SKILL.md (bắt buộc - dưới 500 dòng), scripts/ (code chạy được), references/ (context phụ), assets/ (templates). SKILL.md là “não” - dùng để navigation và high-level procedure. → Làm gì: Tạo thư mục theo format trên trước khi viết bất kỳ content nào

2. Frontmatter quyết định agent có trigger skill hay không Trường name và description trong YAML là thứ duy nhất agent thấy trước khi quyết định load skill. Description tối đa 1024 ký tự, viết theo third person, có cả “negative triggers” (khi nào KHÔNG nên dùng). → Làm gì: Viết description kiểu “Creates React components using Tailwind. Use when user wants to update styles. Don’t use for Vue or vanilla CSS”

3. Progressive disclosure - chỉ load info khi cần Giữ SKILL.md dưới 500 dòng. Chi tiết nặng nề move sang references/, scripts/, assets/. Agent sẽ không thấy các file này trừ khi bạn bảo nó đọc (“See references/auth-flow.md for error codes”). → Làm gì: Tách large config, template phức tạp ra file riêng, trong SKILL.md chỉ ghi đường dẫn

4. Viết instruction cho LLM, không phải cho human Dùng step-by-step numbering, third-person imperative (“Extract the text” thay vì “I will extract”). Template cụ thể để trong assets/ thay vì mô tả bằng prose dài. → Làm gì: Thay vì viết “JSON output nên có field X, Y, Z”, đặt file template mẫu trong assets/ rồi bảo agent “copy structure này”

5. Script phức tạp thì bundle sẵn, đừng bắt LLM viết lại Nếu agent cần parse data phức tạp hoặc query database, cho nó script Python/Bash có sẵn trong scripts/. Script phải trả về error message rõ ràng để agent tự sửa. → Làm gì: Viết script xử lý task phức tạp một lần, để trong scripts/, gọi khi cần

6. Validate skill bằng chính LLM 4 bước: (1) Discovery - test description có trigger đúng không, (2) Logic - feed toàn bộ SKILL.md rồi simulate execution, (3) Edge Case - prompt LLM tấn công logic của mình, (4) Refinement - restructure theo progressive disclosure. → Làm gì: Dùng LLM khác (hoặc chat khác) để test skill trước khi deploy

Quick Start

1. Tạo thư mục skill với cấu trúc:

   skill-name/
   ├── SKILL.md              # \<500 dòng, navigation + main steps
   ├── scripts/              # Python/Bash scripts
   ├── references/           # 1 level deep only
   └── assets/               # templates, schemas

2. Viết description tối ưu cho frontmatter - đây là thứ duy nhất agent thấy để quyết định có load skill hay không. Include cả trigger lẫn negative trigger.