วิธีเขียน AI Agent Skill File ให้ลดการเดาและนำไปใช้ได้จริง

Prompt สามารถบอก Agent ว่า “รอบนี้ให้ทำอะไร” ส่วน Skill file ใช้บันทึกว่า “งานประเภทนี้ ทีมของเราทำกันอย่างไร”

ความแตกต่างนี้สำคัญสำหรับ Developer ครับ เพราะต่อให้ Agent เข้าถึง Repository และมีเครื่องมือที่ต้องใช้ครบ มันก็ยังต้องตัดสินใจเรื่องขอบเขต การเลือก Reference, Validation และวิธีรับมือเมื่อทำงานต่อไม่ได้

ถ้าเราไม่กำหนดสิ่งเหล่านี้ ผลลัพธ์อาจถูกต้องในทางเทคนิค แต่ยังเป็นคนละอย่างกับที่เราต้องการ

บทความนี้จะลองสร้าง Skill ไฟล์เล็กๆ สำหรับ Review การเปลี่ยน API Spec และจุดประสงค์ ของผมไม่ใช่ ต้องการสร้าง template ว่าทุก skill จะต้องใช้รูปแบบนี้เหมือนกัน หรือทุก Platform จะต้องเขียนแบบนี้เหมือนกัน แต่เป็นการแสดงวิธีการเปลี่ยน คำสั่งหรือ skill ที่กำกวมให้เป็น Workflow ที่ Agent ทำตามและตรวจสอบได้

วิธีค้นหา Skill ของ AI หรือโหลดคำสั่ง และเรียกใช้เครื่องมือขึ้นอยู่กับพฤติกรรมของแต่ละ Model รวมถึง Agent runtime, system instructions และเครื่องมือที่เปิดให้ใช้ โครงสร้างในบทความนี้จึงเป็น Design pattern แบบ Generic ที่ต้องปรับให้เข้ากับ Platform ของคุณ

ปัญหาของคำสั่งที่ดูเหมือนจะชัด

ลองดู Prompt นี้ครับ

Review API นี้ และตรวจให้แน่ใจว่าทำตาม Best Practice

อ่านแล้วเหมือนจะเข้าใจ แต่ Agent ยังต้องตัดสินใจเองอีกหลายเรื่อง

• API contract ตัวไหนเป็น Source of truth?
• ต้องตรวจ Authentication และ Permission ด้วยหรือไม่?
• ให้แก้ Code หรือสร้าง Report อย่างเดียว?
• ต้องรัน Test อะไรบ้าง?
• ถ้าข้อมูลไม่ครบต้องทำอย่างไร?
• ผลลัพธ์แบบไหนจึงถือว่า Review เสร็จ?

แต่ละ Model อาจเติมช่องว่างเหล่านี้ไม่เหมือนกัน ผลลัพธ์จึงอาจสมเหตุสมผล แต่ไม่ตรงกับ Workflow ที่เราคิดไว้

Prompt ต่างจาก Skill อย่างไร

ผมแยกสองอย่างนี้แบบง่ายๆ ว่า

• Prompt บอกว่า “รอบนี้ให้ทำงานอะไร”
• Skill บอกว่า “งานประเภทนี้ เราทำกันอย่างไร”

Skill ที่ดีไม่ได้ทำให้ Model เก่งขึ้นแบบเสกได้ แต่มันช่วยทำให้ขอบเขตการทำงานและกติกาการตัดสินใจได้ชัดเจนขึ้น

อย่างน้อยควรมีส่วนเหล่านี้

1. Trigger: ใช้ Skill เมื่อไร
2. Goal: ต้องสร้างผลลัพธ์อะไร
3. Scope: อะไรอยู่และไม่อยู่ในขอบเขต
4. Workflow: Agent ต้องทำตามขั้นตอนไหน
5. References: ต้องอ่านข้อมูลใดภายใต้เงื่อนไขอะไร
6. Constraints: ห้ามทำหรือห้าม Claim อะไร
7. Uncertainty handling: ถ้าหลักฐานไม่ครบต้องทำอย่างไร
8. Completion criteria: ตรวจอย่างไรว่างานเสร็จจริง

โครงสร้าง Directory ที่นำไปปรับใช้ได้

ถ้า Workflow ยังสั้น เริ่มจากไฟล์เดียวก่อนก็ได้ครับ แล้วค่อยแยกเมื่อ Reference, ตัวอย่าง หรือ Script ที่ใช้ซ้ำเริ่มทำให้คำสั่งหลักอ่านยาก

