วิธีเขียน Agent Skill ของคุณเองจากความผิดพลาดจริง
เรียนรู้โครงสร้าง SKILL.md เขียนบรรทัด description ให้ Agent เรียกใช้ถูกจังหวะ และทดสอบด้วยงานเดิม เพื่อเปลี่ยนความผิดพลาดซ้ำให้เป็นทักษะที่ใช้ได้จริง
การเขียนทักษะเอเจนต์ของคุณเองจากความล้มเหลวที่เกิดขึ้นจริง
วิธีที่ดีที่สุดในการเขียนทักษะเอเจนต์ของคุณเองคือการกลั่นกรองจากความล้มเหลวที่เกิดขึ้นจริง ให้ค้นหางานที่เอเจนต์เขียนโค้ดของคุณทำผิดพลาดสองครั้ง จดบันทึกการแก้ไขที่คุณพิมพ์ลงไปทั้งสองครั้ง แล้วบันทึกการแก้ไขนั้นเป็นไฟล์ 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 ระบุหลักการนี้เป็นอันดับแรก ให้เรียกใช้ agent กับงานตัวแทนโดยยังไม่กำหนด skill บันทึกจุดที่ทำงานล้มเหลว แล้วเขียนคำสั่งขั้นต่ำที่แก้ไขความล้มเหลวเหล่านั้น ความล้มเหลวคือข้อกำหนด ดังนั้นหากไม่สามารถเชื่อมโยง skill ใดกลับไปยังความล้มเหลวได้ โดยทั่วไป skill นั้นก็ไม่มีความจำเป็น หลักการคัดกรองเดียวกันนี้ใช้ได้กับ skill ที่ติดตั้งแทนการเขียนเอง และ skill ที่เผยแพร่โดย Matt Pocock จำนวน 27 รายการ ยังแบ่ง skill เหล่านั้นเป็นรายการที่นักพัฒนาซึ่งดูแล VPS เพียงคนเดียวควรติดตั้ง กับรายการที่ให้ประโยชน์ก็ต่อเมื่อทำงานเป็นทีม
สำหรับตัวอย่างการกลั่นกรองทักษะในลักษณะเดียวกัน คุณสามารถอ่าน Ponytail เปลี่ยนความล้มเหลวที่เกิดขึ้นซ้ำๆ ซึ่งเป็นเอเจนต์ที่เขียนทับข้อมูลมากกว่าที่คุณร้องขอ ให้กลายเป็นทักษะ ได้ตั้งแต่ต้นจนจบก่อนที่จะเขียนทักษะของคุณเอง
โครงสร้างของทักษะ (Skill)
ทักษะคือไดเรกทอรีที่มีไฟล์บังคับหนึ่งไฟล์อยู่ภายใน
.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│ └── proxy-headers.md
└── scripts/
└── check-and-reload.shSKILL.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-changesdescription: อธิบายว่าทักษะนี้ทำหน้าที่อะไรและควรใช้เมื่อใด ความยาวสูงสุด 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 จะยังคงเก็บข้อมูลทุกอย่างที่คุณพิมพ์ไว้ระหว่างการเขียน ซึ่งบริบทที่ค้างอยู่นี้จะบดบังช่องโหว่ในไฟล์
- เริ่ม session ใหม่ด้วย
claudeในโปรเจกต์ - พิมพ์คำขอในแบบที่คุณใช้ในวันทำงานปกติด้วยภาษาของคุณเอง โดยไม่ต้องระบุชื่อ skill
- สังเกตการเรียกใช้งาน หาก skill ไม่ทำงาน ให้แก้ไขคำอธิบาย (description) ส่วนเนื้อหา (body) ยังไม่ใช่ปัญหาในขั้นตอนนี้
- เรียกใช้งานด้วยตนเองโดยใช้
/nginx-config-changesเพื่อเป็นตัวควบคุม หากผลลัพธ์ถูกต้องเมื่อเรียกด้วยตนเองแต่ผิดพลาดเมื่อเรียกผ่านคำขอปกติ แสดงว่าเป็นปัญหาที่ตัว trigger ไม่ใช่ที่คำสั่ง (instruction) - รันคำขอเดิมโดยปิดการใช้งาน skill แล้วเปรียบเทียบคำตอบทั้งสอง ในเมนู
/skillsให้เลือก skill นั้น กดSpaceเพื่อเปลี่ยนสถานะเป็นoffแล้วกดEnterเพื่อบันทึก การกระทำนี้จะเขียนรายการskillOverridesลงใน.claude/settings.local.jsonและการกดSpaceอีกครั้งจะเป็นการเปลี่ยนสถานะกลับเป็นonเมื่อคุณทำเสร็จแล้ว - เขียนคำขอสองสามรายการที่ไม่ควรเรียกใช้ 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เท่านั้นpathsglob ใน 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 เท่านั้น หรือต้องการให้สามารถนำไปใช้กับเครื่องมืออื่นได้ด้วย