SSD Nodes Learn Hosting plans →
คู่มือ Matt Connorโดย Matt Connor

วิธีแชร์ Agent Skills ข้าม Repository ไม่ให้โค้ดเพี้ยน

หยุดคัดลอกไฟล์ Agent Skills ไปวางซ้ำในหลายโปรเจกต์จนเกิดปัญหาโค้ดไม่ตรงกัน เปลี่ยนมาจัดการด้วยระบบ Dependency ที่มีการระบุเวอร์ชันและทำ Smoke Test เพื่อควบคุมคุณภาพอย่างเป็นระบบ

วิธีการแชร์ทักษะของ Agent ข้าม Repository

หากต้องการแชร์ทักษะของ Agent ข้าม Repository ให้หยุดใช้วิธีคัดลอกไฟล์และเปลี่ยนมาใช้วิธีอ้างอิงแทน โดยให้คง Repository ของทักษะไว้ที่เดียว ทำการ tag เวอร์ชัน และให้แต่ละโปรเจกต์ระบุเวอร์ชันที่ต้องการใช้งาน จากนั้นให้เพิ่ม smoke test สำหรับแต่ละทักษะ และตรวจสอบการอัปเดตเวอร์ชันทุกครั้งเช่นเดียวกับการตรวจสอบการอัปเดต Dependency

กระบวนการนี้ประกอบด้วย 4 ส่วน ได้แก่ แหล่งข้อมูลหลักที่ใช้ร่วมกัน, การระบุเวอร์ชันที่แน่นอนในแต่ละ Repository, การทำ smoke test สำหรับแต่ละทักษะ และขั้นตอนการตรวจสอบ เนื้อหาด้านล่างนี้จะอธิบายถึงเหตุผลที่ต้องมีแต่ละส่วน สิ่งที่เครื่องมือที่เปิดตัวในปี 2026 ทำได้ และวิธีการสร้างระบบทั้งหมดนี้บน git remote ที่คุณโฮสต์เองโดยไม่ต้องพึ่งพา git host ภายนอกหรือ package registry ยกเว้นเพียงส่วนของ smoke test เท่านั้น เนื่องจาก smoke test จะต้องรัน Claude Code ซึ่งจะส่งคำขอไปยัง model API ดังนั้นในขั้นตอนนี้ข้อมูลจะถูกส่งออกจากเซิร์ฟเวอร์ของคุณ

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

ตำแหน่งที่ skill อยู่ และเหตุใดการแชร์จึงทำได้ยาก

Claude Code โหลด skill จากตำแหน่งต่อไปนี้และตำแหน่งอื่น ๆ โดย เอกสาร skills จะระบุแต่ละ path ไว้

  • .claude/skills/<skill-name>/SKILL.md ภายในไดเรกทอรี managed settings เป็นตำแหน่งระดับองค์กร โดยจะโหลดให้ผู้ใช้ทุกคนบนเครื่องที่องค์กร deploy
  • ~/.claude/skills/<skill-name>/SKILL.md เป็นตำแหน่งส่วนบุคคล โดยจะโหลดในทุก project ของคุณและไม่โหลดใน project ของผู้อื่น
  • .claude/skills/<skill-name>/SKILL.md เป็นตำแหน่งระดับ project โดยจะโหลดสำหรับผู้ที่ checkout repository นั้น
  • <plugin>/skills/<skill-name>/SKILL.md อยู่ภายใน plugin โดยจะโหลดในทุกที่ที่เปิดใช้งาน plugin นั้น

Claude Code ยังโหลด skill จากไดเรกทอรี project ที่ซ้อนกัน ไดเรกทอรีที่ระบุด้วย --add-dir และ skill ที่เปิดใช้งานสำหรับบัญชี claude.ai ของคุณ

ตำแหน่งระดับ project เป็นตัวเลือกที่เหมาะสำหรับทีม เพราะไฟล์จะถูก commit และทุกคนที่ clone repo จะได้รับไฟล์นั้น แต่จุดนี้เองที่ทำให้เกิดปัญหา skill ใน .claude/skills/ เป็นของ repository เดียว คุณมี 8 repositories ดังนั้น skill จึงถูกคัดลอกไว้ 8 ชุด

frontmatter ไม่ได้ช่วยแก้ปัญหานี้ Agent Skills spec อนุญาตให้ใช้ 6 keys และ distribution paths ที่บังคับใช้ข้อกำหนดนี้จะแสดงรายการดังกล่าวเมื่อคุณใช้ key อื่น:

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

