วิธีเขียน Agent Skill ให้ทำงานแม่นยำจากความผิดพลาดจริง

การเขียนทักษะเอเจนต์ของคุณเองจากความล้มเหลวที่เกิดขึ้นจริง

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

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

เริ่มจากงานที่เอเจนต์ทำผิดพลาดสองครั้ง

ครั้งเดียวถือเป็นเรื่องบังเอิญ แต่สองครั้งคือรูปแบบ และรูปแบบนั้นมีค่าพอที่จะบันทึกเป็นไฟล์

นี่คือความผิดพลาดที่เกิดขึ้นซ้ำบนเซิร์ฟเวอร์จริง คุณสั่งให้เอเจนต์เพิ่มบล็อก reverse proxy ลงใน nginx มันแก้ไขไฟล์ /etc/nginx/conf.d/app.conf แล้วรัน sudo systemctl restart nginx การแก้ไขนั้นมีพิมพ์ผิด ทำให้ nginx ไม่สามารถเริ่มทำงานได้ และเว็บไซต์จะล่มจนกว่าคุณจะแก้ไข

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

คุณแก้ไขให้มันในแชท ทดสอบการตั้งค่าด้วย sudo nginx -t ก่อนที่จะแตะต้อง service แล้วจึงนำไปใช้ด้วย reload แทนที่จะใช้ restart หนึ่งสัปดาห์ต่อมา ในงานอื่น ก็เกิดความผิดพลาดเดิมขึ้นอีก ครั้งที่สองนี้คือสัญญาณ

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

คำแนะนำในการเขียนของ Anthropic ให้ความสำคัญกับเรื่องนี้เป็นอันดับแรก ให้รันเอเจนต์ในงานที่เป็นตัวแทนโดยไม่มีทักษะ บันทึกจุดที่มันล้มเหลว จากนั้นเขียนคำสั่งขั้นต่ำที่แก้ไขความล้มเหลวเหล่านั้น ความล้มเหลวคือข้อกำหนด ดังนั้นทักษะที่คุณไม่สามารถย้อนกลับไปหาที่มาของความล้มเหลวได้ มักจะเป็นทักษะที่ไม่มีใครต้องการ

สำหรับตัวอย่างการกลั่นกรองทักษะในลักษณะเดียวกัน คุณสามารถอ่าน Ponytail เปลี่ยนความล้มเหลวที่เกิดขึ้นซ้ำๆ ซึ่งเป็นเอเจนต์ที่เขียนทับข้อมูลมากกว่าที่คุณร้องขอ ให้กลายเป็นทักษะ ได้ตั้งแต่ต้นจนจบก่อนที่จะเขียนทักษะของคุณเอง

โครงสร้างของทักษะ (Skill)

ทักษะคือไดเรกทอรีที่มีไฟล์บังคับหนึ่งไฟล์อยู่ภายใน

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md จะขึ้นต้นด้วยบล็อก frontmatter ซึ่งเป็นการตั้งค่าที่เขียนด้วยรูปแบบ YAML (รูปแบบเดียวกับที่ใช้ในไฟล์ Docker Compose) อยู่ระหว่างเครื่องหมาย --- ตามด้วยคำสั่งในรูปแบบ markdown นี่คือทักษะทั้งหมดสำหรับความล้มเหลวที่กล่าวถึงข้างต้น

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

ไฟล์นั้นมีความยาวไม่ถึงยี่สิบบรรทัดและถือเป็นทักษะที่สมบูรณ์ ส่วนประกอบต่างๆ มีดังนี้:

• name: ความยาวสูงสุด 64 ตัวอักษร ใช้เฉพาะตัวอักษรพิมพ์เล็ก ตัวเลข และเครื่องหมายยัติภังค์เท่านั้น และต้องไม่มีคำว่า claude หรือ anthropic สำหรับทักษะส่วนบุคคลหรือทักษะของโปรเจกต์ นี่เป็นเพียงป้ายแสดงผลเท่านั้น คำสั่งที่คุณพิมพ์จะมาจากชื่อไดเรกทอรี ดังนั้นทักษะนี้จึงเรียกใช้งานด้วย /nginx-config-changes
• description: อธิบายว่าทักษะนี้ทำหน้าที่อะไรและควรใช้เมื่อใด ความยาวสูงสุด 1,024 ตัวอักษร บรรทัดนี้คือส่วนที่ทำงานจริง และหัวข้อถัดไปจะกล่าวถึงเรื่องนี้โดยเฉพาะ
• เนื้อหาหลัก: คำสั่งต่างๆ ซึ่งจะถูกโหลดเมื่อทักษะถูกเรียกใช้งานจริงเท่านั้น
• reference/: ไฟล์เพิ่มเติมที่เอเจนต์จะอ่านตามความต้องการ เชื่อมโยงไฟล์เหล่านี้จาก SKILL.md และควรเก็บลิงก์ไว้ในระดับเดียว (one level deep) เนื่องจากไฟล์ที่ถูกอ้างอิงจากไฟล์ที่ถูกอ้างอิงอีกทอดหนึ่ง มักจะถูกอ่านเพียงบางส่วนเท่านั้น
• scripts/: ไฟล์ที่เอเจนต์จะดำเนินการ (execute) แทนการอ่าน เฉพาะผลลัพธ์ของไฟล์เหล่านี้เท่านั้นที่จะใช้พื้นที่ context ดังนั้นสคริปต์ความยาว 300 บรรทัดจึงใช้ทรัพยากรน้อย

ทักษะจะขยายตัวไปสู่โครงสร้างเต็มรูปแบบเมื่อพฤติกรรมที่ต้องการแก้ไขมีความซับซ้อนจนจำเป็นต้องใช้พื้นที่เพิ่มขึ้น และ ทักษะที่ไม่ขี้เกียจจะใช้พื้นที่นั้นสำหรับ Depth Tree, ชุดไฟล์ gates และสัญญา PLAN.md เพื่อป้องกันไม่ให้เอเจนต์แจ้งว่างานเสร็จสิ้นแล้วในขณะที่งานส่วนอื่นยังไม่ได้ถูกแตะต้อง

ตำแหน่งที่คุณวางไดเรกทอรีจะเป็นตัวกำหนดว่าใครสามารถเข้าถึงทักษะนี้ได้บ้าง

• .claude/skills/<name>/SKILL.md ใน repository: สำหรับโปรเจกต์นี้เท่านั้น และจะติดไปกับทุกคนที่ clone repository นี้
• ~/.claude/skills/<name>/SKILL.md: สำหรับทุกโปรเจกต์บนเครื่องของคุณ และไม่มีใครอื่นเข้าถึงได้
• <plugin>/skills/<name>/SKILL.md: ถูกส่งมาพร้อมกับปลั๊กอิน โดยจะใช้งานได้ทุกที่ที่ปลั๊กอินนั้นถูกเปิดใช้งาน

สร้างทักษะด้วย mkdir -p .claude/skills/nginx-config-changes แล้วเขียนไฟล์ Claude Code จะคอยเฝ้าดูไดเรกทอรีเหล่านี้ ดังนั้นการแก้ไขทักษะที่มีอยู่จะมีผลทันทีภายในเซสชันที่กำลังทำงานอยู่ การสร้างไดเรกทอรี skills ระดับบนสุดที่ไม่มีอยู่ตอนเริ่มเซสชันจำเป็นต้องมีการรีสตาร์ท เนื่องจากไม่มีไดเรกทอรีให้เฝ้าดูในตอนที่เซสชันเริ่มต้นขึ้น

ฟิลด์ description คือบรรทัดที่ทรงพลังที่สุดในไฟล์

เมื่อเริ่มต้นทำงาน เอเจนต์จะโหลด name และ description ของทุกสกิลที่มีอยู่เข้าสู่บริบท แต่จะไม่โหลดเนื้อหาภายใน เมื่อคำขอของคุณเข้ามา บรรทัดนั้นจะเป็นพื้นฐานทั้งหมดในการตัดสินใจว่าสกิลนี้เกี่ยวข้องหรือไม่ ดังนั้นเนื้อหาที่สมบูรณ์แบบแต่มีคำอธิบายที่คลุมเครือจะไม่มีวันถูกอ่าน

