วิธีเขียน Agent Skill ของตัวเองจากความผิดพลาดจริง

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

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

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

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

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

นี่คือความผิดพลาดที่เกิดขึ้นซ้ำบนเซิร์ฟเวอร์จริง คุณสั่งให้เอเจนต์เพิ่มบล็อก reverse proxy ลงใน nginx มันแก้ไขไฟล์ /etc/nginx/conf.d/app.conf แล้วรันคำสั่ง sudo systemctl restart nginx การแก้ไขนั้นมีข้อผิดพลาด (typo) ทำให้ 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 หนึ่งสัปดาห์ต่อมา ในงานอื่นที่ต่างออกไป ความผิดพลาดเดิมก็เกิดขึ้นอีก ครั้งที่สองนี้คือสัญญาณเตือน

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

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

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

โครงสร้างของ skill

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

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

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

---
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).

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

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

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

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

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

ฟิลด์ description คือบรรทัดที่มีผลกระทบสูงสุดในไฟล์

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

ให้เขียนคำอธิบายโดยใช้บุรุษที่ 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 แรกของแต่ละรายการ และใช้โควตา 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 นั้น

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

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

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

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

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

ให้จำกัดคำอธิบายให้แคบลงเฉพาะเงื่อนไขที่สำคัญจริง ๆ และระบุชื่อไฟล์หรือคำสั่งที่ครอบคลุม เพิ่ม 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 และเครื่องมืออื่น ๆ ที่รองรับมาตรฐานนี้ ส่วนการเขียนคำสั่งเพื่อให้สามารถใช้งานได้เมื่อย้ายไปยังโมเดลอื่นเป็นอีกเรื่องหนึ่ง ซึ่ง การเขียนทักษะที่ทำงานร่วมกับโมเดลใดก็ได้ ได้อธิบายไว้แล้ว

FAQ

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

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

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

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

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

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

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

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

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

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