สิ่งที่ไม่มีอยู่คือ key version คุณสามารถบันทึก version ไว้ภายใต้ metadata ได้ แต่ spec ไม่ได้กำหนด dependency pin หรือกลไกการอัปเดตไว้ เรื่องนี้สมเหตุสมผล เพราะ skill เป็นเอกสาร ไม่ใช่ package แต่ก็หมายความว่าการจัดการ version ต้องมาจาก layer ที่อยู่รอบไฟล์ และ layer นั้นเป็นหน้าที่ของคุณ

ปัญหาที่หนึ่ง: สำเนาแปดชุดที่ค่อยๆ แตกต่างกัน

การคัดลอกและวางทำงานได้ในวันแรก แต่จะล้มเหลวในวันที่หกสิบ มีคนแก้ไขคำสั่งที่ผิดพลาดใน repo payments แต่ไม่ได้แตะต้องอีกเจ็ดชุดที่เหลือ อีกคนหนึ่งเพิ่มกฎเกี่ยวกับการแบ่งหน้าใน orders ตอนนี้ชื่อทักษะเดียวกันให้ผลลัพธ์ที่ต่างกันสองแบบ ขึ้นอยู่กับว่า agent เริ่มทำงานในไดเรกทอรีใด และไม่มีนักพัฒนาคนไหนทราบเรื่องนี้

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

ปัญหาที่สอง: ไม่มีการระบุเวอร์ชันที่แน่นอน

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

นั่นหมายความว่านักพัฒนาสองคนที่ทำงานบน commit เดียวกันของแอปพลิเคชันเดียวกัน อาจกำลังรันคำสั่งที่แตกต่างกัน เพราะพวกเขาทำการซิงค์ในวันที่ต่างกัน นอกจากนี้ยังหมายความว่าคุณไม่สามารถตอบคำถามสำคัญหลังจากที่ agent ทำงานผิดพลาดได้ว่า: ทักษะเวอร์ชันใดที่สร้างผลลัพธ์นี้ขึ้นมา? หากไม่มีการบันทึก revision ไว้ การรันนั้นจะไม่สามารถทำซ้ำได้ ส่งผลให้รายงานข้อผิดพลาดไม่สามารถนำไปดำเนินการแก้ไขต่อได้

ปัญหาที่สาม: ไม่มีใครทราบว่าทักษะยังคงทำงานได้ตามปกติหรือไม่

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

ไม่มีสิ่งใดแจ้งเตือนความล้มเหลวอย่างชัดเจนในกรณีเหล่านี้ เอเจนต์ยังคงตอบกลับได้ตามปกติ เพียงแต่คำตอบนั้นมีคุณภาพแย่ลงกว่าเมื่อเดือนที่แล้ว ซึ่งเป็นสิ่งที่สังเกตได้ยากหากพิจารณาเพียงทีละ pull request

สิ่งที่เครื่องมือในปี 2026 แก้ไขได้

ขณะนี้มีแนวทางหลายแบบทยอยออกมา และแต่ละแบบเห็นต่างกันว่าควรเก็บ version ไว้ที่ใด

Lockfiles. เครื่องมือ command line skills จาก Vercel Labs (vercel-labs/skills, ใช้สัญญาอนุญาต MIT, v1.7.2 ณ วันที่ 9 October 2026) ติดตั้ง skills จาก git repository ลงในไดเรกทอรีที่ agent ของคุณกำหนด และรองรับโครงสร้างของ agent มากกว่า seventy รายการ npx skills add <repo> ใช้สำหรับติดตั้ง, npx skills update ใช้สำหรับอัปเกรด และ npx skills list ใช้แสดงรายการที่มีอยู่ เครื่องมือนี้เก็บ lock files สองไฟล์ ไฟล์ระดับ global ที่ ~/.agents/.skill-lock.json บันทึกสิ่งที่ผู้ใช้รายหนึ่งติดตั้งไว้ ตั้งแต่ v1.4.1 (20 February 2026) การติดตั้งในระดับ project จะเขียน skills-lock.json ไว้ที่ project root ด้วย และ source code ของเครื่องมือระบุว่าไฟล์นี้ควร commit เข้า version control npx skills experimental_install จะกู้คืน skills ของ project จากไฟล์ดังกล่าว Issue 283 ซึ่งขอคำสั่ง skills install สำหรับกู้คืน global lock file บนเครื่องอื่น ถูกปิดโดยระบุว่าไม่มีแผนดำเนินการเมื่อวันที่ 5 November 2026 โดย maintainer ระบุว่าเป็นคำขอเดียวกับ issue 549 ให้ถือว่าทั้งสอง issue เป็นรายงานสถานะ lockfile ระดับ project มีอยู่จริง ใน v1.8.1 ที่เผยแพร่แล้ว คำสั่ง restore ยังคงระบุเป็น experimental ใน help แต่ npx skills install เมื่อไม่ระบุ source ก็กู้คืน project lockfile ได้เช่นกัน