api-review-skill/
├── SKILL.md
├── references/
│   ├── api-contract.md
│   ├── security-rules.md
│   ├── output-examples.md
│   └── troubleshooting.md
├── scripts/
│   └── validate.sh
└── assets/
    └── review-template.md

ชื่อไฟล์และ Directory ที่รองรับจริงขึ้นอยู่กับ Platform และ runtime ที่ใช้ ที่สำคัญกว่านั้นคือแต่ละ Model อาจเลือกหรือโหลดไฟล์ไม่เหมือนกัน ดังนั้นไฟล์หลักควรอธิบายว่า Reference แต่ละไฟล์เกี่ยวข้องกับอะไร และควรถูกเปิดเมื่อไร

ตัวอย่าง SKILL.md แบบ Generic

---
name: api-change-review
description: Review API changes for contract compatibility,
  security boundaries, and required validation. Use when an
  endpoint, request schema, response schema, authentication,
  or permission behavior changes.
---

# API Change Review

## Goal

สร้าง Review report ที่ระบุ Breaking changes ของ Contract,
การเปลี่ยนแปลงที่เกี่ยวกับ Security, Validation ที่ขาด
และสมมติฐานที่ต้องให้มนุษย์ตรวจสอบ

## Scope

Review การเปลี่ยนแปลงที่เสนอและ Test ที่เกี่ยวข้อง
ห้ามแก้ Implementation files เว้นแต่ผู้ใช้สั่งให้แก้

## Workflow

1. อ่านไฟล์ที่เปลี่ยนและ API contract
2. ระบุการเปลี่ยน Endpoint, Field, Status code และ Behavior
3. ถ้าแตะ Authentication, Secret หรือ Permission
   ให้อ่าน Security rules
4. เปรียบเทียบ Test กับ Behavior ที่เปลี่ยน
5. สร้าง Report ตามรูปแบบที่กำหนด
6. รัน Validation command เมื่อ Environment รองรับ

## Reference routing

- อ่าน `references/api-contract.md` เมื่อ Endpoint หรือ Schema เปลี่ยน
- อ่าน `references/security-rules.md` เมื่อแตะ Authentication,
  Secret หรือ Permission
- อ่าน `references/output-examples.md` เฉพาะเมื่อรูปแบบ Report ไม่ชัด
- อ่าน `references/troubleshooting.md` เมื่อ Validation ไม่ผ่าน

## Constraints

- ห้ามแต่ง Endpoint, Field, Metric หรือ Test result
- ห้ามเปิด Credential, Customer data หรือ Internal URL
- ห้ามนำ Requirement ที่ยังไม่ Implement ไปเขียนเหมือน Released แล้ว
- ระบุสมมติฐานที่ต้องให้มนุษย์ตรวจสอบ

## Required output

1. Summary
2. Contract-breaking changes
3. Security-sensitive changes
4. Missing or affected tests
5. Assumptions requiring review
6. Validation performed

## Completion criteria

- Behavior ที่เปลี่ยนทุกจุดถูกเชื่อมกับ Contract
- ระบุการเปลี่ยนแปลงที่เกี่ยวกับ Security อย่างชัดเจน
- บอกว่า Validation ใดถูกรันและไม่ได้รัน
- สมมติฐานที่ยังไม่จบถูกแสดงให้เห็น

ตัวอย่างนี้ตั้งใจให้เป็น Generic ครับ มันแสดง Instruction contract ไม่ได้อ้างว่า Syntax นี้เป็นข้อบังคับของ Agent Platform ทุกตัว

Before และ After

Before

Review API นี้ และตรวจให้แน่ใจว่าทำตาม Best Practice

After

Review การเปลี่ยนแปลง API โดยใช้ api-change-review skill

ใช้ `references/api-contract.md` เป็น Contract source
ถ้าการเปลี่ยนแปลงแตะ Authentication, Secret หรือ Permission
ให้ใช้ `references/security-rules.md` เพิ่มด้วย

สร้าง Review report ตามรูปแบบที่กำหนด ห้ามแก้ Implementation files
ระบุ Validation command ที่รัน และแสดงสมมติฐานที่ยังต้องตรวจสอบ

คำสั่งที่สองไม่ได้ดีกว่าเพราะยาวกว่า แต่ดีกว่าเพราะปล่อยให้ Agent ต้องตัดสินใจเองน้อยลง และกำหนด scope ในการตัดสินใจให้ชัดเจนยิ่งขึ้น

เปลี่ยน Index ให้เป็น Routing table

