SKILL.md: เขียนอย่างไรให้ Agent ทำงานซ้ำได้แม่นทุกครั้ง ไม่ใช่แค่ครั้งแรก

มีทีมพัฒนาทีมหนึ่งเริ่มใช้ Coding Agent ช่วยเขียนโค้ดในโปรเจกต์เดียวกันหลายคนพร้อมกัน ปัญหาที่เจอซ้ำ ๆ คือ Agent แต่ละรอบเขียนโค้ดตามสไตล์ไม่เหมือนกัน บางครั้งใช้ชื่อไฟล์ตามแบบเดิมของโปรเจกต์ บางครั้งตั้งชื่อใหม่ตามที่มันคิดว่าดี ทั้งที่ทีมเคยพิมพ์อธิบาย convention ของโปรเจกต์ไว้ในแชทตั้งแต่ต้นสัปดาห์แล้ว

ต้นตอของปัญหานี้ไม่ใช่ Agent จำไม่ได้ในความหมายที่คนเข้าใจ แต่เป็นเพราะข้อมูลที่พิมพ์ไว้ในแชทหายไปพร้อมกับ context ที่หมดอายุหรือถูกตัดทิ้งเมื่อบทสนทนายาวเกินไป ทุกครั้งที่เริ่ม session ใหม่ Agent จึงเริ่มจากศูนย์โดยไม่มีความรู้เรื่อง convention เดิมเหลืออยู่เลย นอกจากจะมีใครพิมพ์อธิบายซ้ำอีกครั้ง

SKILL.md คือทางแก้ที่หลายทีม coding agent เริ่มใช้กันจริงจัง เพราะเปลี่ยนความรู้ที่เคยพิมพ์ทิ้งไว้ในแชทให้กลายเป็นไฟล์ถาวรที่อยู่ในระบบควบคุมเวอร์ชันเดียวกับโค้ด บทความนี้จะพาดูโครงสร้างไฟล์ที่ใช้ได้จริง วิธีเขียนส่วน frontmatter และเนื้อหาให้ Agent ทำตามได้เสถียร พร้อมข้อผิดพลาดที่เจอบ่อยตอนเริ่มเขียน

SKILL.md คืออะไร ต่างจาก README ของโปรเจกต์ตรงไหน

SKILL.md คือไฟล์ข้อความรูปแบบ Markdown ที่บรรจุความรู้เฉพาะเรื่องหนึ่งไว้ให้ Agent เรียกใช้เมื่อเจอสถานการณ์ที่ตรงเงื่อนไข ต่างจาก README ที่มีจุดประสงค์หลักคืออธิบายโปรเจกต์ให้คนอ่านเข้าใจภาพรวมตั้งแต่เริ่มต้น README มักเขียนกว้าง ๆ ครอบคลุมทุกอย่างในไฟล์เดียว ในขณะที่ SKILL.md แต่ละไฟล์ควรโฟกัสเฉพาะเรื่องเดียวที่แคบและชัดเจน เช่น ขั้นตอนเขียน test สำหรับโมดูลหนึ่ง หรือ convention การตั้งชื่อ branch ของทีม

อีกความต่างที่สำคัญคือ README ถูกเขียนให้คนอ่านเป็นหลัก ส่วน SKILL.md ถูกเขียนให้ทั้งคนและ Agent อ่านพร้อมกัน โครงสร้างของมันจึงต้องเจาะจงและมีลำดับขั้นตอนที่ทำตามได้ตรง ๆ มากกว่าการเล่าเรื่องแบบ README ทั่วไป เพราะ Agent ไม่ได้ตีความน้ำเสียงหรือบริบทแวดล้อมได้ดีเท่าคน ถ้าเขียนกำกวมมันจะทำตามแบบที่มันตีความเอง ซึ่งอาจไม่ตรงกับที่ทีมตั้งใจ

ระบบที่รองรับ SKILL.md จะสแกนหาไฟล์เหล่านี้ในโปรเจกต์ แล้วอ่านส่วน frontmatter ด้านบนของแต่ละไฟล์เพื่อประเมินว่าควรโหลดไฟล์ไหนเข้ามาในบริบทของงานที่กำลังทำอยู่ ไม่ใช่โหลดทุกไฟล์พร้อมกันเสมอไป กลไกนี้คล้ายกับการที่ MCP server เลือก tool ที่เกี่ยวข้องมาแสดงให้ Agent เห็น เพียงแต่ SKILL.md ให้ความรู้แทนที่จะให้ความสามารถเชื่อมต่อระบบภายนอก

ส่วน Frontmatter ที่ต้องมี และความหมายของแต่ละ Field