Specs and tests. SkillSpec ใช้อีกแนวทางหนึ่ง โดยมอง SKILL.md เป็น contract ที่ต้องตรวจสอบ แทนที่จะเป็นข้อความที่เชื่อถือได้โดยไม่ตรวจสอบ เป้าหมายที่ระบุไว้คือทำให้ skills "ทำตามได้, ทดสอบได้ และพิสูจน์ได้" skillspec doctor <path> รายงานจุดที่ agent มีแนวโน้มจะหลุดจากลำดับการทำงาน skillspec boundary map <path> แสดงเนื้อหาของ skill และ skillspec boundary assess <path> รายงานสิ่งที่ skill เข้าถึงได้ โดยจัดอันดับตามความเสี่ยง เครื่องมือนี้เป็น Rust crate และใช้สัญญาอนุญาตแบบคู่ คือ MIT หรือ Apache 2.0 Version 0.2.2 เผยแพร่เมื่อ 29 July 2026 และยังเป็น version ล่าสุดบน crates.io ณ วันที่ 10 October 2026 ให้ติดตั้ง version ที่ระบุไว้ แทนการติดตั้ง version ล่าสุด:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

ตั้งแต่ Cargo 1.100 ซึ่งเผยแพร่เมื่อ 12 November 2026 cargo install จะใช้ lockfile ที่จัดแพ็กมาให้เป็นค่าเริ่มต้น และ --locked จะไม่ทำงานใด ๆ skillspec --version ควรแสดง 0.2.2 หากได้หมายเลขอื่น แสดงว่า binary รุ่นเก่าซึ่งอยู่ก่อนหน้าใน PATH กำลังถูกเลือกใช้งาน

Vendor practice. Google อธิบายวิธีสร้าง skills ใน google/skills ไว้ในบทความ วิธีสร้าง, ทดสอบ และขยายการใช้งาน agent skills เมื่อตัดเรื่องขนาดของระบบออก กลไกนี้ก็คือ continuous integration (CI) ตามปกติ ทุก skill ต้องผ่าน linter สำหรับตรวจสอบ frontmatter metadata, จำนวนบรรทัด, โครงสร้างไดเรกทอรี และการตั้งชื่อ ก่อน merge ระบบตรวจสอบ link จะทำให้ build ล้มเหลวเมื่อ URL ใดก็ตามตอบกลับด้วย 404 ซึ่งช่วยตรวจจับ link ที่ดูน่าเชื่อถือแต่ agent สร้างขึ้นเอง ผู้เขียนต้องจัดเตรียม evaluation prompt suite และ scoring rubric ไว้พร้อมกับ skill จากนั้น scheduled evaluation jobs จะทำงานทุกสัปดาห์กับ library ทั้งหมดเพื่อตรวจจับ regression และทุก skill จะมี owner ที่ระบุชื่อไว้ โดยคาดหวังให้ owner แก้ไขเมื่อคุณภาพลดลง

รูปแบบที่อยู่ภายใต้คำตอบทั้งสามประการ

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

  1. แหล่งข้อมูลเดียวที่เชื่อถือได้ (One source of truth): ทักษะหนึ่งอย่างจะมีที่เก็บเพียงแห่งเดียว และทุก repository จะอ้างอิงไปยังที่เก็บนั้นแทนการเก็บสำเนาไว้
  2. การระบุเวอร์ชันที่แน่นอนต่อ repository: แต่ละโปรเจกต์จะบันทึก revision ที่ใช้งานจริงไว้ ดังนั้นการอัปเกรดจึงเป็นเพียงการทำ commit ในโปรเจกต์นั้นพร้อมระบุผู้เขียนและวันที่
  3. การทดสอบเบื้องต้นต่อหนึ่งทักษะ (Smoke test): การตรวจสอบที่รันได้จริงหนึ่งรายการเพื่อพิสูจน์ว่าทักษะนั้นยังคงให้ผลลัพธ์ตามที่ระบุไว้
  4. เส้นทางการตรวจสอบ (Review path): การเปลี่ยนแปลงทักษะที่ใช้ร่วมกันจะต้องผ่านการตรวจสอบ และผู้ใช้งานทุกคนจะเห็นความแตกต่าง (diff) ก่อนที่จะนำไปใช้

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

