Claude Code skills: โครงสร้าง SKILL.md และเมื่อไรเอเจนต์โหลดสกิลนั้น

Skills ใน Claude Code คืออะไร

Skill (สกิล) คือโฟลเดอร์ที่มีไฟล์ SKILL.md ซึ่งเขียนคำสั่งสำหรับงานประเภทหนึ่งโดยเฉพาะ เช่น วิธีดีพลอยโปรเจกต์ วิธีรีวิว หรือวิธีปล่อยเวอร์ชัน เอเจนต์รู้ว่ามีสกิลนั้นตั้งแต่ต้นเซสชัน แต่จะอ่านทั้งไฟล์ก็ต่อเมื่องานต้องการเท่านั้น

Claude Code skills แก้ปัญหาที่คนที่ดูแล CLAUDE.md มานานคุ้นเคย นั่นคือไฟล์คำสั่งที่บวมขึ้นเรื่อยๆ ขั้นตอนดีพลอยยาว 80 บรรทัดต้องใช้สัปดาห์ละครั้ง แต่กลับกินพื้นที่ในบริบททุกเซสชัน แม้กระทั่งตอนแก้คำผิดใน README สกิลช่วยนำขั้นตอนแบบนี้ออกจากบริบทถาวร และดึงมาใช้เมื่อจำเป็น

สกิลประกอบด้วยอะไรบ้าง

สกิลขั้นต่ำคือโฟลเดอร์หนึ่งโฟลเดอร์และไฟล์หนึ่งไฟล์ สกิลของโปรเจกต์อยู่ใน repository ส่วนสกิลส่วนตัวอยู่ในโฮมไดเรกทอรีของผู้ใช้:

.claude/skills/deploy/SKILL.md      # สกิลของโปรเจกต์ ใช้ร่วมกันในทีมผ่าน git
~/.claude/skills/review/SKILL.md    # สกิลส่วนตัว ใช้ได้ในทุกโปรเจกต์

ข้างไฟล์ SKILL.md สามารถวางไฟล์เสริมได้ เช่น เทมเพลต สคริปต์ หรือเอกสารอ้างอิง เอเจนต์จะเปิดไฟล์เหล่านี้ก็ต่อเมื่อเนื้อหาหลักอ้างถึงและจำเป็นต้องใช้เท่านั้น

.claude/skills/deploy/
├── SKILL.md           # คำสั่งหลัก
├── checklist.md       # เช็กลิสต์ละเอียด อ่านตามลิงก์
└── rollback.sh        # สคริปต์ย้อนกลับ

Frontmatter: name และ description

ไฟล์เริ่มด้วยบล็อก YAML ที่อยู่ระหว่างบรรทัด --- สองฟิลด์สำคัญที่สุดคือ name ซึ่งเป็นชื่อสั้นของสกิล และ description ซึ่งอธิบายว่าสกิลทำอะไรและควรใช้เมื่อไร

---
name: deploy
description: ดีพลอยเว็บไซต์ขึ้นโฮสติ้งผ่าน FTP ใช้เมื่อต้องอัปโหลดการเปลี่ยนแปลงขึ้นเซิร์ฟเวอร์ ตรวจความต่างกับเซิร์ฟเวอร์ หรือย้อนกลับการดีพลอย
---

# ดีพลอย

1. รันทดลองก่อน: `./deploy.sh -n`
2. ตรวจรายการไฟล์: ต้องไม่มีความลับหรือสคริปต์ทดสอบ
3. อัปโหลด: `./deploy.sh`
4. เปิดหน้าที่เปลี่ยนและตรวจว่าตอบ 200

การย้อนกลับ ดูที่ rollback.sh ในโฟลเดอร์นี้

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

เอเจนต์โหลดสกิลเมื่อไร

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

จากข้อนี้มีหลักปฏิบัติที่สำคัญ: สกิลทำงานตามคำอธิบาย เอเจนต์มองไม่เห็นเนื้อหาของสกิลจนกว่าจะตัดสินใจเปิดมัน ถ้า description เขียนว่า "สกิลเสริม" เอเจนต์จะไม่รู้ว่าเมื่อไรควรใช้ แต่ถ้าเขียนว่า "ดีพลอยขึ้นโฮสติ้ง ใช้เมื่อต้องอัปโหลดการเปลี่ยนแปลงขึ้นเซิร์ฟเวอร์หรือย้อนกลับการดีพลอย" เอเจนต์จะเข้าใจ

