รูปแบบ Skill

บนดิสก์

Skill คือโฟลเดอร์

จำเป็น:

• SKILL.md (หรือ skill.md; รองรับ skills.md แบบเดิมด้วย)

ไม่บังคับ:

• ไฟล์ปกติที่ใช้สนับสนุน (ดู “ไฟล์ Skill”)
• .clawhubignore (รูปแบบการละเว้นสำหรับการเผยแพร่, แบบเดิมคือ .clawdhubignore)
• .gitignore (รองรับด้วยเช่นกัน)

การนำเข้าจาก GitHub

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

ข้อมูลเมตาการติดตั้งในเครื่อง (เขียนโดย CLI):

• <skill>/.clawhub/origin.json (แบบเดิมคือ .clawdhub)

สถานะการติดตั้งในไดเรกทอรีทำงาน (เขียนโดย CLI):

• <workdir>/.clawhub/lock.json (แบบเดิมคือ .clawdhub)

SKILL.md

• Markdown พร้อม YAML frontmatter ที่ไม่บังคับ
• เซิร์ฟเวอร์ดึงข้อมูลเมตาจาก frontmatter ระหว่างการเผยแพร่
• ใช้ description เป็นข้อมูลสรุป Skill ใน UI/การค้นหา

สำหรับ Agent Skills ที่นำไปใช้ได้ในหลายระบบ name ควรตรงกับไดเรกทอรีแม่และใช้ ตัวอักษรพิมพ์เล็ก ตัวเลข หรือยัติภังค์จำนวน 1–64 ตัว ClawHub แยก slug ที่ใช้กำหนดเส้นทางออกจาก ชื่อที่แสดงในแค็ตตาล็อก ดังนั้นชื่อเดิมจากไคลเอนต์อื่นจึงยังเผยแพร่ได้ และจะไม่ถูกเขียนใหม่โดยอัตโนมัติ รายการแค็ตตาล็อกอาจย่อชื่อที่ยาว ในการแสดงผลโดยไม่เปลี่ยนชื่อที่จัดเก็บไว้

ข้อมูลเมตา Frontmatter

ประกาศข้อมูลเมตาของ Skill ใน YAML frontmatter ที่ด้านบนของ SKILL.md ซึ่งบอกรีจิสทรี (และการวิเคราะห์ความปลอดภัย) ว่า Skill ต้องการสิ่งใดในการทำงาน

Frontmatter พื้นฐาน

---name: my-skilldescription: สรุปสั้น ๆ ว่า Skill นี้ทำอะไรversion: 1.0.0---

ข้อมูลเมตารันไทม์ (metadata.openclaw)

ประกาศข้อกำหนดรันไทม์ของ Skill ภายใต้ metadata.openclaw (นามแฝง: metadata.clawdbot, metadata.clawdis)

---name: my-skilldescription: จัดการงานผ่าน Todoist APImetadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY---

ใช้ requires.env สำหรับตัวแปรสภาพแวดล้อมที่ต้องมีอยู่ก่อน Skill จะทำงานได้ ใช้ envVars เมื่อต้องการข้อมูลเมตาแยกตามตัวแปร รวมถึงตัวแปรที่ไม่บังคับด้วย required: false

การอ้างอิงฟิลด์ทั้งหมด

ข้อกำหนดการติดตั้ง

หาก Skill ต้องติดตั้งการขึ้นต่อกัน ให้ประกาศในอาร์เรย์ install:

metadata:  openclaw:    install:      - kind: brew        formula: jq        bins: [jq]      - kind: node        package: typescript        bins: [tsc]

ชนิดการติดตั้งที่รองรับ: brew, node, go, uv

ตัวแปรสภาพแวดล้อมที่ไม่บังคับ

ประกาศตัวแปรสภาพแวดล้อมที่ไม่บังคับภายใต้ metadata.openclaw.envVars และตั้งค่า required: false อย่าเพิ่มรายการที่ไม่บังคับลงใน requires.env เนื่องจาก requires.env หมายความว่า Skill ไม่สามารถทำงานได้หากไม่มีตัวแปรเหล่านั้น

metadata:  openclaw:    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: โทเค็น Todoist API ที่ใช้สำหรับคำขอที่ผ่านการยืนยันตัวตน      - name: TODOIST_PROJECT_ID        required: false        description: ID โปรเจกต์เริ่มต้นที่ไม่บังคับ เมื่อผู้ใช้ไม่ได้ระบุ