ให้เขียนคำอธิบายในรูปแบบบุรุษที่ 3 เช่น "ทดสอบและโหลด nginx ใหม่ได้อย่างปลอดภัย" เป็นสิ่งที่ใช้ได้ แต่ "ฉันสามารถช่วยคุณเกี่ยวกับ nginx ได้" ไม่ควรใช้ เพราะข้อความนี้จะถูกแทรกเข้าไปใน system prompt ซึ่งการใช้บุรุษที่ 1 จะทำให้โมเดลเข้าใจว่ากำลังพูดถึงตัวเอง

ให้ระบุข้อมูล 2 อย่างในนั้น ได้แก่ สกิลนี้ทำอะไร และเงื่อนไขที่สกิลนี้จะถูกนำมาใช้ ให้วางกรณีการใช้งานที่สำคัญไว้ลำดับแรก เนื่องจาก Claude Code จะตัดรายการที่แสดงผลที่ 1,536 ตัวอักษร มีฟิลด์ when_to_use ที่เป็นทางเลือกสำหรับวลีเรียกใช้งานเพิ่มเติมและตัวอย่างคำขอ ซึ่งจะถูกต่อท้ายคำอธิบายภายใต้ขีดจำกัดเดียวกัน

จากนั้นให้ใช้คำที่คุณจะพิมพ์จริง description: Helps with nginx ไม่ตรงกับอะไรเลย เพราะไม่มีใครพิมพ์คำว่า "helps with" ตัวอย่างข้างต้นระบุชื่อ /etc/nginx, server block, reverse proxy และ TLS (transport layer security) certificate path ซึ่งเป็นคำศัพท์โดยประมาณของคำขอใดๆ ที่ควรจะเรียกใช้งานสกิลนี้

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

รักษาขนาดเนื้อหาให้กะทัดรัดเนื่องจากจะคงอยู่ในบริบท

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

Anthropic แนะนำให้รักษา SKILL.md ไว้ไม่เกิน 500 บรรทัด และย้ายรายละเอียดไปไว้ในไฟล์แยกต่างหาก การบีบอัดข้อมูลแสดงให้เห็นว่าเหตุใดตัวเลขนี้จึงไม่ใช่ตัวเลขที่กำหนดขึ้นมาลอยๆ เมื่อการสนทนาถูกสรุปเพื่อเพิ่มพื้นที่บริบท Claude Code จะแนบการเรียกใช้ทักษะล่าสุดของแต่ละรายการกลับเข้ามา โดยจะเก็บไว้เพียง 5,000 token แรกของแต่ละรายการ และเติมให้เต็มงบประมาณรวม 25,000 token โดยเริ่มจากทักษะที่ถูกเรียกใช้ล่าสุด ทักษะที่มีความยาวมากจะถูกตัดทอนออกไปกลางคัน และทักษะที่ยาวหลายรายการอาจผลักกันออกไปจนหมดสิ้น

ดังนั้น ให้เขียนเฉพาะสิ่งที่โมเดลยังไม่ทราบเท่านั้น โมเดลทราบดีว่า nginx คืออะไรและ reverse proxy ทำหน้าที่อย่างไร แต่โมเดลไม่ทราบกฎภายในบ้านของคุณเกี่ยวกับการใช้ reload แทน restart และกฎข้อนั้นคือเหตุผลเดียวที่ไฟล์นี้มีอยู่

หากทักษะสั่งให้เอเจนต์รันสคริปต์ที่รวมมาด้วย ให้ระบุพาธด้วย ${CLAUDE_SKILL_DIR} เพื่อให้สามารถแก้ไขพาธได้ไม่ว่าจะติดตั้งทักษะไว้ที่ใด และให้ทำการอนุมัติคำสั่งล่วงหน้าเพื่อให้การรันไม่หยุดชะงักที่การแจ้งเตือนขอสิทธิ์

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