นอกจากการเลือกอัตโนมัติ สามารถเรียกสกิลโดยตรงด้วยชื่อผ่านเครื่องหมายสแลช เช่น /deploy ซึ่งสะดวกเมื่อคุณรู้แน่ชัดว่าต้องการขั้นตอนไหน และไม่อยากพึ่งการจับคู่คำขอกับคำอธิบายของเอเจนต์

วิธีเขียน description ให้สกิลถูกเรียกใช้

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

การเปิดเผยแบบทีละชั้น

สกิลสร้างขึ้นบนหลักการ progressive disclosure คือเปิดเผยข้อมูลเป็นชั้นๆ และชั้นถัดไปจะโหลดก็ต่อเมื่อจำเป็น

นี่คือแนวคิดเดียวกับการใช้ router แทนกำแพงข้อความในไฟล์คำสั่ง คือมีแผนที่สั้นๆ ไว้เสมอ และรายละเอียดอยู่หลังลิงก์ ความต่างคือสกิลทำให้การโหลดแบบนี้เป็นกลไกมาตรฐาน ไม่ต้องฝากความหวังว่าเอเจนต์จะเปิดเอกสารที่ถูกต้องเอง ข้อดีเพิ่มเติมคือ สคริปต์ในชั้นที่ 3 เอเจนต์รันได้เลยโดยไม่ต้องโหลดโค้ดทั้งหมดเข้าบริบท

Skills, CLAUDE.md และ slash command ต่างกันอย่างไร

ทั้งสามกลไกส่งคำสั่งให้เอเจนต์ แต่ในจังหวะเวลาต่างกันและมีต้นทุนต่อบริบทต่างกัน

หลักการเลือกง่ายๆ คือ ถ้าคำสั่งจำเป็นเกือบทุกงาน ให้วางใน CLAUDE.md ถ้าจำเป็นเฉพาะงานประเภทหนึ่ง ให้เป็นสกิล ถ้าคุณพิมพ์คำขอยาวๆ เดิมซ้ำทุกครั้ง นั่นคือตัวเลือกสำหรับ command หรือสกิลที่เรียกด้วยมือ

ข้อห้ามเด็ดขาดอย่าย้ายไปไว้ในสกิล เพราะสกิลอาจไม่ถูกโหลด แต่กฎอย่าง "ห้าม commit ความลับ" ต้องมีผลเสมอ ข้อกำหนดแบบนี้ควรอยู่ใน CLAUDE.md และบังคับด้วยกลไก เช่น hook สิทธิ์การเข้าถึง หรือการตรวจใน CI เมื่อเป็นไปได้

วิธีสร้าง skill สำหรับ Claude Code ทีละขั้น

1. หาขั้นตอนที่ทำซ้ำ สัญญาณที่ดีคือคุณเคยอธิบายสิ่งเดิมให้เอเจนต์ฟังสามครั้ง หรือมีหัวข้อใน CLAUDE.md ที่ต้องใช้ในงานเพียงหนึ่งในสิบ
2. สร้างโฟลเดอร์ .claude/skills/<ชื่อ>/ และไฟล์ SKILL.md ภายใน
3. เขียน frontmatter ด้วย name และ description ที่บอกชัดว่าควรใช้สกิลเมื่อไร
4. เขียนขั้นตอน ด้วยคำสั่งที่เจาะจงและเกณฑ์ความสำเร็จ ว่าต้องตรวจอะไรและผลแบบใดนับว่าสำเร็จ
5. แยกส่วนที่ยาว ออกไปยังไฟล์ข้างเคียงและอ้างอิงจากเนื้อหาหลัก
6. ลบส่วนซ้ำออกจาก CLAUDE.md และเหลือบรรทัดชี้ไปยังสกิล เช่น "ดีพลอย ใช้สกิล deploy"
7. ตรวจสอบ ในเซสชันใหม่ ขอให้ทำงานด้วยคำพูดของคุณเอง โดยไม่บอกชื่อสกิล แล้วดูว่าเอเจนต์หยิบมาใช้หรือไม่ ถ้าไม่ ให้เขียน description ใหม่

