skill0-writer
เอกสาร skill0 ใช้ หลักการพีระมิด: agent อาจอ่านแค่ 10–30 บรรทัดแรกเท่านั้น ข้อมูลสำคัญที่สุดจึงต้องมาก่อน รายละเอียดหลังบรรทัดที่ 30 เป็นของแถม ไม่ใช่ภาระที่ต้องแบกรับ
สิ่งที่ไม่มีกฎใดจับได้
- ชัดเจนสำคัญกว่าสั้น เอกสารสั้นที่ตอบผิดแย่กว่าเอกสารยาวที่ตอบถูก
- คำเตือนด้านความปลอดภัย/ความเสี่ยง ต้องเขียนให้ชัดเจน — ใช้ MUST, NEVER, DO NOT เขียนข้อควรระวังเป็นประโยคเต็ม ไม่ใช่วงในวงเล็บ
- อย่าอธิบายสิ่งที่เป็นความรู้สามัญเกินจำเป็น ถ้าคำที่บอกข้อตกลงแล้วบวกประโยคหนึ่งสองประโยคก็สื่อครบแล้ว ให้หยุด ผู้อ่านรู้อยู่แล้วว่า YAML, git และ cache คืออะไร ใช้บริบทกับสิ่งที่เฉพาะเจาะจง repo นี้แทน เหตุผลของกฎมักเป็นตัวกระทำผิดที่พบบ่อยที่สุด — ให้เหตุผลของกฎเฉพาะเมื่อมันดูผิดไปหากไม่มีเหตุผล (
sw-1200) - ใช้ตารางเฉพาะเมื่อเป็นเมทริกซ์จริง ต้องมี 3 คอลัมน์ขึ้นไปและแต่ละแถวต้องอ่านเทียบกัน ตารางสองคอลัมน์คือรายการที่สวมไว้ด้วยไวยากรณ์ตาราง — เขียนเป็นรายการแทน ชุดข้อมูลควรอยู่ในไฟล์
.tsvภายนอกข้าง ๆ เอกสาร แล้วลิงก์เข้ามา เพื่อให้x tsvค้นหาได้ (sw-1250)
YFM — เฉพาะ SKILL.md
---
name: <slug> # ต้องเหมือนชื่อไดเรกทอรี
description: <สรุป 1-2 ประโยคที่ agent ใช้ตัดสินว่าจะโหลดหรือไม่>
---
name และ description คือส่วนที่สำคัญ ส่วนที่เหลือซ้อนอยู่ในบล็อก metadata: ตามข้อตกลงของ yfm เป็นสเกลาร์คั่นด้วยจุลภาค — ไม่บังคับ และเพิ่มโครงสร้างสำหรับการทำดัชนี การค้นพบ และจุดเชื่อมต่อ ontology
ไฟล์ย่อยไม่ต้องมี YFM เฉพาะ SKILL.md เท่านั้นที่ loader กรอง ดังนั้นเฉพาะไฟล์นี้ที่ต้องมี front matter ไฟล์อื่นทุกไฟล์ (references/*, usecase/*, EXAMPLE.md, *.report.md …) ถูกอ่านโดยตรงจาก agent ที่ตัดสินใจเปิดมันแล้ว — YFM ในไฟล์เหล่านั้นเป็นต้นทุนโทเคนล้วน ๆ ที่บอกวัตถุประสงค์ซ้ำกับสิ่งที่ชื่อเรื่องและบรรทัดแรกบอกอยู่แล้ว ให้ไฟล์เหล่านั้นเริ่มที่หัวข้อ # การฝ่าฝืนต้องระบุเหตุผลไว้ในตัวไฟล์
สำหรับเวอร์ชันภาษาจีน ให้ใช้ SKILL.cn.md คู่ขนานกัน (หนึ่งไฟล์ต่อหนึ่งสกิล) ห้ามผสมภาษาในไฟล์เดียวกัน
การตรวจสอบเชิงกล
อยู่ใน skill0-writer.rule.yml รัน x rule lint skill0-writer.rule.yml และ x rule check -r skill0-writer.rule.yml lib/skill0/ ความครอบคลุม: การมี YFM + ฟิลด์ name/description รูปแบบของ name จำนวนบรรทัด ≤ 100 (เหมาะสมคือ 50) ลำดับหัวข้อ install → usage → advanced → links ภาษาอังกฤษเท่านั้น ไม่มีคำแนะนำนำ/ไม่มีบทสรุป/ไม่มีการซ้ำซาก ไม่มีไฟล์กำพร้า
การตรวจสอบความปลอดภัยจากการตัดบรรทัด
หลังเขียนเสร็จ ให้ทบทวนที่บรรทัดที่ 30: agent ที่หยุดอ่านตรงนี้จะเข้าใจผิดหรือไม่?
ถ้าผิด ให้ย้ายข้อกำกัดที่สำคัญขึ้นมาก่อน 30 บรรทัดต้องให้แบบจำลองทางจิตที่ถูกต้อง (แม้ไม่ครบถ้วน) หลังบรรทัดที่ 30 ค่อยขยายด้วยรายละเอียด — พีระมิดแก้ตัวเองได้
การโหลดสองชั้น: description สำหรับจับคู่ เนื้อหาสำหรับอ้างอิง
ตัวโหลดสกิล (Claude Code, Cursor, Continue ฯลฯ) โหลด SKILL.md เป็นสองจังหวะ:
description:ใน YFM — โหลดเข้าแคตตาล็อกของ agent โดยอัตโนมัติ เพื่อการจับคู่ agent อ่านคำอธิบายเพื่อตัดสินว่าจะโหลด สกิลหรือไม่- เนื้อหา — โหลดตามต้องการหลังจับคู่ได้ เป็นสาระอ้างอิง
ผลที่ตามมา:
- description = คืออะไร + เมื่อไรควรโหลด — ใส่คำสำคัญเต็ม เป็นตัวกระตุ้น กระชับ
- เนื้อหา = ใช้อย่างไร + สาระอ้างอิง — ตัวอย่าง schema กรณีเฉพาะ ลิงก์ไปยังเอกสารลึก
ห้ามทำซ้ำเนื้อหาข้ามสองชั้น สิ่งที่ description สื่อ เนื้อหาควร ขยายความ ไม่ใช่พูดซ้ำในระดับผิวเดียวกัน โดยเฉพาะย่อหน้าแรกของเนื้อหาต้องไม่ลงรายการฟีเจอร์ชุดเดียวกับ description — เนื้อหานำด้วยสาระอ้างอิง ไม่ใช่สรุปซ้ำอีกครั้ง
การทดสอบในทางปฏิบัติ: ถ้าลบ description ทิ้งทั้งหมดแล้วอ่านเฉพาะ 30 บรรทัดแรกของเนื้อหา agent ก็ยังควรเห็นว่าสกิลนี้ทำอะไรและควรโหลดเมื่อไร ถ้าข้อมูลนั้นมีอยู่แค่ใน description เนื้อหาก็ไม่มีอะไรมาเพิ่มไว้ด้านบน — ให้ย้ายคำอธิบายเข้าเนื้อหาและปล่อยให้ description ถือพาดหัว
สกิลคือชุดความรู้ ไม่ใช่บทเรียน
เนื้อหาของสกิลคือ การบรรยายสภาพให้ LLM ไม่ใช่หลักสูตรสำหรับมือใหม่
- ความสามารถ อยู่ที่ LLM เนื้อหาไม่สอน
- ความรู้ อยู่ที่เครื่องมือข้อมูลของ x-cmd (
x wkp/x rfc/x cve, NVD / MITRE / GHSA) และแหล่งภายนอก เนื้อหาทำหน้าที่ชี้ แล้วให้ agent ดึงข้อมูลใหม่เอง - การตีกรอบ คือหน้าที่ของสกิล: ระบุรูปร่างของปัญหา ข้อตกลง รูปแบบผลลัพธ์ที่มีโครงสร้าง และเครื่องมือ x-cmd ที่จะใช้
สกิลพาและมุมการแก้ปัญหา ข้อตกลง รูปแบบผลลัพธ์ และตัวชี้ไปยังแหล่งที่มา สกิลไม่ควรพา ความสามารถ (LLLM มีอยู่แล้ว) ข้อมูลคงที่ (จะเก่า) หรือ บทเรียน (ให้ใช้ไฟล์แนบแยก)
เมื่อรายละเอียดละเอียดเกินไปหรือเปลี่ยนเร็วเกินไป ให้ย้ายไปไฟล์แนบแยก (references/, ANALYTICS.md) หรือเอกสารภายนอกที่อัปเดตเสมอ
ลิงก์ภายนอก
รวบรวมสองประเภท: ลิงก์ราก (จุดเข้า เช่น llms.txt, ดัชนีเอกสาร) และ ลิงก์ที่มีประโยชน์ (ลิงก์เจาะจงสำหรับ 20% ของเอกสารที่ครอบคลุม 80% ของกรณีใช้งาน) เรียงลิงก์รากก่อน แล้วค่อยลิงก์ที่มีประโยชน์ — AI เข้าใจลำดับ ห้ามทำซ้ำ เว้นแต่จุดที่ต้องเน้นเป็นพิเศษ
ข้อควรระวังแบบอ่อน (เรื่องที่ต้องตัดสินใจเอง)
- ไฟล์ย่อย (CLEANUP.md, references/*) ยาวได้มากกว่า SKILL.md แต่ 20 บรรทัดแรกก็ยังต้องแบกของหลักได้ (พีระมิดเหมือนกัน)
- ต้อง ลิงก์ไปยังไฟล์ย่อยทุกไฟล์จาก SKILL.md แม่ของมัน (ต้องมี forward link) การลิงก์ย้อนกลับจากไฟล์ย่อยไปยัง SKILL.md เป็น ไม่บังคับ — ไฟล์ usecase อ้างอิงแม่โดยอ้อมทางเส้นทางอยู่แล้ว บังคับใช้โดย
sw-1000-no-orphan-docsใน skill0-writer.rule.yml - การคาดเดา — ถ้าบอกข้อเท็จจริงที่ทดสอบแล้ว ให้บอกได้ ถ้าไม่ ให้ติดป้ายว่า "ยังไม่ได้ทดสอบ"
- อีโมจิ เว้นแต่หัวข้อของสกิลจำเป็นต้องใช้