Skills ของ Codex: วิธีทำให้ Agent เขียนโค้ดตามมาตรฐานทีมทุกครั้ง

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

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

ไฟล์ Skill ของ Codex เก็บไว้ที่ไหน และหน้าตาฟอร์แมตเป็นแบบไหน

Skill ของ Codex ไม่ใช่การตั้งค่าในเมนูหรือคำสั่งลับที่พิมพ์ในแชท แต่เป็นไฟล์ธรรมดาที่วางอยู่ในระบบไฟล์จริง ระดับโปรเจกต์จะอยู่ในโฟลเดอร์ .codex/skills/ ที่รากของ repository โดยแต่ละ Skill แยกเป็นคนละโฟลเดอร์ย่อย ชื่อโฟลเดอร์คือชื่อของ Skill นั้น แล้วข้างในมีไฟล์หลักชื่อ SKILL.md เป็นตัวกำหนดพฤติกรรม

ตัวไฟล์ SKILL.md แบ่งเป็นสองส่วนชัดเจน ส่วนบนสุดคือ frontmatter รูปแบบ YAML คั่นด้วย --- สองบรรทัด เก็บ field สำคัญอย่างน้อยสองตัวคือ name (ชื่อ Skill สั้น ๆ ไม่มีเว้นวรรค) และ description (คำอธิบายว่า Skill นี้ใช้ตอนไหน) ส่วนที่เหลือถัดจาก frontmatter คือเนื้อหา Markdown ปกติ เขียนขั้นตอนหรือกฎที่ต้องการให้ทำตามได้อย่างอิสระ

field ที่มักถูกมองข้ามคือ description เพราะหลายคนคิดว่าเป็นแค่คำอธิบายให้คนอ่าน แต่จริง ๆ แล้ว field นี้คือสิ่งที่ Codex ใช้ตัดสินใจว่าจะเรียก Skill นี้เข้ามาในงานไหนบ้าง ถ้าเขียนกว้างเกินไปหรือคลุมเครือ Codex อาจไม่เรียกใช้เลยแม้เนื้อหาข้างในจะดีแค่ไหนก็ตาม

ตอนรันงานจริง Codex ตัดสินใจเรียก Skill ไหนมาใช้ยังไง

เมื่อเริ่ม session ใหม่ Codex จะสแกนโฟลเดอร์ .codex/skills/ ทั้งหมดก่อน แล้วอ่านเฉพาะ frontmatter ของทุก Skill ที่เจอ ไม่ได้โหลดเนื้อหาเต็มทุกไฟล์เข้า context ตั้งแต่แรก เพราะถ้าทำแบบนั้นเมื่อมี Skill สะสมหลายสิบไฟล์จะกินพื้นที่ context โดยไม่จำเป็น

เมื่อได้รับคำสั่งงานจากผู้ใช้ Codex จะเทียบคำสั่งนั้นกับ field description ของแต่ละ Skill เพื่อประเมินว่า Skill ไหนเกี่ยวข้องกับงานที่กำลังทำ ถ้าเข้าเงื่อนไข เนื้อหาเต็มของ Skill นั้นถึงจะถูกดึงเข้ามาอ่านจริง ๆ กลไกนี้ต่างจากไฟล์คำแนะนำแบบ AGENTS.md ที่ถูกอ่านเข้า context ทันทีตั้งแต่เริ่ม session โดยไม่ต้องผ่านการเทียบเงื่อนไขใด ๆ

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

ขอบเขตระดับโปรเจกต์กับระดับเครื่อง ต่างกันตรงไหน และใช้ร่วมกันยังไง

Skill ของ Codex แบ่งขอบเขตได้สองระดับ ระดับโปรเจกต์เก็บไว้ที่ .codex/skills/ ในรากของ repository นั้น ๆ ใช้ได้เฉพาะกับคนที่เปิดโปรเจกต์นี้ ส่วนระดับเครื่อง (global) เก็บไว้ที่ ~/.codex/skills/ ในโฮมไดเรกทอรีของผู้ใช้ ใช้ได้กับทุกโปรเจกต์ที่เปิดจากเครื่องนั้น ไม่ว่าจะเป็น repository ไหนก็ตาม

ความต่างนี้สำคัญเวลาตัดสินใจว่าควรวาง Skill ไว้ที่ไหน กฎที่เป็นมาตรฐานเฉพาะของ repository เช่นรูปแบบการตั้งชื่อ endpoint หรือ pattern การจัดการ error ของโปรเจกต์นั้น ควรอยู่ในระดับโปรเจกต์เพื่อให้ commit ไปพร้อมกับโค้ดและทุกคนในทีมที่ clone repository ได้ใช้ชุดเดียวกัน ส่วนนิสัยการทำงานส่วนตัว เช่นรูปแบบการเขียนคำอธิบาย commit ที่ผู้ใช้คนหนึ่งชอบใช้ในทุกโปรเจกต์ เหมาะกับระดับเครื่องมากกว่า

