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

Agent Plugins จึงเข้ามาแก้ปัญหานี้ โดยเป็นมาตรฐานเปิดที่ไม่ได้อยู่ใต้การควบคุมของค่ายใดค่ายหนึ่ง ตอนนี้มาตรฐานออกเวอร์ชัน 1.0.0 แล้ว เวอร์ชันนี้กำหนดรูปแบบโฟลเดอร์กลางสำหรับรวมของเสริมของ AI agent ไว้ในปลั๊กอินเดียว ทั้งสกิลและ MCP server เครื่องมือหลายตัวจึงอ่านและโหลดปลั๊กอินนี้ด้วยวิธีเดียวกันได้

ปัญหาที่มาตรฐานนี้เข้าไปจับ

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

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

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

หนึ่งปลั๊กอินคือหนึ่งโฟลเดอร์

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

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json
└── com.example.client/
    └── hooks/

• plugin.json เป็นไฟล์บังคับที่ระบุชื่อปลั๊กอินและเวอร์ชันของมาตรฐาน Agent Plugins ที่ปลั๊กอินใช้
• skills/ ใช้เก็บสกิลตามรูปแบบที่สเปกของ Agent Skills กำหนด Agent Skills เป็นสเปกอีกฉบับและมีผู้ดูแลแยกกัน
• mcp.json ระบุว่าปลั๊กอินเชื่อมต่อกับ MCP server ตัวไหนและเชื่อมต่อด้วยวิธีใด ระบบรองรับสามแบบ คือ stdio · Streamable HTTP · HTTP+SSE แบบเดิม ส่วนวิธีทำงานของ MCP อยู่ในสเปกของ MCP อีกฉบับ
• โฟลเดอร์ที่ใช้ชื่อโดเมนแบบย้อนลำดับ เช่น com.example.client/ เป็นที่เก็บส่วนเสริมเฉพาะของเครื่องมือแต่ละตัว เช่น hooks/ เครื่องมือจึงเพิ่มส่วนของตัวเองได้โดยไม่ต้องแก้ส่วนกลางที่ทุกตัวใช้ร่วมกัน

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

ข้างในสกิลหนึ่งตัว มีกติกาไม่กี่ข้อ

สกิลหนึ่งตัวต้องมีโฟลเดอร์ที่ใส่ไฟล์ SKILL.md ไว้อย่างน้อยหนึ่งไฟล์ ในโฟลเดอร์เดียวกันจะมี scripts/ references/ และ assets/ เพิ่มด้วยก็ได้ ไฟล์ SKILL.md แบ่งเป็นสองส่วน โดยส่วนหัวเขียนด้วย YAML และส่วนเนื้อหาเขียนด้วย Markdown

ส่วนหัวบังคับให้ใส่เพียงสองช่อง ส่วนช่องอื่นใส่เมื่อจำเป็น

ชื่อ pdf-processing data-analysis และ code-review ใช้ในช่อง name ได้ ส่วน PDF-Processing ใช้ไม่ได้เพราะมีตัวพิมพ์ใหญ่ -pdf ใช้ไม่ได้เพราะขึ้นต้นด้วยขีด และ pdf--processing ใช้ไม่ได้เพราะมีขีดติดกันสองตัว

ข้อมูลในช่อง description ช่วยให้ agent เลือกใช้สกิลได้ตรงกับงาน สเปกยกตัวอย่างที่เขียนรายละเอียดไว้ดังนี้

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

ส่วน description: Helps with PDFs. เป็นตัวอย่างที่สเปกระบุว่ายังไม่ดีพอ เพราะบอกเพียงว่าสกิลเกี่ยวกับอะไร แต่ไม่ได้บอกว่าควรใช้สกิลนี้เมื่อไร

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

ทำไมสเปกถึงขอให้เขียนสั้น