โครงสร้างสำหรับทีมขนาดเล็กบน Git remote ที่โฮสต์เอง

ที่เก็บข้อมูล (repository) หนึ่งแห่งจะเก็บทักษะความรู้เอาไว้ โดยไม่มีข้อมูลอื่นปะปน ประวัติการแก้ไขจึงอ่านได้เสมือนเป็นบันทึกการเปลี่ยนแปลง (changelog) ของคำแนะนำต่างๆ

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

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

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

หาก remote ของคุณคือ Gitea, Forgejo, GitLab หรือเป็น bare repository ที่ใช้งานผ่าน SSH บน VPS ของคุณเอง เนื้อหาต่อจากนี้จะไม่มีการเปลี่ยนแปลงใดๆ ทุกอย่างในที่นี้คือการทำงานของ git ร่วมกับการใช้ symlink

การตรึงเวอร์ชันด้วย git submodule

Submodule จะบันทึก commit ที่เจาะจงของ repository อื่นไว้ภายใน repository ของคุณ บันทึกดังกล่าวคือการตรึงเวอร์ชัน (pin) ในแต่ละโปรเจกต์ที่เรียกใช้งาน:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

Symlink คือส่วนที่ทำให้กลไกนี้ทำงานได้ รายการ skill ในระดับโปรเจกต์อาจเป็น symlink ที่ชี้ไปยังไดเรกทอรีอื่นบนดิสก์ ซึ่ง Claude Code จะติดตาม symlink นั้นไปอ่าน SKILL.md จากปลายทาง ทำให้ skill โหลดเข้ามาเป็น skill ปกติของโปรเจกต์ ในขณะที่ข้อมูลจริงถูกเก็บไว้ใน submodule ณ commit ที่คุณเลือก

ตรวจสอบการตรึงเวอร์ชัน:

git submodule status

บรรทัดที่ถูกต้องจะขึ้นต้นด้วยช่องว่าง ตามด้วย commit, path และ tag ล่าสุด:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

หากขึ้นต้นด้วย - หมายความว่า submodule ยังไม่ได้ถูก initialised ทำให้ .claude/skills/api-review ไม่ชี้ไปยังที่ใดและ skill จะไม่โหลดโดยไม่มีการแจ้งเตือน แก้ไขปัญหานี้ด้วย git submodule update --init หากขึ้นต้นด้วย + หมายความว่า commit ที่ checkout อยู่ไม่ตรงกับที่บันทึกไว้ ซึ่งหมายความว่านักพัฒนารายนั้นกำลังรันคำสั่งที่ไม่มีใครใช้ การ clone ใหม่จำเป็นต้องใช้ git clone --recurse-submodules และควรระบุคำสั่งนี้ไว้ใน README เพราะการ clone ปกติจะทำให้ vendor/agent-skills ว่างเปล่าและไม่มีการแสดงข้อผิดพลาด

การอัปเกรดเป็นสิ่งที่ต้องทำโดยเจตนา ซึ่งเป็นหัวใจสำคัญของวิธีนี้:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

บรรทัด diff คือเส้นทางการตรวจสอบ (review path) ซึ่งจะแสดงการเปลี่ยนแปลงเดียวกันกับที่ repository อื่นๆ ที่เรียกใช้งานจะเห็น และสามารถรวมไว้ใน pull request ได้

การ pin ด้วย marketplace ของ plugin แทน

หากไม่ต้องการให้ developer ทุกคนเรียนรู้การใช้ submodule ระบบ plugin ของ Claude Code จะจัดการการแจกจ่ายให้ และรองรับ remote แบบ self-hosted วาง catalog ไว้ที่ .claude-plugin/marketplace.json ใน skills repository:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

ในกรณีนี้มี source ที่แตกต่างกัน 2 จุด และการสับสนระหว่างสองจุดนี้เป็นข้อผิดพลาดที่พบบ่อย source ของ marketplace ซึ่งหมายถึงแหล่งที่ใช้ดึง catalog เอง รองรับ ref สำหรับ branch หรือ tag และใน Claude Code v2.1.324 หรือใหม่กว่า รองรับ commit SHA แบบเต็มที่เป็นตัวพิมพ์เล็กทั้งหมด แต่ไม่รองรับ field sha แยกต่างหาก ส่วน source ของ plugin ภายใน catalog รองรับทั้งสองแบบ และเมื่อกำหนดทั้งคู่ ค่า sha จะเป็น pin ที่มีผล ให้ pin catalog ผ่าน ref ของ marketplace source และ pin plugin ผ่าน sha ของ catalog entry ชื่อ type ก็แตกต่างกันเช่นกัน ภายใน catalog url หมายถึง git repository ที่ต้อง clone ส่วนใน marketplace source url หมายถึงลิงก์โดยตรงไปยังไฟล์ marketplace.json และ git repository คือ git