การอนุญาตจะครอบคลุมเฉพาะรอบที่มีการเรียกใช้ทักษะและจะถูกล้างออกเมื่อคุณส่งข้อความถัดไป ดังนั้นสิทธิ์ดังกล่าวจะไม่กลายเป็นการอนุญาตถาวรโดยที่คุณไม่รู้ตัว

วิธีพิสูจน์ว่า skill ทำงาน

การเฝ้าดูการโหลด skill จะบอกเพียงว่า agent ค้นพบ skill นั้นแล้ว แต่ไม่ได้ยืนยันว่าคำตอบมีการเปลี่ยนแปลงหรือไม่ คุณควรตรวจสอบทั้งสองอย่างและทำใน session ใหม่เสมอ เนื่องจาก session ที่คุณใช้เขียน skill จะยังคงเก็บข้อมูลทุกอย่างที่คุณพิมพ์ไว้ระหว่างการเขียน ซึ่งบริบทที่ค้างอยู่นี้จะบดบังช่องโหว่ในไฟล์

1. เริ่ม session ใหม่ด้วย claude ในโปรเจกต์
2. พิมพ์คำขอในแบบที่คุณใช้ในวันทำงานปกติด้วยภาษาของคุณเอง โดยไม่ต้องระบุชื่อ skill
3. สังเกตการเรียกใช้งาน หาก skill ไม่ทำงาน ให้แก้ไขคำอธิบาย (description) ส่วนเนื้อหา (body) ยังไม่ใช่ปัญหาในขั้นตอนนี้
4. เรียกใช้งานด้วยตนเองโดยใช้ /nginx-config-changes เพื่อเป็นตัวควบคุม หากผลลัพธ์ถูกต้องเมื่อเรียกด้วยตนเองแต่ผิดพลาดเมื่อเรียกผ่านคำขอปกติ แสดงว่าเป็นปัญหาที่ตัว trigger ไม่ใช่ที่คำสั่ง (instruction)
5. รันคำขอเดิมโดยปิดการใช้งาน skill แล้วเปรียบเทียบคำตอบทั้งสอง ในเมนู /skills ให้เลือก skill นั้น กด Space เพื่อเปลี่ยนสถานะเป็น off แล้วกด Enter เพื่อบันทึก การกระทำนี้จะเขียนรายการ skillOverrides ลงใน .claude/settings.local.json และการกด Space อีกครั้งจะเป็นการเปลี่ยนสถานะกลับเป็น on เมื่อคุณทำเสร็จแล้ว
6. เขียนคำขอสองสามรายการที่ไม่ควรเรียกใช้ skill นี้ และตรวจสอบว่า skill ยังคงเงียบอยู่ตามที่ควรจะเป็น

หากต้องการทำกระบวนการนี้ให้เป็นอัตโนมัติ ให้ติดตั้งปลั๊กอิน skill-creator จาก marketplace อย่างเป็นทางการ

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

หากผลลัพธ์การติดตั้งแสดง Run /reload-plugins to activate. ให้รันคำสั่งนั้น จากนั้นขอให้ Claude ประเมิน skill ของคุณโดยระบุชื่อ ปลั๊กอินจะจัดเก็บกรณีทดสอบไว้ใน evals/evals.json ภายในไดเรกทอรีของ skill และรันแต่ละกรณีใน subagent แยกต่างหาก เพื่อให้ทุกการรันเริ่มต้นด้วยบริบทที่สะอาด จากนั้นปลั๊กอินจะเขียนการเปรียบเทียบระหว่างการใช้ skill กับไม่ใช้ skill ซึ่งเป็นตัวเลขที่แท้จริง คืออัตราความสำเร็จที่เพิ่มขึ้นเมื่อเทียบกับจำนวน token และเวลาที่เสียไปในการใช้ skill

