Format keterampilan

Di disk

Keterampilan adalah sebuah folder.

Wajib:

• SKILL.md (atau skill.md; skills.md lama juga diterima)

Opsional:

• semua file reguler pendukung (lihat “File keterampilan”)
• .clawhubignore (pola pengabaian untuk penerbitan, .clawdhubignore lama)
• .gitignore (juga dipatuhi)

Impor GitHub

Pengimpor GitHub berbasis web lebih ketat daripada penerbitan/sinkronisasi lokal. Pengimpor ini hanya menemukan file SKILL.md atau skills.md lama di repositori publik non-fork yang dimiliki oleh akun GitHub yang sedang masuk. Pengimpor ini tidak mengimpor repositori privat, fork, repositori yang diarsipkan/dinonaktifkan, atau repositori publik pihak ketiga.

Metadata instalasi lokal (ditulis oleh CLI):

• <skill>/.clawhub/origin.json (.clawdhub lama)

Status instalasi direktori kerja (ditulis oleh CLI):

• <workdir>/.clawhub/lock.json (.clawdhub lama)

SKILL.md

• Markdown dengan frontmatter YAML opsional.
• Server mengekstrak metadata dari frontmatter selama penerbitan.
• description digunakan sebagai ringkasan keterampilan di UI/pencarian.

Untuk Agent Skills portabel, name harus cocok dengan direktori induk dan menggunakan 1–64 huruf kecil, angka, atau tanda hubung. ClawHub memisahkan slug yang dapat dirutekan dan nama tampilan katalog, sehingga nama yang sudah ada dari klien lain tetap dapat diterbitkan dan tidak ditulis ulang secara diam-diam. Daftar katalog dapat memendekkan nama panjang secara visual tanpa mengubah nama yang disimpan.

Metadata frontmatter

Metadata keterampilan dideklarasikan dalam frontmatter YAML di bagian atas SKILL.md. Metadata ini memberi tahu registri (dan analisis keamanan) apa yang diperlukan keterampilan Anda agar dapat berjalan.

Frontmatter dasar

---name: my-skilldescription: Ringkasan singkat tentang fungsi keterampilan ini.version: 1.0.0---

Metadata runtime (metadata.openclaw)

Deklarasikan persyaratan runtime keterampilan Anda di bawah metadata.openclaw (alias: metadata.clawdbot, metadata.clawdis).

---name: my-skilldescription: Kelola tugas melalui API Todoist.metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY---

Gunakan requires.env untuk variabel lingkungan yang harus tersedia sebelum keterampilan dapat berjalan. Gunakan envVars jika Anda memerlukan metadata per variabel, termasuk variabel opsional dengan required: false.

Referensi lengkap bidang

Spesifikasi instalasi

Jika keterampilan Anda memerlukan dependensi yang harus diinstal, deklarasikan dependensi tersebut dalam larik install:

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

Jenis instalasi yang didukung: brew, node, go, uv.

Variabel lingkungan opsional

Deklarasikan variabel lingkungan opsional di bawah metadata.openclaw.envVars dan tetapkan required: false. Jangan tambahkan entri opsional ke requires.env, karena requires.env berarti keterampilan tidak dapat berjalan tanpanya.

metadata:  openclaw:    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: Token API Todoist yang digunakan untuk permintaan terautentikasi.      - name: TODOIST_PROJECT_ID        required: false        description: ID proyek default opsional ketika pengguna tidak menentukannya.

Mengapa hal ini penting

Analisis keamanan ClawHub memeriksa apakah yang dideklarasikan keterampilan Anda sesuai dengan yang benar-benar dilakukannya. Jika kode Anda merujuk TODOIST_API_KEY tetapi frontmatter Anda tidak mendeklarasikannya di bawah requires.env, primaryEnv, atau envVars, analisis akan menandai ketidakcocokan metadata. Menjaga deklarasi tetap akurat membantu keterampilan Anda lolos review dan membantu pengguna memahami apa yang mereka instal.

Contoh: frontmatter lengkap

---name: todoist-clidescription: Kelola tugas, proyek, dan label Todoist dari baris perintah.version: 1.2.0metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: Token API Todoist.      - name: TODOIST_PROJECT_ID        required: false        description: ID proyek default opsional.    emoji: "\u2705"    homepage: https://github.com/example/todoist-cli---

File keterampilan

Penerbitan menerima semua file reguler dalam folder keterampilan, apa pun ekstensinya. File yang diabaikan, jalur tersembunyi, symlink, metadata macOS, dan batas ukuran sisi server tetap berlaku.

• File berukuran terbatas yang berisi UTF-8 valid dapat dipratinjau sebagai teks biasa yang di-escape dan disertakan dalam analisis teks terbatas.
• File lain mempertahankan byte persisnya dan tersedia untuk diunduh.
• Pemindai keamanan menerima artefak lengkap yang disimpan; deteksi teks merupakan persoalan rendering dan analisis, bukan daftar yang diizinkan untuk unggahan.

Batas (sisi server):

• Ukuran total bundel: 50MB.
• Teks penyematan mencakup SKILL.md + hingga sekitar 40 file UTF-8 berukuran terbatas (batas upaya terbaik).

Slug

• Secara default diturunkan dari nama folder.
• Cakupan paket harus sama persis dengan handle penerbit ClawHub. Handle penerbit dapat menggunakan huruf kecil, angka, tanda hubung, titik, dan garis bawah; handle harus diawali dan diakhiri dengan huruf kecil atau angka.
• Slug paket harus menggunakan huruf kecil dan aman untuk npm, misalnya @example.tools/demo-plugin atau demo-plugin.

Pembuatan versi + tag

• Setiap penerbitan membuat versi baru (semver).
• Tag adalah penunjuk string ke suatu versi; latest umum digunakan.

Lisensi

• Semua keterampilan yang diterbitkan di ClawHub dilisensikan berdasarkan MIT-0.
• Siapa pun dapat menggunakan, memodifikasi, dan mendistribusikan ulang keterampilan yang diterbitkan, termasuk secara komersial.
• Atribusi tidak diwajibkan.
• Jangan tambahkan ketentuan lisensi yang bertentangan dalam SKILL.md; ClawHub tidak mendukung penggantian lisensi per keterampilan.

Keterampilan berbayar

• ClawHub tidak mendukung keterampilan berbayar, penetapan harga per keterampilan, paywall, atau bagi hasil.
• Jangan tambahkan metadata harga ke SKILL.md; metadata tersebut bukan bagian dari format keterampilan dan tidak akan membuat keterampilan yang diterbitkan menjadi berbayar.
• Jika keterampilan Anda terintegrasi dengan layanan pihak ketiga berbayar, dokumentasikan biaya eksternal dan akun yang diperlukan dengan jelas dalam petunjuk keterampilan dan deklarasi lingkungan (requires.env untuk variabel wajib, atau envVars dengan required: false untuk variabel opsional).