Validator SKILL.md untuk Agent Skills

SKILL.md adalah berkas instruksi standar terbuka berbasis spesifikasi Agent Skills yang dirancang agar model AI dan asisten pemrograman seperti Claude Code dapat mempelajari alur kerja khusus. Berkas ini disimpan di dalam direktori proyek dan memuat dua komponen utama, yaitu metadata konfigurasi pada bagian atas (YAML frontmatter) serta instruksi prosedural dalam format Markdown di bagian bawah.

Agen AI membaca metadata nama dan deskripsi pada saat inisialisasi lingkungan kerja untuk memetakan keahlian yang tersedia tanpa membebani jendela konteks. Ketika pengguna memasukkan perintah yang relevan, barulah agen memuat isi instruksi lengkap untuk mengeksekusi tugas. Menggunakan Validator SKILL.md membantu memastikan format berkas Anda bebas dari kesalahan sintaksis yang dapat membuat agen gagal memuat keahlian tersebut. Jika Anda mengelola konfigurasi data terstruktur dalam format lain, alat seperti konverter JSON ke YAML dapat mempermudah penyusunan struktur frontmatter sebelum ditempelkan ke dalam berkas.

Bagian frontmatter YAML wajib diletakkan di baris paling awal berkas dan diapit oleh sepasang pembatas tiga tanda hubung. Validator SKILL.md memeriksa setiap kunci metadata berdasarkan spesifikasi resmi agar tidak terjadi kegagalan pembacaan struktur data.

| Field | Status | Batasan dan Format | | name | Wajib | Maksimal 64 karakter, huruf kecil, angka, tanda hubung tunggal, wajib sama dengan nama folder | | description | Wajib | Maksimal 1.024 karakter, penjelasan fungsi dan pemicu aktivasi | | compatibility | Opsional | Maksimal 500 karakter, keterangan kompatibilitas lingkungan | | license | Opsional | Nama lisensi kode atau hak cipta alur kerja | | metadata | Opsional | Pasangan kunci dan nilai untuk konfigurasi kustom |

Pelanggaran aturan penamaan pada kunci name, seperti penggunaan huruf kapital, spasi, atau karakter simbol, akan langsung digolongkan sebagai error fatal. Apabila Anda membutuhkan validasi struktur data bertingkat di luar frontmatter dasar, Anda dapat memeriksa strukturnya melalui konverter YAML ke JSON guna memastikan format data telah tersusun secara benar.

Field description adalah komponen paling penting dalam menentukan apakah agen AI akan menjalankan keahlian yang Anda buat. Agen menyeleksi keahlian yang tepat dari daftar direktori hanya dengan membaca deskripsi singkat ini sebelum memutuskan untuk memuat keseluruhan isi berkas.

Deskripsi yang terlalu pendek atau ambigu sering kali menjadi penyebab utama keahlian diabaikan oleh agen AI. Spesifikasi menyarankan panjang deskripsi minimal 60 karakter dan tidak melebihi 1.024 karakter. Deskripsi yang efektif harus menjelaskan fungsi utama sekaligus skenario pemicu penggunaannya.

1. Pola deskripsi lemah: Membantu format skema database SQL.
2. Pola deskripsi ideal: Menjalankan migrasi skema PostgreSQL dan menganalisis indeks performa query. Gunakan keahlian ini saat pengguna meminta refaktor tabel, pembuatan index baru, atau optimasi query database yang lambat.

Validator SKILL.md akan menandai deskripsi di bawah 60 karakter dengan peringatan dan memberikan catatan jika tidak mendeteksi indikasi kalimat pemicu aktivasi.

Bagian body yang berada di bawah penutup frontmatter memuat panduan langkah demi langkah bagi agen AI. Karena ruang konteks model memiliki batas kapasitas komputasi, efisiensi ukuran berkas sangat krusial agar agen bekerja cepat dan hemat token.

Spesifikasi Agent Skills menyarankan panjang instruksi body tidak melebihi 500 baris atau sekitar 5.000 estimasi token. Validator SKILL.md menghitung estimasi tersebut menggunakan rasio pendekatan 4 karakter per token. Jika berkas Anda memerlukan dokumentasi API yang panjang atau contoh kode yang banyak, pisahkan detail tersebut ke dalam subdirektori references/.

Saat merujuk berkas pendukung, selalu gunakan tautan relatif satu tingkat dan hindari struktur folder bersarang yang terlalu dalam. Pastikan Anda juga menghapus teks draf atau penampung sementara seperti TODO dan lorem ipsum sebelum mendistribusikan keahlian ke repositori tim.

Keahlian agen yang Anda buat mungkin akan dijalankan pada berbagai platform otomasi yang berbeda, mulai dari asisten koding lokal hingga sistem backend yang mengandalkan alur kerja otomatis seperti manajemen kunci autentikasi bot web. Memahami perbedaan antara spesifikasi inti dan ekstensi platform sangat penting untuk menjaga portabilitas.

Claude Code mendukung beberapa field tingkat atas tambahan, seperti model, hooks, dan allowed-tools. Pada Claude Code, allowed-tools dituliskan sebagai teks tunggal yang dipisahkan oleh spasi, bukan sebagai daftar larik YAML. Jika berkas dibaca oleh sistem agen lain yang mematuhi spesifikasi standar murni, kunci tambahan ini akan diabaikan.

Validator SKILL.md mengidentifikasi perbedaan ini dengan memberikan catatan informatif. Jika Anda ingin menyematkan konfigurasi khusus platform tanpa menimbulkan kerancuan pada parser standar, masukkan nilai konfigurasi tersebut ke dalam kunci metadata.

Hasil pemeriksaan pada Validator SKILL.md dibagi ke dalam tiga tingkat temuan, yaitu error, warning, dan note. Status berkas dinyatakan valid apabila tidak memiliki error sama sekali, meskipun masih memuat warning atau note praktis.

• Error: Pelanggaran format spesifikasi resmi, seperti frontmatter tidak tertutup, nama tidak valid, atau body kosong yang membuat keahlian gagal dimuat.
• Warning: Penyimpangan dari panduan praktik terbaik, seperti deskripsi di bawah 60 karakter, body melebihi 500 baris, atau keberadaan placeholder TODO.
• Note: Informasi tambahan mengenai ekstensi platform tertentu, seperti penggunaan field eksklusif Claude Code.

Laporan hasil pengujian menyediakan statistik berkas serta tabel temuan yang dapat diekspor ke dalam format CSV. Seluruh proses validasi dieksekusi secara lokal di dalam peramban web pengguna tanpa mengirimkan isi berkas ke server mana pun, sehingga alur kerja internal dan kerahasiaan skrip tim Anda tetap terlindungi.