จากนั้นแต่ละ repository ที่ใช้งานจะประกาศ marketplace ไว้ใน .claude/settings.json ที่ commit ร่วมกัน:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Claude Code จะลงทะเบียน marketplace ให้ teammate เมื่อ teammate ยอมรับ workspace trust dialog สำหรับ project folder โดยไม่ต้องมี wiki page คอยบอกขั้นตอนนี้ catalog entry จะชี้ไปยัง git URL แทน relative path ดังนั้น plugin จะไม่ถูกติดตั้งจาก settings ของ repository เพียงอย่างเดียว Teammate แต่ละคนต้องเรียกใช้ claude plugin install team-skills@acme-agents --scope project 1 ครั้ง และก่อนดำเนินการดังกล่าว Claude Code จะแจ้งว่า plugin ถูกเปิดใช้งานใน project settings แล้ว แต่ยังไม่ได้ติดตั้ง หลังจากติดตั้งแล้ว skills จะเรียกใช้ผ่าน /team-skills:api-review เนื่องจาก plugin skills ใช้ namespace ตามชื่อ plugin และไม่ชนกับ project skill ที่มีชื่อเดียวกัน เมื่อ push tag ใหม่และอัปเดต pin ใน catalog และ repository ที่ใช้งานแล้ว ให้ผู้ใช้เรียก /plugin marketplace update acme-agents เพื่อ refresh จากนั้นเรียก /reload-plugins หาก install summary แจ้งให้ดำเนินการ

การเขียน smoke test สำหรับ skill หนึ่งรายการ

smoke test คือการเรียกใช้ agent ตามสคริปต์กับ fixture ที่มีข้อผิดพลาดซึ่งทราบอยู่แล้ว พร้อม assertion 1 รายการ Claude Code ทำงานแบบไม่โต้ตอบด้วย -p และ skill ที่ผู้ใช้เรียกใช้ก็ทำงานในโหมดนี้ได้ โดยใส่ /skill-name ในสตริง prompt ระบบจะขยายค่าให้ก่อนเริ่มการทำงาน

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md เป็นไฟล์สั้นที่มีข้อผิดพลาดที่ตั้งใจใส่ไว้ 1 รายการ assertion คือ skill ต้องระบุข้อผิดพลาดนั้น jq -e จะจบการทำงานด้วยสถานะไม่ใช่ 0 เมื่อ filter ให้ผลเป็น null ดังนั้น หาก skill หยุดตรวจพบข้อผิดพลาดที่ใส่ไว้ สคริปต์จะล้มเหลว claude จะจบการทำงานด้วยสถานะไม่ใช่ 0 เมื่อการเรียกใช้ล้มเหลว และ set -euo pipefail จะเปลี่ยนความล้มเหลวอย่างใดอย่างหนึ่งให้เป็น test ที่ล้มเหลว

โมเดลอาจเรียบเรียงคำตอบใหม่ในแต่ละรอบ ดังนั้นอย่า assert กับประโยคทั้งประโยค ให้ assert กับ identifier ที่ skill ควรส่งออก หรือ field ของ schema ที่คุณระบุให้ใช้ และทำ fixture ให้มีขนาดเล็ก เพื่อให้การเรียกใช้ใช้ทรัพยากรน้อย

ใน CI ให้เพิ่ม --bare หากไม่มีตัวเลือกนี้ claude -p จะโหลด context เดียวกับที่ session แบบโต้ตอบใช้ รวมถึง hooks, plugins และ CLAUDE.md จากเครื่องที่ใช้รัน ดังนั้น configuration ส่วนตัวของสมาชิกในทีมอาจเปลี่ยนผลลัพธ์ได้ โหมด bare จะข้ามการค้นหาอัตโนมัติ ยกเว้น skill ใน .claude/skills/ ภายใต้ directory ที่ระบุอย่างชัดเจนด้วย --add-dir โหมดนี้จึงข้าม project skill ที่กำลังทดสอบอยู่ ให้โหลด skill ดังกล่าวอย่างชัดเจน โหมด bare จะไม่อ่านข้อมูลเข้าสู่ระบบ subscription ของคุณด้วย ดังนั้นให้ตั้งค่า ANTHROPIC_API_KEY ใน environment ก่อน:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