skill สามารถพกพาหลักฐานการทำงานของตัวเองได้แทนที่จะปล่อยให้เป็นการรัน eval แยกต่างหาก ซึ่งเป็นสิ่งที่ skill Old Coder ทำ โดยให้ agent ส่งรายงานหลักฐานกลับมาเพื่อให้คุณนำไปรันซ้ำได้ด้วยตัวเอง

โหมดความล้มเหลว: สกิลไม่ทำงาน

คุณพิมพ์คำขอไปแล้ว แต่เอเจนต์ยังคงทำงานแบบเดิมที่ผิดพลาด และไม่มีบรรทัดแสดงการทำงานของสกิลปรากฏขึ้น ให้ตรวจสอบตามลำดับดังนี้

• คำอธิบายระบุว่าสกิลทำหน้าที่อะไร แต่ไม่ได้ระบุว่าควรใช้เมื่อใด ทำให้ไม่มีส่วนใดในคำขอของคุณที่ตรงกับเงื่อนไข
• คำอธิบายไม่มีคำที่คุณพิมพ์ หากคุณพิมพ์คำว่า "nginx" คำอธิบายก็ต้องมีคำว่า nginx อยู่ด้วย
• disable-model-invocation: true ถูกตั้งค่าไว้ใน frontmatter ซึ่งจะกันไม่ให้คำอธิบายถูกนำไปรวมในบริบทของโมเดล ทำให้สกิลสามารถเรียกใช้งานได้โดยคุณผ่าน /name เท่านั้น
• paths glob ใน frontmatter จำกัดการเปิดใช้งานไว้เฉพาะไฟล์ที่ตรงกับเงื่อนไข และไฟล์ที่คุณกำลังทำงานอยู่ไม่ตรงกับเงื่อนไขดังกล่าว
• สกิลถูกเก็บไว้ในไดเรกทอรี .claude/skills/ ที่ซ้อนอยู่ใต้ไดเรกทอรีเริ่มต้นของคุณ สกิลเหล่านี้จะถูกโหลดก็ต่อเมื่อเอเจนต์อ่านหรือแก้ไขไฟล์ภายในไดเรกทอรีย่อยนั้น ดังนั้นจนกว่าจะถึงตอนนั้น สกิลจะไม่พร้อมใช้งานเลย

โหมดความล้มเหลว: สกิลทำงานตลอดเวลา

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

ให้จำกัดคำอธิบายให้แคบลงเฉพาะเงื่อนไขที่สำคัญจริง ๆ และระบุชื่อไฟล์หรือคำสั่งที่ครอบคลุม เพิ่ม paths glob เมื่อสกิลใช้ได้กับไฟล์บางประเภทเท่านั้น สำหรับการดำเนินการใด ๆ ที่มีผลข้างเคียง เช่น การ deploy หรือการ commit ให้ตั้งค่า disable-model-invocation: true และเรียกใช้งานด้วยตนเองผ่าน /name เพื่อป้องกันไม่ให้เอเจนต์ตัดสินใจเองว่าถึงเวลาที่เหมาะสมในการ deploy

รูปแบบความล้มเหลว: ทักษะที่ควรอยู่ในไฟล์กฎ

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

ความล้มเหลวที่แท้จริงคือการใส่ไว้ในทั้งสองที่ สำเนาทั้งสองชุดจะมีความคลาดเคลื่อน และเมื่อเอเจนต์ทำงานผิดพลาด คุณจะไม่สามารถระบุได้ว่าเอเจนต์ทำตามสำเนาชุดไหน ให้เลือกที่อยู่เพียงแห่งเดียวสำหรับคำสั่งแต่ละชุด กฎที่อยู่ในที่เดียวอย่างถูกต้องแล้วแต่ยังถูกมองข้ามเป็นปัญหาที่ต่างออกไป และ กลไกเบื้องหลังคำสั่งที่ถูกเพิกเฉย เป็นสิ่งที่ควรตรวจสอบก่อนที่คุณจะย้ายมันไปไว้ในทักษะโดยหวังว่าการย้ายจะช่วยแก้ปัญหาได้ ขอบเขตระหว่างทักษะ, MCP servers และไฟล์กฎ จะช่วยอธิบายกรณีที่ซับซ้อนกว่า รวมถึงกรณีที่คำตอบที่ถูกต้องคือการใช้ MCP (model context protocol) server ซึ่งเป็นการมอบเครื่องมือใหม่ให้เอเจนต์แทนที่จะเป็นการเพิ่มคำสั่งใหม่