รายชื่อไฟล์บอก Agent ว่า “มีอะไรอยู่บ้าง” ส่วน Routing table บอกว่า “ไฟล์ไหนเกี่ยวข้องเมื่อไร”

Reference	เปิดเมื่อ	ไม่ต้องเปิดเมื่อ
api-contract.md	Endpoint, Schema, Status code หรือ Behavior เปลี่ยน	งานไม่เกี่ยวกับ API contract
security-rules.md	แตะ Authentication, Secret, Role หรือ Permission	ไม่มี Behavior ที่เกี่ยวกับ Security
output-examples.md	รูปแบบ Report ที่ต้องการยังไม่ชัด	Output contract ชัดอยู่แล้ว
troubleshooting.md	Validation รันไม่ได้หรือไม่ผ่าน	Validation สำเร็จตามปกติ

ตารางนี้เป็นแนวทางตัดสินใจ ไม่ใช่กลไกบังคับ พฤติกรรมการเลือก Reference จริงยังขึ้นอยู่กับแต่ละ Model, runtime, วิธีจัด Context และเครื่องมือที่ใช้

ควรใช้ไฟล์เดียวหรือแยกหลายไฟล์

เก็บ Skill ไว้ในไฟล์เดียวเมื่อ

• มี Workflow เดียวและไม่ยาว
• Constraints ทั้งหมดยังไม่กลบขั้นตอนหลัก
• ตัวอย่างมีขนาดเล็ก
• ไม่มี Script ที่ต้องใช้ซ้ำ

แยกเป็นหลายไฟล์เมื่อ

• Reference ยาวหรือเฉพาะทาง
• หลาย Workflow ใช้กติกาชุดเดียวกัน
• ตัวอย่างทำให้ไฟล์หลักอ่านยาก
• Validation scripts ถูกใช้ซ้ำ
• กฎที่มีความอ่อนไหวต้องแยกผู้รับผิดชอบหรือกระบวนการ Review

ไฟล์หลักควรตอบได้อย่างน้อยสองคำถาม: Agent ต้องทำอะไร และต้องไปอ่านรายละเอียดต่อจากที่ไหน

Skill ต้องถูกตรวจเหมือน Software

Skill อาจมีคำสั่ง Reference และ Executable code ก่อนใช้ Skill จากภายนอกควรตรวจให้ชัด โดยเฉพาะเมื่อมันสามารถอ่านไฟล์ เรียก Network หรือรัน Script ได้

สิ่งที่ควรตรวจ ได้แก่

• การอ่านไฟล์นอกขอบเขตที่ควรเข้าถึง
• ปลายทางของ Network และ API
• Credential ที่ถูกเขียนฝังไว้
• คำสั่งแก้ไขหรือลบไฟล์
• คำสั่งแฝงที่พยายามข้ามกฎของระบบ
• Script ที่ยังไม่ผ่านการ Review

สำหรับการใช้ในองค์กร อาจต้องเพิ่ม Sandbox และ Coexistence test ด้วย เพราะแต่ละ Model อาจตอบสนองต่อคำสั่งหรือชุดเครื่องมือเดียวกันแตกต่างกัน

Validation checklist

- [ ] Description ระบุว่า Skill ควรถูกใช้เมื่อไร
- [ ] Goal และ Scope ชัดเจน
- [ ] Workflow เป็นขั้นตอนที่สังเกตและตรวจสอบได้
- [ ] Reference ทุกไฟล์มีเงื่อนไขในการเปิดใช้
- [ ] ระบุสิ่งที่ห้ามทำและห้าม Claim
- [ ] มีกติกาสำหรับข้อมูลที่ไม่ครบ
- [ ] Output contract นำกลับมาใช้และตรวจสอบได้
- [ ] Completion criteria ตรวจได้จริง
- [ ] ไม่มี Secret หรือ Internal URL ฝังอยู่
- [ ] Executable scripts ผ่านการ Review
- [ ] ทดสอบกับงานที่ควร Trigger Skill
- [ ] ทดสอบกับงานที่ไม่ควร Trigger Skill

สรุป

ก่อนส่ง Skill ให้ Agent ลองอ่านในมุมของ Developer ที่เพิ่งเข้าร่วม Project วันนี้ แล้วถามว่า

ข้อมูลเท่านี้ทำงานต่อได้ไหม? ยังต้องเดาอะไรอีก? ถ้าต้องตัดสินใจ รู้หรือยังว่าควรไปในทิศทางไหน?

Skill ที่ดีไม่ได้กำจัดการคิด แต่มันกำจัดการเดาที่ไม่จำเป็นครับ

---