Nulis Skill Hermes yang Benar: Struktur, Pitfalls, dan Cara Biar Tidak Stale

Hermes mengubah cara developer berinteraksi dengan knowledge base. Tapi skill yang ditulis asal-asalan bisa bikin model bingung, merespons melenceng, atau worse lagi — diam saja pas user butuh. Artikel ini bedah cara nulis skill Hermes yang efektif, dari struktur dasar sampai strategi menjaga skill tetap fresh.

Anatomi SKILL.md: Bukan Sekadar File Markdown Biasa

Setiap skill Hermes berpusat pada satu file SKILL.md. Di sinilah semua logika, konteks, dan instruksi hidup. Tapi bukan sembarang markdown — file ini punya struktur yang dipahami oleh Hermes parser. Memahami anatomi ini adalah fondasi sebelum menulis satu baris pun.

Bagian paling atas adalah frontmatter YAML. Ini bukan dekorasi. Frontmatter memberi metadata yang dipakai Hermes untuk routing, ranking, dan contextual matching. Field seperti name, description, version, dan tags menentukan bagaimana skill ini muncul di ekosistem. Melewatkan salah satu field penting bisa bikin skill tidak ter-trigger sama sekali, meski konten di dalamnya sempurna.

Setelah frontmatter, ada bagian when_to_use. Ini adalah jantung dari skill. Bagian ini menjelaskan kondisi kapan skill harus diaktifkan. Hermes membaca ini untuk melakukan matching antara intent user dan skill yang tersedia. Jika deskripsi terlalu umum, skill akan ter-trigger di konteks yang salah. Jika terlalu spesifik, skill mungkin tidak pernah ter-trigger sama sekali. Keseimbangan di sini menentukan kualitas respons yang dihasilkan.

Bagian steps berisi instruksi eksplisit untuk model. Ini adalah urutan logis yang harus diikuti saat skill aktif. Steps harus terstruktur, jelas, dan tidak ambigu. Model tidak bisa menebak-nebak — setiap langkah harus bisa dieksekusi tanpa keraguan. Steps yang buruk menghasilkan output yang tidak konsisten dan sulit di-debug.

Terakhir, pitfalls adalah daftar hal-hal yang harus dihindari. Bagian ini sering diabaikan, padahal sama pentingnya dengan steps. Pitfalls mencegah model terjebak dalam pola respons yang salah, seperti memberikan jawaban yang terlalu panjang, menggunakan asumsi yang tidak valid, atau melewatkan langkah penting.

Kenapa Description 57 Karakter Pertama Kritis

Ini bukan mitos. Hermes menggunakan description sebagai sinyal utama untuk intent matching. Dan model hanya membaca sekitar 57 karakter pertama sebelum membuat keputusan routing. Sisanya, meski ditulis dengan sangat detail, sering kali tidak sampai ke proses penentuan apakah skill ini relevan atau tidak.

Bayangkan description seperti headline di koran. Orang hanya melihat sekilas, dan keputusan mereka dibuat dalam hitungan milidetik. Sama halnya dengan Hermes — description yang buruk di 57 karakter pertama berarti skill lo tidak akan pernah muncul, berapa pun bagusnya konten di dalamnya.

Contoh buruk: "Skill ini membantu developer dalam menulis kode yang lebih baik dengan berbagai teknik dan best practice yang bisa diterapkan" — 142 karakter, terlalu umum, tidak ada konteks spesifik.

Contoh lebih baik: "Membantu refaktor kode Python ke pattern yang lebih clean dan maintainable" — 72 karakter, tapi 57 karakter pertamanya sudah jelas: "Membantu refaktor kode Python ke pattern yang" — cukup untuk trigger matching.

Karakter 58-57 itu bukan berarti tidak penting sama sekali. Deskripsi lengkap tetap dibaca untuk scoring dan contextual nuance. Tapi 57 karakter pertama adalah gatekeeper. Jika gagal di gate ini, seluruh effort menulis skill berikutnya jadi percuma.