plugin ที่โหลดด้วย --plugin-dir จะใช้ชื่อจาก .claude-plugin/plugin.json และหากไม่มี manifest ดังกล่าว ระบบจะตั้งชื่อตาม directory ของ plugin ให้ commit plugin.json ที่มี "name": "team-skills" ไว้ถัดจาก catalog ใน skills repository มิฉะนั้น command ข้างต้นต้องเรียกใช้ /agent-skills:api-review แทน

เมื่อใช้ --output-format stream-json event system/init จะแสดงว่า plugin ใดถูกโหลด และมี array plugin_errors สำหรับ plugin ที่โหลดไม่สำเร็จ ระบบจะเปิด stream นี้ เว้นแต่ startup events จะมาก่อน ให้ CI job ล้มเหลวเมื่อ plugin_errors ไม่ว่าง วิธีนี้จะตรวจจับกรณี pin ชี้ไปยัง revision ที่ไม่มีอยู่อีกต่อไป ซึ่งหากไม่ตรวจจับ อาจดูเหมือน agent เพิกเฉยต่อกฎขององค์กรโดยไม่มีข้อความแจ้งเตือน

ทักษะที่ใช้ร่วมกันคือคำสั่งที่เรียกใช้งานได้

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

ประการแรก SKILL.md สามารถเรียกใช้ shell command ก่อนที่โมเดลจะอ่านข้อมูลใด ๆ บรรทัดลักษณะนี้ในเนื้อหาคือการประมวลผลล่วงหน้า:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

คำสั่งจะทำงานบนเครื่องที่โหลดทักษะ และผลลัพธ์จะแทนที่ placeholder ในข้อความที่โมเดลได้รับ fenced block ที่เปิดด้วย backticks 3 ตัวตามด้วย ! จะเรียกใช้หลายคำสั่งในลักษณะเดียวกัน ระบบจะไม่ขอการยืนยันสำหรับการทำงานเหล่านี้ระหว่างรันไทม์ Claude Code จะตรวจสอบแต่ละคำสั่งตาม permission rules ของคุณ นอก auto mode หากกฎเหล่านั้นไม่อนุญาตคำสั่ง ระบบจะยุติการทำงานของทักษะ เว้นแต่ทักษะจะอนุมัติคำสั่งนั้นไว้ล่วงหน้าผ่านคุณสมบัติที่สองด้านล่าง กฎ deny และ ask ยังคงมีผลเหนือการอนุมัติล่วงหน้านั้น การอ่านทักษะที่ใช้ร่วมกันจึงเท่ากับการอ่าน command substitutions ของทักษะด้วย

ประการที่สอง frontmatter สามารถอนุมัติ tools ไว้ล่วงหน้าได้ allowed-tools จะให้สิทธิ์ tools ที่ระบุโดยไม่แสดง permission prompt สำหรับ turn ที่เรียกใช้ทักษะ Workspace trust ไม่ได้ควบคุมการให้สิทธิ์นี้: Claude Code จะใช้ allowed-tools ของ project skill แม้ใน -p run ที่ทำงานอยู่ในโฟลเดอร์ซึ่งยังไม่มีใคร trust เอกสารของ Claude Code ระบุผลกระทบไว้อย่างชัดเจน: ทักษะสามารถให้สิทธิ์เข้าถึง tools ในขอบเขตกว้างแก่ตัวเองได้ ดังนั้นให้ตรวจสอบ allowed-tools ของทักษะที่อยู่ใน repository ก่อนเรียกใช้ Claude Code ที่นั่น องค์กรสามารถไม่อนุญาตให้ project skill และ personal skill ใช้ field นี้ได้ โดยตั้งค่า allowManagedPermissionRulesOnly ใน managed settings ซึ่งต้องใช้ Claude Code v2.1.282 หรือใหม่กว่า

ดังนั้นให้จัดการการอัปเดตทักษะเช่นเดียวกับการอัปเดต dependency ให้ระบุด้วย exact commit ทุกจุดที่กลไกรองรับ เพราะ tag สามารถถูกย้ายได้ และ branch จะเปลี่ยนตามคำจำกัดความอยู่แล้ว บนเครื่องที่จำกัดสิทธิ์ "disableSkillShellExecution": true ใน settings จะแทนที่ command substitution ทุกตัวด้วยข้อความตามตัวอักษร [shell command execution disabled by policy] แทนการเรียกใช้ และหากตั้งค่าผ่าน managed settings ผู้ใช้จะ override ไม่ได้ Bundled skill และ managed skill ไม่อยู่ภายใต้การตั้งค่านี้