แบ่งปันเมื่อผ่านการพิสูจน์แล้ว

ทักษะที่ผ่านการใช้งานจริงมาหนึ่งสัปดาห์ถือว่าคุ้มค่าที่จะนำไปใช้ต่อ ทักษะของโปรเจกต์ใน .claude/skills/ จะถูกตรวจสอบเหมือนกับโค้ดและจะถูกจัดเก็บไปพร้อมกับ repository ดังนั้นเพื่อนร่วมทีมที่ clone โปรเจกต์ไปจะได้รับสิ่งที่คุณแก้ไขโดยไม่ต้องตั้งค่าเพิ่มเติม การย้ายทักษะระหว่าง repository โดยไม่ต้องใช้วิธีคัดลอกและวางเป็นปัญหาเฉพาะตัว ซึ่งมีอธิบายไว้ใน วิธีการแบ่งปัน agent skills ข้าม repository

ข้อควรทราบเรื่องความสามารถในการพกพา Claude Code ยอมรับฟิลด์ frontmatter ได้หลายรายการ แต่มาตรฐาน Agent Skills อนุญาตเพียง 6 รายการเท่านั้น ได้แก่ name, description, license, compatibility, metadata และ allowed-tools หากคุณอัปโหลดทักษะไปยัง claude.ai หรือจัดแพ็กเกจสำหรับ Skills API โดยมีฟิลด์อื่นอยู่ใน frontmatter ระบบจะปฏิเสธการทำงานทันทีแทนที่จะเพิกเฉยต่อฟิลด์นั้น:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

หากใช้เพียง 6 ฟิลด์ดังกล่าว ไฟล์เดียวกันจะสามารถโหลดได้ทั้งใน Claude Code และเครื่องมืออื่นที่รองรับมาตรฐานนี้ อย่างไรก็ตาม สถานที่ที่โหลดไฟล์จะเป็นตัวกำหนดว่าทักษะทำอะไรได้บ้าง เนื่องจาก Cowork ทำงานใน Anthropic sandbox ในขณะที่ Claude Code ทำงานบนเครื่องของคุณหรือ VPS ดังนั้นทักษะ nginx ที่กล่าวถึงข้างต้นจึงมีประโยชน์เมื่อนำไปใช้ในเครื่องของเพื่อนร่วมทีม แต่จะไม่มีประโยชน์เลยใน sandbox ที่ไม่สามารถเข้าถึงเซิร์ฟเวอร์ได้ การเขียนคำสั่งเพื่อให้ทักษะสามารถใช้งานได้เมื่อย้ายไปยังโมเดลอื่นเป็นงานที่แยกต่างหาก ซึ่งมีอธิบายไว้ใน การเขียนทักษะที่ทำงานได้กับทุกโมเดล

FAQ

ไฟล์ SKILL.md ควรมีความยาวเท่าใด

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

ทำไมทักษะของฉันถึงไม่ทำงาน