เหตุผลที่เรื่องนี้สำคัญ

การวิเคราะห์ความปลอดภัยของ ClawHub จะตรวจสอบว่าสิ่งที่ Skill ประกาศตรงกับสิ่งที่ทำจริงหรือไม่ หากโค้ดอ้างอิง TODOIST_API_KEY แต่ frontmatter ไม่ได้ประกาศไว้ภายใต้ requires.env, primaryEnv หรือ envVars การวิเคราะห์จะระบุว่าข้อมูลเมตาไม่ตรงกัน การรักษาความถูกต้องของการประกาศช่วยให้ Skill ผ่านการรีวิวและช่วยให้ผู้ใช้เข้าใจว่ากำลังติดตั้งอะไร

ตัวอย่าง: frontmatter ฉบับสมบูรณ์

---name: todoist-clidescription: จัดการงาน โปรเจกต์ และป้ายกำกับของ Todoist จากบรรทัดคำสั่งversion: 1.2.0metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: โทเค็น Todoist API      - name: TODOIST_PROJECT_ID        required: false        description: ID โปรเจกต์เริ่มต้นที่ไม่บังคับ    emoji: "\u2705"    homepage: https://github.com/example/todoist-cli---

ไฟล์ Skill

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

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

ขีดจำกัด (ฝั่งเซิร์ฟเวอร์):

• ขนาดบันเดิลรวม: 50MB
• ข้อความสำหรับ embedding รวม SKILL.md + ไฟล์ UTF-8 ที่มีขนาดอยู่ภายในขอบเขตสูงสุดประมาณ 40 ไฟล์ (ขีดจำกัดแบบพยายามให้ดีที่สุด)

Slug

• โดยค่าเริ่มต้น สร้างจากชื่อโฟลเดอร์
• ขอบเขตแพ็กเกจต้องตรงกับแฮนเดิลผู้เผยแพร่ ClawHub ทุกประการ แฮนเดิลผู้เผยแพร่ใช้ตัวอักษรพิมพ์เล็ก ตัวเลข ยัติภังค์ จุด และขีดล่างได้ โดยต้องเริ่มต้นและลงท้ายด้วยตัวอักษรพิมพ์เล็กหรือตัวเลข
• Slug ของแพ็กเกจต้องเป็นตัวพิมพ์เล็กและปลอดภัยสำหรับ npm เช่น @example.tools/demo-plugin หรือ demo-plugin

การกำหนดเวอร์ชัน + แท็ก

• การเผยแพร่แต่ละครั้งจะสร้างเวอร์ชันใหม่ (semver)
• แท็กเป็นตัวชี้แบบสตริงไปยังเวอร์ชัน โดยนิยมใช้ latest

ใบอนุญาต

• Skill ทั้งหมดที่เผยแพร่บน ClawHub อยู่ภายใต้ใบอนุญาต MIT-0
• ทุกคนสามารถใช้ แก้ไข และเผยแพร่ Skill ที่เผยแพร่แล้วต่อได้ รวมถึงเพื่อการค้า
• ไม่จำเป็นต้องระบุที่มา
• อย่าเพิ่มข้อกำหนดใบอนุญาตที่ขัดแย้งกันใน SKILL.md; ClawHub ไม่รองรับการแทนที่ใบอนุญาตแยกตาม Skill

Skill แบบชำระเงิน

• ClawHub ไม่รองรับ Skill แบบชำระเงิน การกำหนดราคาแยกตาม Skill เพย์วอลล์ หรือการแบ่งรายได้
• อย่าเพิ่มข้อมูลเมตาการกำหนดราคาลงใน SKILL.md; ข้อมูลนี้ไม่ได้เป็นส่วนหนึ่งของรูปแบบ Skill และจะไม่ทำให้ Skill ที่เผยแพร่แล้วกลายเป็นแบบชำระเงิน
• หาก Skill ผสานรวมกับบริการแบบชำระเงินของบุคคลที่สาม ให้ระบุค่าใช้จ่ายภายนอกและบัญชีที่จำเป็นไว้อย่างชัดเจนในคำแนะนำของ Skill และการประกาศตัวแปรสภาพแวดล้อม (requires.env สำหรับตัวแปรที่จำเป็น หรือ envVars พร้อม required: false สำหรับตัวแปรที่ไม่บังคับ)