ถ้ามี Skill ชื่อเดียวกันอยู่ทั้งสองระดับ Skill ระดับโปรเจกต์จะถูกใช้ก่อนเสมอ เพราะถือว่าเจาะจงกับบริบทของงานตรงหน้ามากกว่า ทีมที่พบพฤติกรรมแปลก ๆ เช่น Skill ที่ตั้งใจเขียนไว้เฉพาะโปรเจกต์กลับถูกแทนที่ด้วยกฎอื่น ควรตรวจก่อนว่ามี Skill ชื่อซ้ำกันอยู่ในระดับเครื่องหรือไม่

ตัวอย่างจริง เขียน Skill ควบคุมมาตรฐานการเขียน API endpoint ใหม่

สมมติทีมมีโปรเจกต์ backend เขียนด้วย Express อยู่ที่ /repo และต้องการให้ Codex เขียน endpoint ใหม่ทุกตัวตาม pattern เดียวกันเสมอ ขั้นแรกคือสร้างโฟลเดอร์ .codex/skills/new-api-endpoint/ แล้วสร้างไฟล์ /repo/.codex/skills/new-api-endpoint/SKILL.md ข้างใน

เนื้อหาไฟล์เริ่มด้วย frontmatter ดังนี้ name: new-api-endpoint ตามด้วย description: ใช้เมื่อสร้าง REST endpoint ใหม่ในโปรเจกต์นี้ ต้องมี validation, error handling แบบมาตรฐานทีม และไฟล์ test คู่กันเสมอ ปิดท้ายด้วย --- แล้วตามด้วยเนื้อหา Markdown ที่ระบุ pattern ละเอียด เช่นต้อง validate input ด้วย zod ก่อนเข้า business logic เสมอ, error ต้อง throw เป็น AppError พร้อม status code ไม่ใช่ throw string ตรง ๆ, และทุก endpoint ต้องมีไฟล์ test คู่กันในโฟลเดอร์ __tests__ ชื่อไฟล์เดียวกับ route

เมื่อวางไฟล์นี้ไว้แล้ว ครั้งถัดไปที่มีคนสั่ง Codex ว่า 'ช่วยเพิ่ม endpoint สำหรับลบสินค้าออกจากตะกร้า' คำว่าเพิ่ม endpoint ในคำสั่งจะเทียบตรงกับคำใน description ของ Skill นี้ Codex จะดึงเนื้อหาเต็มเข้ามาอ่าน แล้วเขียนโค้ดตาม pattern ที่ระบุไว้ทันที โดยไม่ต้องมีใครพิมพ์อธิบายกฎ validation หรือ error handling ซ้ำอีกในคำสั่งนั้น

องค์ประกอบของ Skill ที่ถูกเรียกใช้จริง เทียบกับ Skill ที่เขียนไว้เฉย ๆ

ไม่ใช่ Skill ทุกแบบจะถูก Codex เรียกใช้จริงแม้จะวางไฟล์ถูกตำแหน่งแล้ว บางแบบเขียน description กว้างเกินจนไม่ต่างจากไม่มี Skill เลย ตารางนี้เทียบให้เห็นความต่าง:

Skill เขียนไว้ครบแล้ว แต่ Codex ไม่เคยเรียกใช้เลย ไล่ปัญหายังไง

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

1. ตรวจตำแหน่งไฟล์ก่อนว่าอยู่ที่ .codex/skills/<ชื่อ>/SKILL.md จริงหรือไม่ ไม่ใช่วางไว้ในโฟลเดอร์อื่นที่คล้ายกัน เช่น .codex/SKILL.md เฉย ๆ โดยไม่มีโฟลเดอร์ย่อยครอบ
2. ตรวจ frontmatter ว่าคั่นด้วย --- ครบทั้งสองบรรทัดจริง ถ้าลืมบรรทัดปิดท้าย Codex จะอ่านทั้งไฟล์เป็นเนื้อหาธรรมดาแทนที่จะแยก field ออกมา ทำให้ name และ description ไม่ถูกอ่านเป็น field เลย
3. อ่าน field description ของตัวเองใหม่อีกครั้งในมุมคนสั่งงานจริง ไม่ใช่มุมคนเขียน Skill ถ้าเขียนกว้างเกินไปแทบไม่ต่างจากไม่มีเงื่อนไขเลย ควรระบุคำที่คนน่าจะพิมพ์สั่งงานจริง เช่นคำว่า endpoint หรือ route ให้ตรงกับที่ทีมมักใช้
4. ทดสอบด้วยการสั่งงานที่ใช้คำในคำอธิบายตรง ๆ ก่อน ถ้าเรียกติดตอนใช้คำตรง แต่ไม่ติดตอนใช้คำอื่นที่ความหมายเดียวกัน แปลว่าปัญหาอยู่ที่ความกว้างของ description ไม่ใช่ตำแหน่งไฟล์
5. ถ้ามี Skill ชื่อซ้ำกันทั้งระดับโปรเจกต์และระดับเครื่อง ให้ตรวจว่าตัวที่ใช้งานจริงเป็นตัวที่คาดหวังหรือไม่ เพราะระดับโปรเจกต์จะทับระดับเครื่องเสมอ