ด้านบนสุดของไฟล์ SKILL.md มักมีส่วน frontmatter คั่นด้วยเครื่องหมาย `---` บนล่าง เก็บข้อมูล metadata ที่ระบบใช้ตัดสินใจว่าจะโหลดไฟล์นี้เมื่อไร field ที่พบบ่อยที่สุดคือ `name` ซึ่งเป็นชื่อสั้น ๆ ไม่ซ้ำกันในโปรเจกต์ และ `description` ซึ่งเป็นประโยคอธิบายว่า Skill นี้ใช้เมื่อไรและครอบคลุมเรื่องอะไร

field `description` สำคัญที่สุดในบรรดา frontmatter ทั้งหมด เพราะเป็นสิ่งเดียวที่ระบบใช้เทียบกับงานที่กำลังทำอยู่ก่อนตัดสินใจโหลดไฟล์เต็มเข้ามา ถ้าเขียนกว้างเกินไปเช่น 'ความรู้เกี่ยวกับโปรเจกต์นี้' ระบบจะไม่รู้ว่าควรโหลดตอนไหน แต่ถ้าเขียนเจาะจงเกินไปจนแคบมากเช่น 'ใช้เฉพาะตอนแก้บั๊ก id 4521 เท่านั้น' ก็จะไม่มีวันถูกโหลดใช้ซ้ำในสถานการณ์อื่นเลย ต้องหาจุดสมดุลที่เจาะจงพอจะจับคู่ได้แม่น แต่กว้างพอจะใช้ซ้ำได้จริง

field เสริมอื่น ๆ ที่พบในหลายระบบได้แก่ `version` สำหรับติดตามการเปลี่ยนแปลงของไฟล์ และบาง field ที่ใช้จำกัดขอบเขตว่า Skill นี้ควรมีผลกับไฟล์หรือโฟลเดอร์ไหนในโปรเจกต์เท่านั้น ไม่จำเป็นต้องใส่ทุก field ที่ระบบรองรับ แต่ควรใส่เฉพาะที่มีความหมายจริงกับ Skill นั้น เพราะ field ที่ใส่ไปโดยไม่มีเนื้อหารองรับจริงจะทำให้ Skill ดูสมบูรณ์กว่าที่เป็นจริงและอาจทำให้คนอื่นในทีมเข้าใจผิด

เขียน Description ให้ระบบเลือกโหลด Skill ถูกจังหวะ

ปัญหาที่พบบ่อยที่สุดของ SKILL.md ที่เขียนไม่ได้ผลคือ description ที่ไม่ได้บอกเงื่อนไขการใช้งานอย่างเจาะจง เขียนแค่ว่า Skill ทำอะไรโดยไม่บอกว่าใช้ 'เมื่อไร' เช่น 'อธิบายวิธีเขียน API endpoint' ซึ่งกว้างเกินจนไม่รู้ว่าจะโหลดตอนไหนในบรรดางานที่เกี่ยวกับ API ทั้งหมด

วิธีเขียนที่ได้ผลดีกว่าคือระบุสถานการณ์ที่ควรโหลด Skill นี้แบบเจาะจง เช่น 'ใช้เมื่อสร้าง REST API endpoint ใหม่ในโฟลเดอร์ api/ ของโปรเจกต์นี้ ครอบคลุมการตั้งชื่อ route, การ validate input และรูปแบบ response ที่ทีมใช้' การระบุทั้งบริบท (โฟลเดอร์ไหน) และขอบเขต (ครอบคลุมเรื่องอะไร) ช่วยให้ระบบจับคู่ได้แม่นกว่ามาก

อีกเทคนิคที่ช่วยได้คือเขียนคำที่คนในทีมมักพิมพ์จริงเวลาต้องการความช่วยเหลือเรื่องนี้ ไว้แทรกใน description เช่นถ้าทีมมักพิมพ์ว่า 'ช่วยเขียน endpoint ให้หน่อย' ก็ควรมีคำว่า endpoint ปรากฏใน description ตรง ๆ เพราะการจับคู่มักอาศัยความใกล้เคียงของคำในเชิงความหมายกับสิ่งที่ผู้ใช้พิมพ์จริง ไม่ใช่แค่คำนิยามเชิงวิชาการ

จัดโครงเนื้อหาในไฟล์ให้ Agent ทำตามได้ทีละขั้น ไม่ใช่อ่านแล้วงง

เนื้อหาส่วนล่างของ SKILL.md ควรจัดเป็นลำดับขั้นตอนที่ชัดเจน ไม่ใช่ย่อหน้ายาวที่อธิบายทุกอย่างปนกัน เพราะ Agent ทำงานได้แม่นกว่าเมื่อเจอโครงสร้างที่แยกขั้นตอนออกจากกันชัด เช่น หัวข้อย่อยว่าต้องตรวจสอบอะไรก่อนเริ่ม ขั้นตอนหลักมีกี่ข้อ และมีข้อควรระวังอะไรระหว่างทำ