ควรใช้ความระมัดระวังเช่นเดียวกันกับข้อมูลที่ทักษะอ่าน ทักษะที่เรียกใช้ env หรือเปิดไฟล์ config จะนำทุกอย่างที่พบเข้าไปใน context ของโมเดล ซึ่งเป็น failure ที่กล่าวถึงใน การเก็บ secret ให้พ้นจาก agent ที่คุณเรียกใช้ ทักษะที่ดึงหน้าเว็บหรือเรียกใช้ query ก่อให้เกิดการเปิดเผยข้อมูลในลักษณะเดียวกัน แต่ชี้ออกไปภายนอก เนื่องจากข้อความที่ดึงมาจะอยู่ใน context และมีลักษณะเหมือนคำสั่งที่คุณเขียนทุกประการ นี่คือขอบเขตที่ควรทำความเข้าใจก่อนที่คุณจะ ชี้ agent ไปยัง SearXNG instance ของคุณเองเพื่อค้นหาเว็บ

สิ่งที่ควรตรวจสอบเมื่อมีการปรับเวอร์ชัน

  • ผลต่าง (diff) ของเนื้อหาใน SKILL.md ทุกส่วน เนื่องจากข้อความดังกล่าวคือคำสั่งที่เอเจนต์ของคุณจะปฏิบัติตาม
  • การแทนที่คำสั่ง (command substitution) ทุกรายการ เนื่องจากคำสั่งเหล่านี้จะทำงานบนเครื่องของคุณเมื่อโหลดทักษะ (skill) นั้น
  • การเปลี่ยนแปลงใดๆ ใน allowed-tools เนื่องจากบรรทัดดังกล่าวเป็นการให้สิทธิ์การเข้าถึงเครื่องมือโดยไม่ต้องแจ้งเตือน
  • การทดสอบที่อยู่เบื้องหลังแท็ก หาก repository ที่ใช้ร่วมกันมีการรัน smoke test ใน CI แท็กที่คุณอ้างอิงถึงควรมีสถานะการรันที่ผ่าน (green run)

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

เมื่อการเปลี่ยนแปลงของโมเดลหรือเครื่องมือทำให้ทักษะใช้งานไม่ได้

มีหลายสิ่งที่เปลี่ยนแปลงไปภายใต้ทักษะโดยที่ไม่มีใครเข้าไปแก้ไข การอัปเกรดโมเดลส่งผลต่อความน่าเชื่อถือในการปฏิบัติตามคำสั่งที่ยาวเหยียด ดังนั้นทักษะที่เคยพึ่งพาการที่โมเดลทำงานไปจนถึงขั้นตอนที่ 9 อาจหยุดทำงานก่อนถึงขั้นนั้น เครื่องมือบรรทัดคำสั่ง (command line tool) เปลี่ยนชื่อ flag ทำให้เอเจนต์รันด้วย flag เก่า อ่านข้อผิดพลาดที่เกิดขึ้น แล้วพยายามแก้ไขปัญหาเฉพาะหน้า URL ที่อ้างอิงเริ่มส่งค่า 404 กลับมา หรือตัวควบคุมเอเจนต์ (agent harness) เปลี่ยนวิธีการเลือกทักษะ ทำให้ description ที่เคยถูกเลือกใช้งานกลับไม่ถูกเลือกอีกต่อไป เมื่อกระบวนการเริ่มจบลงก่อนกำหนดเช่นนี้ การปรับเวอร์ชัน (version bump) ไม่สามารถแก้ไขปัญหาได้ และตัวคำสั่งเองจำเป็นต้องมีโครงสร้างที่บังคับให้ทำขั้นตอนสุดท้ายให้สำเร็จ ซึ่งเป็นแนวทางเบื้องหลัง ทักษะที่ไม่ขี้เกียจและวิธี Depth Tree

นี่คือเหตุผลที่การทดสอบแบบ smoke test มีความสำคัญอย่างยิ่งในระบบนี้ ให้รันการทดสอบของแต่ละทักษะตามตารางเวลาและทุกครั้งที่มีการ push โค้ด Google รันงานประเมินผลรายสัปดาห์กับไลบรารีทั้งหมดด้วยเหตุผลนี้ และการตั้ง cron job รายสัปดาห์บน VPS ขนาดเล็กก็เพียงพอสำหรับทีมที่มีทักษะประมาณ 10 รายการ นี่เป็นวิธีเดียวที่คุณจะทราบถึงปัญหาที่เกิดขึ้นก่อนที่นักพัฒนาจะพบเอง

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

FAQ

ฉันจะแชร์ทักษะของ agent เดียวกันในหลาย repository ได้อย่างไร