ทำแบบนี้แล้วพัง เพราะชื่อ Skill ชนกันระหว่างเครื่องส่วนตัวกับโปรเจกต์ลูกค้า

ทีมหนึ่งเขียน Skill ชื่อ code-style ไว้ที่ระดับเครื่อง (~/.codex/skills/code-style/) เพราะต้องการให้ทุกโปรเจกต์ที่ตัวเองเปิดใช้กฎการจัดรูปแบบโค้ดแบบเดียวกันหมด แล้ววันหนึ่งไปทำงานในโปรเจกต์ของลูกค้าอีกรายที่มี .codex/skills/code-style/ ของตัวเองอยู่แล้วในระดับโปรเจกต์ ซึ่งเขียนกฎขัดกับของตัวเองโดยสิ้นเชิง

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

บทเรียนจากกรณีนี้คือควรตั้งชื่อ Skill ระดับเครื่องให้เฉพาะเจาะจงกับตัวเองจริง ๆ ไม่ใช่ใช้ชื่อทั่วไปที่คนอื่นน่าจะตั้งชื่อซ้ำได้ง่าย และก่อนเริ่มงานในโปรเจกต์ใหม่ควรเช็คโฟลเดอร์ .codex/skills/ ของโปรเจกต์นั้นก่อนว่ามีชื่อชนกับที่ตัวเองมีอยู่แล้วหรือไม่

ทำให้ทั้งทีมใช้ Skill ชุดเดียวกันจริง ไม่ใช่แค่เก็บไว้ในเครื่องคนเขียน

Skill จะมีประโยชน์เต็มที่ก็ต่อเมื่อไฟล์ .codex/skills/ ถูก commit เข้า repository จริง ไม่ใช่เก็บไว้ในเครื่องคนใดคนหนึ่งเฉย ๆ เพราะถ้าไม่ commit คนอื่นที่ clone repository ไปจะไม่มี Skill ชุดนี้เลย ทำให้ Agent ของแต่ละคนทำงานไม่ตรงกันเหมือนเดิม ทั้งที่ตั้งใจแก้ปัญหานี้อยู่แล้ว

แนวคิดเรื่องมาตรฐานทีมแบบนี้คล้ายกับที่อธิบายไว้ใน Skills ของ Claude Code แม้กลไกไฟล์และการเรียกใช้จะต่างกันในรายละเอียด แต่เป้าหมายเดียวกันคือให้ Agent ทำตามกฎทีมโดยไม่ต้องพิมพ์ซ้ำ ทีมที่ยังไม่แน่ใจว่า Codex เหมาะกับงานแบบไหนควรอ่าน OpenAI Codex คืออะไร เป็นพื้นฐานก่อน

ทีมที่ใช้ทั้ง Codex และ Claude Code สลับกันในโปรเจกต์เดียว ควรอ่านความต่างของกลไก Skill ทั้งสองฝั่งเพิ่มเติมใน Codex กับ Claude Code เพราะไฟล์ .codex/skills/ กับโฟลเดอร์ Skill ของ Claude Code ไม่ใช่ไฟล์เดียวกันและไม่ถูกอ่านข้ามระบบกัน ต้องเขียนแยกกันสำหรับแต่ละเครื่องมือ

สำหรับทีมที่ต้องการบังคับขั้นตอนก่อนงานจะถือว่าเสร็จจริง เช่นรัน lint หรือ test อัตโนมัติ สามารถใช้แนวทางคล้ายกับ Hooks ร่วมกับ Skill ได้ โดย Skill กำหนดว่าเขียนโค้ดแบบไหน ส่วนขั้นตอนบังคับก่อนส่งงานเป็นอีกชั้นที่แยกออกจากกัน

สรุป

กลไก Skill ของ Codex อยู่ที่รายละเอียดเชิงเทคนิคมากกว่าที่หลายคนคิด ตำแหน่งไฟล์ ฟอร์แมต frontmatter และความชัดเจนของ description ล้วนส่งผลโดยตรงต่อว่า Skill นั้นจะถูกเรียกใช้จริงหรือถูกมองข้ามไปเงียบ ๆ โดยไม่มีข้อความ error ใด ๆ บอกเลย

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

• Skill เก็บเป็นไฟล์ SKILL.md จริงในระบบไฟล์ ที่ .codex/skills/<ชื่อ>/ ระดับโปรเจกต์ หรือ ~/.codex/skills/<ชื่อ>/ ระดับเครื่อง
• Codex เทียบคำสั่งงานกับ field description ใน frontmatter ก่อนตัดสินใจดึงเนื้อหาเต็มของ Skill เข้ามาใช้
• Skill ระดับโปรเจกต์ทับ Skill ระดับเครื่องเสมอเมื่อชื่อซ้ำกัน เป็นสาเหตุที่พบบ่อยของ Skill ที่ดูเหมือนหายไปเฉย ๆ
• เมื่อ Skill ไม่ถูกเรียกใช้ ให้ไล่ตรวจตำแหน่งไฟล์ ฟอร์แมต frontmatter และความชัดเจนของ description ตามลำดับก่อนสรุปว่าใช้งานไม่ได้

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