การใส่ตัวอย่างโค้ดหรือ template จริงในไฟล์ช่วยได้มากกว่าการอธิบายด้วยคำพูดล้วน ๆ เพราะ Agent มีแนวโน้มทำตามรูปแบบของตัวอย่างที่ให้ไว้ได้แม่นกว่าการตีความคำอธิบายเชิงนามธรรม เช่นถ้า Skill เกี่ยวกับการเขียน test ควรมีตัวอย่างไฟล์ test จริงหนึ่งไฟล์แนบไว้ในเนื้อหา ไม่ใช่แค่บอกว่า 'เขียน test ให้ครอบคลุม'

ควรแยกส่วน 'สิ่งที่ต้องทำเสมอ' ออกจากส่วน 'สิ่งที่ห้ามทำ' ให้ชัดเจน เพราะบางครั้งข้อห้ามสำคัญไม่แพ้ขั้นตอนที่ต้องทำ เช่น ห้ามแก้ไฟล์ migration ที่ merge เข้า main แล้ว หรือห้าม hardcode ค่า config ที่ควรอ่านจาก environment variable การแยกสองส่วนนี้ออกจากกันชัดเจนช่วยลดโอกาสที่ Agent จะข้ามข้อห้ามไปเพราะมันปนอยู่กลางย่อหน้าขั้นตอนปกติ

SKILL.md เทียบกับวิธีเก็บความรู้แบบอื่นที่ทีมเคยใช้

ก่อนมี SKILL.md หลายทีมเก็บความรู้แบบนี้ไว้ในรูปแบบอื่น เช่น comment ยาวในโค้ด เอกสาร wiki แยกต่างหาก หรือพิมพ์ในแชทซ้ำทุกครั้ง ตารางนี้เทียบข้อดีข้อเสียของแต่ละวิธีเมื่อใช้กับ Coding Agent:

ขั้นตอนเขียน SKILL.md ใหม่ ตั้งแต่ศูนย์จนใช้งานได้จริง

การเริ่มเขียน SKILL.md ไฟล์แรกไม่จำเป็นต้องสมบูรณ์แบบตั้งแต่ครั้งเดียว แนวทางที่ใช้ได้ผลจริงคือเริ่มจากปัญหาที่เกิดซ้ำบ่อยที่สุดในทีมก่อน แล้วค่อยขยายไปเรื่องอื่น

1. สังเกตว่างานแบบไหนที่ทีมต้องอธิบาย Agent ซ้ำ ๆ บ่อยที่สุดในสัปดาห์ที่ผ่านมา เลือกเรื่องนั้นมาทำ Skill แรก
2. เขียน description ที่ระบุเงื่อนไขการใช้แบบเจาะจง ทดลองอ่านออกเสียงว่าฟังแล้วรู้ทันทีไหมว่าใช้เมื่อไร
3. จัดเนื้อหาเป็นขั้นตอนที่ทำตามได้ตรง ๆ พร้อมตัวอย่างโค้ดหรือ template อย่างน้อยหนึ่งชิ้นถ้าเกี่ยวข้อง
4. ทดสอบด้วยการขอให้ Agent ทำงานที่ควรตรงกับ Skill นี้ แล้วสังเกตว่ามันโหลด Skill มาใช้จริงหรือไม่ และทำตามขั้นตอนครบไหม
5. ปรับ description หรือเนื้อหาตามผลทดสอบ แล้ว commit ไฟล์เข้าระบบควบคุมเวอร์ชันเดียวกับโค้ดเพื่อให้ทั้งทีมใช้ร่วมกันได้

ดูแล SKILL.md ให้ตรงกับความจริง เมื่อโปรเจกต์เปลี่ยนไปเรื่อย ๆ

ปัญหาระยะยาวของ SKILL.md ที่หลายทีมเจอคือไฟล์เขียนไว้ถูกต้องตอนสร้าง แต่พอโปรเจกต์เปลี่ยน convention หรือ library หลักที่ใช้ ไฟล์เก่ากลับไม่มีใครอัปเดตตาม ทำให้ Agent ทำตามขั้นตอนที่ล้าสมัยไปแล้วโดยไม่มีใครรู้ตัวจนกว่าจะมีคน review โค้ดแล้วสงสัยว่าทำไม Agent ยังเขียนแบบเก่าอยู่