ใส่ทักษะไว้ใน git repository เฉพาะ ติด tag ให้กับ release และให้แต่ละโปรเจกต์ที่ใช้อ้างอิง tag แทนการคัดลอกไฟล์ มีกลไกที่ใช้ได้ 2 แบบ git submodule จะบันทึก commit ที่แน่นอน และ symlink จาก .claude/skills/<name> ไปยัง submodule จะทำให้ระบบโหลดทักษะนั้นเหมือนเป็นทักษะปกติของโปรเจกต์ ส่วน plugin marketplace ทำงานแบบเดียวกันผ่าน /plugin โดยประกาศ pin ไว้ใน .claude/settings.json ของ repository ที่ใช้งาน ทั้ง 2 แบบทำให้ version อยู่ใน git history คุณจึงตรวจสอบได้ว่าคำสั่งใดเป็นต้นเหตุของการทำงานครั้งหนึ่งของ agent

ฉันจะ pin ทักษะของ agent ให้ใช้ version ที่ระบุได้หรือไม่

ไม่สามารถทำจากภายใน SKILL.md ได้ เพราะ frontmatter นี้ไม่มี key version การ pin ต้องกำหนดจาก layer ที่อยู่รอบไฟล์ git submodule จะ pin commit ที่แน่นอนได้โดยการออกแบบ ใน Claude Code plugin marketplace แหล่งที่มาของ plugin รองรับ ref สำหรับ branch หรือ tag และ sha สำหรับ commit ที่แน่นอน โดย sha จะมีผลเหนือกว่าเมื่อกำหนดทั้ง 2 ค่า ส่วนแหล่งที่มาของ marketplace เองรองรับ ref สำหรับ branch, tag หรือ full lowercase commit SHA ใน Claude Code v2.1.324 หรือใหม่กว่า ควรใช้ commit pin เพราะ tag อาจถูกย้ายหลังจากที่คุณตรวจสอบแล้ว

การทดสอบ smoke test ของทักษะควรตรวจสอบอะไร

ให้ตรวจสอบสิ่งที่มีความคงที่ รันทักษะแบบไม่โต้ตอบกับ fixture ที่มีข้อผิดพลาดที่ทราบอยู่แล้ว จากนั้นตรวจว่ามี identifier เฉพาะปรากฏใน output เช่น rule id ที่ทักษะควรรายงาน การขอ structured output ด้วย --output-format json และ --json-schema ทำให้ตรวจสอบได้อย่างชัดเจน และ jq -e จะทำให้สคริปต์ล้มเหลวเมื่อไม่มีค่า อย่าตรวจสอบจากประโยคเต็ม เพราะ model อาจเรียบเรียงคำตอบใหม่ในแต่ละครั้งที่รัน

การติดตั้งทักษะที่แชร์จาก repository ของทีมอื่นปลอดภัยหรือไม่

ให้ถือว่าเป็น code dependency เพราะเป็นคำสั่งที่เรียกใช้งานได้ SKILL.md สามารถรัน shell commands ขณะโหลดผ่านรูปแบบ command substitution ของคำสั่ง ! และ field allowed-tools ใน frontmatter สามารถอนุมัติ tools ล่วงหน้าโดยไม่ต้องแสดง prompt อ่าน diff ทุกครั้งที่มีการอัปเดต pin ไปยัง commit ที่แน่นอนแทน branch และเลือก source ที่ทีมของคุณควบคุมเอง หากเป็นเครื่องที่มีการจัดการ "disableSkillShellExecution": true ใน settings จะหยุดไม่ให้ command substitutions ใน user, project, plugin และ additional-directory skills ทำงาน ส่วน bundled และ managed skills จะได้รับการยกเว้น

ทักษะที่แชร์จะทำงานกับ agent อื่นที่ไม่ใช่ Claude Code หรือไม่

ขึ้นอยู่กับ frontmatter ที่ใช้ Agent Skills spec กำหนด 6 keys ได้แก่ name, description, license, compatibility, metadata และ allowed-tools ทักษะที่จำกัดอยู่เฉพาะ keys เหล่านี้จะโหลดได้ใน tools ที่รองรับ spec และยังโหลดใน Claude Code ได้โดยไม่ต้องแก้ไข ส่วน keys และ body features เฉพาะของ harness ที่อยู่นอกเหนือ spec จะถูกละเว้นหรือถูกปฏิเสธในระบบอื่น ดังนั้นควรไม่นำมาใช้ในทักษะที่ตั้งใจจะแชร์อย่างกว้างขวาง

บทความนี้มีประโยชน์หรือไม่

#agent-skills#versioning#claude-code#team-standards#self-hosting