Praktiknya, tulis description seperti headline berita: subjek, verb, objek, spesifik. Hindari kata-kata filler seperti "ini adalah", "yang bertujuan untuk", atau "yang bisa membantu". Setiap karakter berharga.

Skill Terlalu Luas vs Terlalu Spesifik — Trade-off yang Harus Dipahami

Ini adalah dilema paling umum dalam authoring skill. Terlalu luas, dan skill lo akan ter-trigger di konteks yang salah, menghasilkan respons yang generik dan tidak relevan. Terlalu spesifik, dan skill lo hampir tidak pernah ter-trigger karena tidak ada user yang persis cocok dengan deskripsi lo.

Skill terlalu luas contohnya: "Membantu debugging kode" — ini bisa berarti apa saja. Python? JavaScript? Go? Debugging di browser? Di server? Di CI/CD? Hermes tidak akan tahu harus merutekan ke skill ini atau tidak, dan ketika ter-trigger, outputnya akan sangat umum karena tidak ada konteks yang cukup.

Skill terlalu spesifik contohnya: "Membantu debugging error 'TypeError: undefined is not a function' di React 18 dengan TypeScript 5.4" — ini sangat spesifik, tapi probabilitas user mengalami error persis seperti ini sangat rendah. Skill ini hampir tidak pernah ter-trigger, dan ketika ter-trigger, cakupannya terlalu sempit untuk memberikan nilai nyata.

Solusinya ada di tengah: spesifik dalam konteks, generik dalam solusi. Skill yang baik memiliki description yang cukup spesifik untuk triggering yang akurat, tapi steps yang cukup generik untuk menangani variasi kasus.

Contohnya: "Membantu debugging TypeError di aplikasi JavaScript/TypeScript" — cukup spesifik untuk routing (TypeError + JS/TS), tapi cukup generik untuk menangani berbagai sub-kasus. Steps-nya bisa mencakup pola umum debugging TypeError: cek null/undefined, periksa tipe data, review type annotations, dan lain-lain.

Trade-off ini juga berlaku di level tags dan when_to_use. Tags yang terlalu banyak membuat skill bersaing dengan dirinya sendiri. Tags yang terlalu sedikit membuat skill hilang di tengah hiruk-pikuk knowledge base. Temukan titik di mana tags cukup deskriptif untuk routing tapi tidak membatasi cakupannya secara tidak perlu.

Cara Skill Jadi Stale dan Kapan Harus Di-patch

Skill yang stale adalah skill yang ditulis sekali lalu dibiarkan begitu saja. Dunia berubah, library update, best practice bergeser — tapi skill tetap sama. Akibatnya, model mengikuti instruksi yang sudah kadaluwarsa, memberikan saran yang tidak lagi relevan, atau bahkan menyesatkan.

Tanda-tanda skill mulai stale: pertama, library atau tool yang dibahas sudah release versi baru dengan perubahan breaking. Kedua, ada pola atau praktik baru yang lebih baik tapi tidak tercakup di skill. Ketiga, user mulai melaporkan respons yang terasa "kuno" atau tidak sesuai dengan konteks terkini.

Proses patching skill sebaiknya dilakukan secara berkala, bukan menunggu sampai rusak. Tetapkan jadwal review — bulanan untuk skill yang membahas teknologi cepat berubah seperti framework web atau tooling, triwulanan untuk skill yang membahas konsep yang lebih stabil seperti algoritma atau arsitektur.

Saat melakukan patch, jangan hanya update versi. Review seluruh SKILL.md dari awal: apakah when_to_use masih akurat? Apakah steps masih relevan? Apakah pitfalls masih mencakup risiko terkini? Sering kali, perubahan kecil di satu bagian membutuhkan penyesuaian di bagian lain.