เมื่อเปิดเครื่องมือ ระบบจะอ่านเฉพาะชื่อและคำอธิบายของทุกสกิลก่อน ขั้นตอนนี้ใช้พื้นที่ราวหนึ่งร้อยโทเคนต่อสกิลหนึ่งตัว ระบบจะโหลดเนื้อหาใน SKILL.md เมื่อเริ่มใช้สกิลนั้นจริง ส่วนไฟล์ใน scripts/ references/ และ assets/ จะโหลดเมื่อมีการเรียกใช้ไฟล์นั้นเท่านั้น

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

เมื่อเขียนเสร็จแล้ว เราใช้ไลบรารีอ้างอิงชื่อ skills-ref ตรวจได้ว่าส่วนหัวทำตามกติกาหรือไม่ เมื่อสั่ง skills-ref validate ./my-skill ไลบรารีจะตรวจทั้งช่องในส่วนหัวและกติกาการตั้งชื่อ

ปลั๊กอินที่ใช้ได้จริง เริ่มที่สองไฟล์

คลังสเปกบน GitHub มีตัวอย่างปลั๊กอินแบบเล็กที่สุดที่ใช้งานได้จริง โดยมีเพียงสองไฟล์

hello-plugin/
├── plugin.json
└── skills/
    └── greet/
        └── SKILL.md

ไฟล์แรกคือ plugin.json ซึ่งอยู่ในโฟลเดอร์หลัก และมีเนื้อหาดังนี้

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

ไฟล์ที่สองคือ skills/greet/SKILL.md ส่วนหัวของไฟล์นี้มีสองช่องบังคับ แล้วจึงตามด้วยเนื้อหา

---
name: greet
description: Greet the user and offer help.
---
Greet the user and offer help.

ชื่อในช่อง name ตรงกับชื่อโฟลเดอร์ greet ซึ่งเป็นที่อยู่ของไฟล์นี้ ข้อมูลทั้งสองส่วนจึงทำตามกติกาข้างต้น

ถ้ามีสกิลอยู่ในเครื่องแล้ว ให้สร้างโฟลเดอร์ใหม่หนึ่งโฟลเดอร์ แล้ววาง plugin.json ไว้ในโฟลเดอร์หลัก จากนั้นย้ายสกิลเดิมไปไว้ที่ skills/<ชื่อสกิล>/SKILL.md และแก้ชื่อในช่อง name ให้ตรงกับชื่อโฟลเดอร์ หากมี MCP server ที่ใช้ร่วมกัน จะเพิ่ม mcp.json ภายหลังก็ได้

สิ่งที่มาตรฐานนี้จงใจไม่ตกลง

เราต้องรู้ข้อจำกัดนี้ตั้งแต่ต้น เพื่อจะได้ไม่คาดหวังสิ่งที่มาตรฐานไม่ได้ทำ

มาตรฐานรับประกันเพียงว่า เราไม่ต้องจัดไฟล์ในปลั๊กอินใหม่เมื่อเปลี่ยนเครื่องมือ แต่ไม่ได้รับประกันว่าจะติดตั้งปลั๊กอินได้ทุกที่ด้วยการกดปุ่มเพียงครั้งเดียว เครื่องมือแต่ละตัวมีวิธีติดตั้งของตัวเอง หากต้องการติดตั้งปลั๊กอินกับเครื่องมือตัวไหน ต้องอ่านวิธีติดตั้งของเครื่องมือตัวนั้น เพราะมาตรฐานไม่ได้กำหนดขั้นตอนนี้ไว้

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

ใครนั่งอยู่ในวงที่ตกลงกัน

Agent Plugins เปิดสัญญาอนุญาตของมาตรฐานให้คนทั่วไปนำไปใช้ได้ และพัฒนามาตรฐานในพื้นที่ที่ทุกคนเข้าดูได้ คณะกรรมการกำกับทางเทคนิคชุดแรกมีผู้ดูแลหลักจาก Amazon · Cursor · Microsoft · OpenAI · Vercel จึงมีคนจากหลายค่ายร่วมดูแลมาตรฐานเปิดนี้ตั้งแต่ต้น

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

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

ที่มา:

• เอกสารทางการของ Agent Plugins
• โปรเจกต์ agent-plugins-spec บน GitHub
• เอกสารทางการของ Agent Skills