แนวทางที่ช่วยลดปัญหานี้คือผูก SKILL.md เข้ากับกระบวนการ code review เดียวกับโค้ด เมื่อ pull request ไหนเปลี่ยน convention ที่ Skill ไฟล์ใดอ้างอิงอยู่ ผู้ review ควรเช็คด้วยว่าต้องอัปเดต SKILL.md ที่เกี่ยวข้องหรือไม่ เช่นเดียวกับที่ต้องอัปเดต README เมื่อโครงสร้างโปรเจกต์เปลี่ยน

อีกวิธีที่ช่วยได้คือกำหนดให้แต่ละไฟล์มีเจ้าของที่ชัดเจน ไม่จำเป็นต้องเป็นคนคนเดียวตลอดไป แต่ควรมีใครสักคนที่รับผิดชอบตรวจทานเป็นระยะว่าเนื้อหายังตรงกับสถานะจริงของโปรเจกต์อยู่หรือไม่ โดยเฉพาะ Skill ที่เกี่ยวกับเรื่องที่เปลี่ยนบ่อย เช่น dependency version หรือ deployment process

ทำแบบนี้แล้วพัง เพราะ… ข้อผิดพลาดที่เจอบ่อยตอนเขียน SKILL.md

• เขียน description กว้างเกินไปเพื่อให้ครอบคลุมทุกกรณี — ทำแบบนี้แล้วพัง เพราะระบบไม่รู้ว่าควรโหลดตอนไหน เหมือนปัญหาการเขียน description ของ MCP tool ที่กว้างจนโมเดลเลือกผิด
• ยัดความรู้หลายเรื่องไม่เกี่ยวข้องกันไว้ในไฟล์เดียว — ทำแบบนี้แล้วพัง เพราะทุกครั้งที่ไฟล์ถูกโหลด Agent ต้องแบกเนื้อหาที่ไม่เกี่ยวกับงานตรงหน้าเข้ามาด้วย ทำให้สับสนและกินพื้นที่ context โดยไม่จำเป็น
• เขียนเนื้อหาเป็นย่อหน้ายาวไม่มีขั้นตอนชัดเจน — ทำแบบนี้แล้วพัง เพราะ Agent ตีความลำดับความสำคัญเองแล้วอาจข้ามขั้นตอนที่ทีมมองว่าจำเป็น
• ไม่มีใครดูแลไฟล์หลังเขียนเสร็จ ปล่อยให้ล้าสมัยไปเรื่อย ๆ — ทำแบบนี้แล้วพัง เพราะ Agent จะยังทำตามขั้นตอนเก่าที่ไม่ตรงกับของจริงแล้ว โดยไม่มีสัญญาณเตือนใด ๆ
• สร้าง Skill ใหม่ทุกครั้งที่เจอปัญหาโดยไม่เช็คว่ามีไฟล์เดิมที่ใกล้เคียงอยู่แล้ว — ทำแบบนี้แล้วพัง เพราะจำนวนไฟล์ SKILL.md จะเยอะเกินไปจนซ้อนทับเนื้อหากันเอง เหมือนปัญหา MCP tool ที่คาบเกี่ยวขอบเขตกัน

สรุป

SKILL.md แก้ปัญหาความรู้ที่เคยพิมพ์ทิ้งไว้ในแชทแล้วหายไปทุกครั้งที่เริ่ม session ใหม่ ด้วยการเปลี่ยนให้เป็นไฟล์ถาวรที่ Agent เรียกใช้ซ้ำได้ตามเงื่อนไขที่กำหนด หัวใจของการเขียนไฟล์นี้ให้ได้ผลคือ description ที่เจาะจงพอให้ระบบจับคู่ถูก และเนื้อหาที่จัดเป็นขั้นตอนทำตามได้จริง

การดูแล SKILL.md ไม่จบแค่วันที่เขียนเสร็จ ต้องผูกเข้ากับกระบวนการ review และมีเจ้าของดูแลระยะยาว เพราะไฟล์ที่ล้าสมัยจะทำให้ Agent ทำงานผิดจากความจริงของโปรเจกต์โดยไม่มีใครรู้ตัวจนกว่าจะมีปัญหาเกิดขึ้นจริง

• SKILL.md คือไฟล์ความรู้เฉพาะเรื่องที่ Agent เรียกใช้ซ้ำได้ ต่างจาก README ที่เขียนให้คนอ่านภาพรวม
• description ใน frontmatter คือส่วนสำคัญที่สุด ต้องเจาะจงพอให้ระบบจับคู่กับงานได้ถูก
• จัดเนื้อหาเป็นขั้นตอนพร้อมตัวอย่างจริง ไม่ใช่ย่อหน้ายาวที่อธิบายกว้าง ๆ
• ผูกการดูแลไฟล์เข้ากับ code review เพื่อไม่ให้เนื้อหาล้าสมัยตามโปรเจกต์ที่เปลี่ยนไป

คำถามที่พบบ่อย