Jangan takut menghapus bagian yang sudah tidak relevan. Skill yang lebih pendek tapi akurat lebih berharga daripada skill yang panjang tapi mengandung informasi kadaluwarsa. Hermes tidak menghukum skill yang ringkas — ia menghukum skill yang ambigu atau salah.

Linked Files: Kapan Pisah ke references/ vs Inline

Satu SKILL.md yang sangat panjang bukan solusi. Ketika konten skill melampaui sekitar 200 baris, readability menurun, maintenance menjadi sulit, dan parsing overhead meningkat. Di sinilah konsep linked files masuk.

Hermes mendukung referensi ke file eksternal melalui mekanisme linked files. File-file ini bisa disimpan di direktori references/ dan direferensikan dari SKILL.md utama. Pertanyaannya: kapan harus dipisah, dan kapan harus tetap inline?

Pisah ke references/ ketika: konten bersifat referensi murni (dokumentasi API, spec, tabel konstanta), konten sangat panjang (di atas 100 baris), atau konten bersifat modular dan bisa dipakai oleh beberapa skill sekaligus. File di references/ tetap dibaca oleh Hermes saat skill aktif, tapi tidak membebani SKILL.md utama.

Tetap inline ketika: konten adalah instruksi eksplisit yang harus diikuti secara berurutan, konten relatif pendek (di bawah 50 baris), atau konten bersifat kontekstual dan tidak relevan untuk skill lain. Steps dan pitfalls sebaiknya tetap di SKILL.md karena mereka adalah inti dari skill.

Contoh praktis: skill untuk debugging React punya SKILL.md utama berisi steps debugging dan pitfalls. Tapi ada references/react-error-codes.md yang berisi tabel lengkap error codes React beserta solusinya. SKILL.md mengarahkan ke file referensi saat langkah debugging memerlukan lookup error code.

Keputusan ini bukan hitam-putih. Beberapa skill kompleks mungkin membutuhkan hierarki: SKILL.md utama → references/ untuk modul-modul → sub-references untuk detail teknis. Yang penting, struktur harus logis dan mudah di-maintenance.

Langkah Praktis: Mulai dari Sekarang

Menulis skill Hermes yang baik membutuhkan iterasi. Skill pertama lo biasanya tidak sempurna — dan itu wajar. Yang penting adalah memulai, menguji, mengamati bagaimana model merespons, dan memperbaiki berdasarkan feedback nyata.

Gunakan test cases sederhana untuk memvalidasi skill lo. Tanyakan pertanyaan yang seharusnya trigger skill lo, dan periksa apakah responsnya sesuai ekspektasi. Jika tidak, review when_to_use, description, dan steps. Ulangi sampai konsisten.

Jangan lupa untuk mendokumentasikan perubahan di setiap patch. Version history di frontmatter bukan sekadar formalitas — ini jejak yang membantu lo dan team memahami evolusi skill dari waktu ke waktu.

Insight: Skill yang Baik Adalah Skill yang Tumbuh

Skill Hermes yang terbaik bukan yang ditulis sempurna di hari pertama. Skill yang terbaik adalah yang dirawat, diperbarui, dan disempurnakan secara berkala berdasarkan data nyata dari pengguna. Setiap kali model merespons dengan salah, itu adalah sinyal bahwa skill perlu di-review. Setiap kali user memberikan feedback positif, itu adalah konfirmasi bahwa arah yang diambil sudah tepat.

Pendekatan ini mengubah authoring skill dari satu-time task menjadi continuous improvement loop. Dan di ekosistem Hermes, skill yang terus berkembang akan terus relevan — tidak akan pernah stale.

---

Review satu skill lo sekarang. Buka SKILL.md, periksa 57 karakter pertama description, review when_to_use, dan tanyakan pada diri sendiri: apakah trigger dan pitfall-nya masih akurat untuk konteks hari ini? Jika ragu, patch. Skill yang dirawat adalah skill yang tetap berguna.