ตัวอย่างสกิล

สกิลดีพลอย

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

สกิลรีวิว

---
name: review
description: รีวิวการเปลี่ยนแปลงปัจจุบันก่อน commit ใช้เมื่อขอให้ตรวจ diff หาข้อผิดพลาดในการแก้ไข หรือเตรียมการเปลี่ยนแปลงสำหรับ commit
---

# รีวิวการเปลี่ยนแปลง

1. ดึง diff: `git diff` และ `git diff --staged`
2. สำหรับไฟล์ที่เปลี่ยนแต่ละไฟล์ ตรวจ:
   - อินพุตของผู้ใช้ถูก escape ก่อนแสดงผล
   - SQL query ใช้ parameter
   - ไม่มีข้อความ debug หรือไฟล์ชั่วคราว
3. รันเทสต์และลินเตอร์ของโปรเจกต์ (คำสั่งอยู่ใน CLAUDE.md)
4. รายงาน: รายการปัญหาพร้อมไฟล์และบรรทัด เรียงจากร้ายแรงไปเล็กน้อย
   ถ้าไม่มีปัญหาเลย ให้บอกตรงๆ อย่าแต่งข้อคิดเห็นขึ้นมา

สกิลแบบนี้เปลี่ยนคำว่า "ดูหน่อยว่าโอเคไหม" ให้เป็นการตรวจที่ทำซ้ำได้ โดยใช้รายการเดียวกันทุกครั้ง

สกิลจบเซสชัน

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

ความผิดพลาดที่พบบ่อย

• คำอธิบายคลุมเครือ มีสกิลแต่เอเจนต์ไม่เรียกใช้ แก้ได้โดยเขียน description ใหม่พร้อมตัวกระตุ้นที่เจาะจง
• สกิลที่ยาวเป็นกำแพง ย้ายหัวข้อเก่า 400 บรรทัดทั้งหมดไปไว้ใน SKILL.md ปัญหาบริบทบวมก็กลับมาอีกแบบหนึ่ง เก็บเนื้อหาหลักให้สั้น และรายละเอียดไว้ในไฟล์ข้างเคียง
• ซ้ำซ้อนกับ CLAUDE.md ขั้นตอนเดียวกันเขียนไว้สองที่และค่อยๆ ไม่ตรงกัน แหล่งความจริงควรมีที่เดียว
• สกิลที่ทับซ้อนกัน สองสกิลที่มีคำอธิบายคล้ายกันทำให้เอเจนต์เลือกสุ่มๆ แยกให้ชัดด้วยข้อความ "ใช้เมื่อ / ไม่ใช้เมื่อ"
• คำสั่งที่ล้าสมัย สคริปต์ถูกเปลี่ยนชื่อแต่สกิลยังอ้างถึงชื่อเดิม สกิลเป็นส่วนหนึ่งของโค้ดโปรเจกต์ ให้แก้ไปพร้อมกับขั้นตอนนั้นใน commit เดียวกัน

เมื่อไรควรย้ายหัวข้อจาก CLAUDE.md ไปเป็นสกิล

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

สัญญาณที่สองคือความยาว หัวข้อที่อ่านไม่จบในหน้าจอเดียวมักเป็นขั้นตอน ไม่ใช่กฎ ขั้นตอนอ่านทั้งหมดได้สะดวกตอนที่ลงมือทำ ไม่ต้องถือไว้ตลอดเซสชัน

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

สรุป

Claude Code skills คือวิธีเก็บขั้นตอนไว้ข้างโปรเจกต์โดยไม่ต้องจ่ายด้วยบริบทในทุกเซสชัน คำอธิบายของสกิลมองเห็นได้เสมอ เนื้อหาโหลดเมื่อจำเป็น ไฟล์เสริมโหลดทีหลังอีก ใน CLAUDE.md เหลือแผนที่โปรเจกต์และกฎเด็ดขาด ส่วนสกิลรับงานอย่างดีพลอย รีวิว ปล่อยเวอร์ชัน และงานประเภทเดียวกันอื่นๆ โครงสร้างไฟล์คำสั่งและการเปิดเผยบริบทแบบทีละชั้นเราอธิบายอย่างละเอียดพร้อมการลงมือทำจริงในคอร์สเกี่ยวกับ harness engineering