Authoring: Trigger, Contract & Composition
Viết description có boundary, workflow có completion criteria và skill nhỏ có thể compose theo pattern từ Matt Pocock và Superpowers.
Description là routing contract; body là execution contract; completion criteria là verification contract.
Những điều cần nắm chắc
Description cần cả positive trigger và boundary đủ phân biệt near-miss.
Skill nhỏ, composable thường dễ route và dễ eval hơn framework ôm toàn quy trình.
User-invoked skill phù hợp orchestration có chủ ý; model-invoked skill phù hợp discipline tái sử dụng.
Instruction tốt tạo cùng process dưới nhiều input, không ép mọi lần sinh cùng câu chữ.
Nội dung bài viết
Học từ Matt Pocock: giữ quyền điều khiển và compose primitives
Repository mattpocock/skills tách user-invoked skill dùng để orchestration khỏi model-invoked skill chứa discipline tái sử dụng. Một router có thể chọn flow, nhưng primitive không nên phụ thuộc vào một mega-framework sở hữu toàn session.
Điểm tinh tế không phải “skill càng ngắn càng tốt”, mà là mỗi skill có một reason to change và một invocation boundary rõ. Grilling, diagnosis, TDD và code review có thể compose, nhưng mỗi phần vẫn test được độc lập.
Description tối ưu retrieval, không tóm tắt giáo trình
Đặc tả yêu cầu description nói skill làm gì và khi nào dùng. Trong thực tế, symptom và near-miss quan trọng hơn slogan. “Helps with frontend” không tạo tín hiệu; “Review existing React UI changes for accessibility and responsive regressions; do not use to build a new screen” tạo decision boundary.
Không dựa hoàn toàn vào keyword. Model routing dùng semantic match, nên description cần artifact, action, trạng thái hiện tại và trường hợp loại trừ.
Body phải có observable completion criteria
“Review carefully” là intention, không phải workflow. Một step mạnh nói phải kiểm tra artifact nào, tạo evidence gì và điều kiện nào cho phép đi tiếp. Completion criteria kéo theo legwork: agent phải chạy test thật thay vì chỉ tuyên bố đã kiểm tra.
Mỗi step nên phân biệt rigid rule và flexible heuristic. Nếu mọi câu đều viết như tuyệt đối, agent không biết phần nào được trade-off; nếu mọi câu đều mềm, workflow biến thành gợi ý có thể bỏ qua.
Code & cấu trúc tham khảo
SKILL.md có routing boundary và definition of done
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. Read repository instructions and inspect the changed UI files.102. Classify findings by severity and cite file-level evidence.113. Run the relevant static checks without modifying code.1213## Done when14- Every finding has impact, evidence, and a concrete remediation.15- Passed checks and unavailable checks are reported separately.16- No file is changed unless the user requested a fix.Takeaway: Trigger, workflow và done-condition giải quyết ba failure mode khác nhau.
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.
Matt Pocock — Skills for Real Engineers
Skill nhỏ, composable và phân loại user/model-invoked.
Writing for agents
Completion criteria, leading words và pruning agent-facing text.
Best practices for skill creators
Scope, examples và progressive disclosure cho skill author.
Superpowers — writing skills
Skill discovery optimization, flowchart boundary và TDD cho process documentation.