คำอธิบาย (description) มักเป็นสาเหตุหลัก เนื่องจากเป็นส่วนเดียวของทักษะที่อยู่ในบริบทเมื่อโมเดลตัดสินใจเลือกใช้ ตรวจสอบให้แน่ใจว่าคำอธิบายระบุว่าควรใช้ทักษะเมื่อใด ไม่ใช่เพียงแค่ระบุว่าทักษะทำอะไร และต้องมีคำที่คุณใช้พิมพ์ในคำสั่งจริง หากคำอธิบายถูกต้องแล้ว ให้ตรวจสอบ frontmatter สำหรับ disable-model-invocation: true ซึ่งอาจซ่อนทักษะจากโมเดลโดยสิ้นเชิง และตรวจสอบ paths glob ที่อาจจำกัดทักษะไว้เฉพาะไฟล์ที่คุณไม่ได้กำลังแก้ไขอยู่ อีกสาเหตุหนึ่งคือทักษะอยู่ในไดเรกทอรี .claude/skills/ ที่ซ้อนอยู่ใต้ไดเรกทอรีเริ่มต้นของคุณ ซึ่งทักษะจะโหลดก็ต่อเมื่อเอเจนต์อ่านหรือแก้ไขไฟล์ในไดเรกทอรีย่อยนั้นแล้วเท่านั้น

ควรสร้างเป็นทักษะหรือเพิ่มเป็นบรรทัดในไฟล์กฎ (rules file)

ให้พิจารณาว่าทักษะนั้นใช้กับงานของคุณมากน้อยเพียงใด ไฟล์กฎจะถูกโหลดในทุกเซสชัน จึงควรเก็บข้อมูลที่เป็นจริงสำหรับทุกงาน เช่น ตัวจัดการแพ็กเกจ (package manager) หรือข้อกำหนดในการตั้งชื่อ branch ส่วนทักษะจะถูกโหลดเฉพาะเมื่อมีการเรียกใช้ จึงเป็นที่ที่เหมาะสมสำหรับขั้นตอนที่สำคัญเฉพาะงานบางประเภทเท่านั้น ห้ามเขียนคำสั่งเดียวกันไว้ในทั้งสองที่ เพราะสำเนาทั้งสองอาจมีความแตกต่างกันเมื่อเวลาผ่านไป และคุณจะไม่สามารถระบุได้ว่าเอเจนต์ทำตามคำสั่งจากที่ใด

ฉันจะทราบได้อย่างไรว่าทักษะช่วยงานได้จริง

ให้เปรียบเทียบกับค่าพื้นฐาน (baseline) โดยรวบรวมคำสั่งจริงจำนวนหนึ่ง แล้วรันแต่ละคำสั่งในเซสชันใหม่โดยเปิดใช้งานทักษะ จากนั้นรันคำสั่งเดิมอีกครั้งโดยปิดใช้งานทักษะจากเมนู /skills แล้วอ่านคำตอบทั้งสองแบบเปรียบเทียบกัน การใช้เซสชันใหม่มีความสำคัญเนื่องจากบทสนทนาที่คุณเขียนทักษะไว้นั้นยังมีคำอธิบายของคุณอยู่ ซึ่งอาจทำให้ไฟล์ที่ไม่สมบูรณ์ดูเหมือนสมบูรณ์ได้ ปลั๊กอิน skill-creator สามารถรันการเปรียบเทียบนี้ให้คุณและรายงานอัตราความสำเร็จควบคู่ไปกับต้นทุนของโทเค็น

ฉันสามารถใช้ SKILL.md เดียวกันกับเอเจนต์อื่นได้หรือไม่

ได้ ตราบใดที่คุณยังคงอยู่ในฟิลด์ที่มาตรฐาน Agent Skills กำหนดไว้ ได้แก่ name, description, license, compatibility, metadata และ allowed-tools โดย Claude Code รองรับฟิลด์อื่นๆ อีกมากมาย และยังรองรับคุณสมบัติในส่วนเนื้อหา เช่น การแทรกคำสั่งเชลล์ (shell command injection) ซึ่งเครื่องมืออื่นอาจไม่รองรับ การอัปโหลดทักษะที่มีฟิลด์นอกเหนือจากมาตรฐานจะทำให้เกิดข้อผิดพลาดที่ระบุรายการคุณสมบัติที่อนุญาตไว้อย่างชัดเจน ดังนั้นควรตัดสินใจตั้งแต่เนิ่นๆ ว่าทักษะนี้มีไว้เพื่อใช้ใน Claude Code เท่านั้น หรือต้องการให้สามารถนำไปใช้กับเครื่องมืออื่นได้ด้วย