Skill Claude Code Diam-Diam Gak Kepake? Ini Dia Solusinya

Skill Claude Code Diam-Diam Gak Kepake? Ini Dia Solusinya

Saya manage tim developer yang sudah hidup di dalam Claude Code hampir setahun penuh. Bukan “kita coba buat sprint doang” ya, tapi bener-bener “CI kita jalan di situ dan template pull request kita adalah Claude prompt” gitu. Di tengah perjalanan itu, saya sempat kepedean. Saya bikin custom skills untuk tim: `code-review`, `debug-protocol`, dan `team-conventions`. File-nya rapi di `.claude/skills/`, keliatan bagus, YAML frontmatter-nya lengkap semua. Tapi beberapa minggu pertama, skill-skill itu cuma duduk manis. Diem. Gak dipedulikin. Kayak alarm kebakaran yang baru bunyi pas apinya udah nyala.

Bagian paling nyebelin? File skill-nya bener. Path-nya bener. Markdown-nya bersih dan terdokumentasi dengan cantik. Tapi skill-nya gak pernah kepanggil. Setelah berbulan-bulan garuk-garuk kepala, akhirnya saya sadar: ini bukan salah skill. Ini salah saya.

Jebakan "Skill Gak Jalan"

Buat kamu yang belum pernah ngubek-ngubek konfigurasi skill Claude Code, ini versi singkatnya: skill itu folder di bawah `.claude/skills//SKILL.md`. Masing-masing punya YAML frontmatter — nama dan deskripsi — lalu diikuti instruksi yang harus dijalankan model kalau skill-nya aktif.

```markdown
---
name: code-reivew
description: Use when the user asks for a code review.
---
```

Keliatan polos, ya. Tapi cara Claude Code mutusin mau manggil skill atau nggak adalah dengan baca *semua* deskripsi skill, campur ke sistem prompt-nya, lalu cocok-cocokin sama request yang lagi kamu ketik. Intinya, aktivasi skill itu sebenernya permainan mencocokkan niat. Dan kalau deskripsimu ditulis kayak pemicu keyword yang kaku, ya udah, permainannya kalah dari awal.

Kami habis tiga minggu nyalahin Claude, nyalahin API, nyalahin fase bulan. Terus kami beneran baca dokumentasi resmi skill di [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) dan nyadar sesuatu yang nggak enak: modelnya bukan males, tapi dia cuma literal. Dia cuma bisa manggil skill yang dia *anggap* relevan dari deskripsinya. Dan deskripsi kami waktu itu jelek banget.

Masalah Sebenarnya: Deskripsi yang Gak Cocok

Ini yang butuh waktu lama banget buat kami pahami: **skill itu nggak berdiri sendiri.** Dia hidup di dalam sup berisi skill-skill lain, perilaku bawaan, dan apa pun yang lagi ada di konteks Claude. Pas developer ngetik sesuatu, Claude ngelakuin perhitungan singkat: *“Ini cocok sama deskripsi skill yang mana? Kalau banyak yang cocok, mana yang paling deket? Atau lebih baik jawab langsung aja?”*

Kalau deskripsi skill terlalu sempit, terlalu ambigu, atau terlalu fokus ke keyword, Claude bakal meleset. Kalau deskripsimu tabrakan sama skill lain atau command bawaan, Claude bakal milih yang salah. Kode di dalam `SKILL.md` itu nggak pernah jadi masalah. Yang jadi masalah metadata-nya.

Ini tiga skenario paling umum yang bikin tim-tim kena.

Skenario 1: Skill Code Review yang Kebiasaan Tidur

Saya nulis skill `code-review` dengan deskripsi paling obvious sejagat: *"Use when the user asks for a code review."* Simpel, kan? Salah besar.

Developer kami nggak pernah bilang "code review." Mereka bilang:

- "Bisa sanity-check PR gue?"
- "Liat diff ini, ada yang aneh."
- "Review ini dong sebelum gua ship."
- "Ini over-engineered gak sih?"

Tebak yang mana yang memicu skill-nya? Nggak ada. Claude jawab langsung tanpa manggil skill-nya, karena frasa "code review"-nya nggak pernah muncul di pesan. Perbaikannya bikin malu sendiri. Kami tulis ulang deskripsinya jadi semantik, bukan literal:

```yaml
description: >-
Use for reviewing code changes, pull requests, diffs, or merge requests.
Trigger on phrases like "review this PR", "check my diff", "sanity-check
this code", "is this good to merge", or "look at these changes".
Not for general debugging or explaining code.
```

Kami juga nambahin klausa "Not for". Perubahan satu itu doang bikin skill-nya kepanggil sekitar 80% lebih sering. Skill Claude Code itu fundamentalnya prompt engineering — dan prompt-nya ya deskripsi itu sendiri.

Skenario 2: Debugging Protocol yang Ghosting

Skill `debug-protocol` kami tadinya mau jadi pahlawan tim. Isinya prosedur terstruktur, langkah demi langkah, buat reproduksi bug, cek log, inspect state, sampai ngusulin fix. Bagus banget. Sayangnya, skill-nya nggak pernah kepanggil.

Kenapa? Karena deskripsinya dimulai dengan kata "debug." Padahal "debug" itu ada di mana-mana di Claude Code. Ada built-in debug flag, ada perilaku debugging level sistem, dan mungkin ada tiga skill lain di folder yang sama pakai bahasa mirip. Waktu developer kami bilang "help me debug this failing test," Claude punya empat kandidat yang cocok, dan dia milih yang punya relevansi *keseluruhan* paling kuat — biasanya behavior bawaan, bukan custom skill kami.

Dari sini kami belajar dua hal:

1. **Kasih nama skill yang unik dan spesifik.** `debug-protocol` itu kebanyakan generic. `sentry-repro-protocol` atau `memory-leak-hunt` akan jauh lebih oke. Nama yang generic bakal kalah sama intent yang generic juga.
2. **Pakai manual override.** Di Claude Code, kamu selalu bisa ketik `/debug-protocol` buat maksa skill itu jalan. Kami tambahin ini ke konvensi tim, dan tiba-tiba skill-nya nggak mati — cuma butuh undangan langsung.

Tapi insight yang lebih dalam: model milih skill yang salah karena *kami* sendiri yang bikin tabrakan. Kalau ada dua skill yang bunyinya mirip, Claude bakal nebak. Bikin deskripsi yang saling ngilangin satu sama lain. Bilang eksplisit ke Claude: "gunakan ini, bukan debugging behavior umum, kalau masalahnya melibatkan server logs."

Skenario 3: Team Conventions Skill yang Lupa Semuanya

Kegagalan paling aneh datang dari skill `team-conventions`. Isinya aturan commit message, branch naming, dan deskripsi PR. Awalnya jalan mulus, terus berhenti sekitar pesan ke-20. Kami kira model-nya "lupa." Ternyata bukan bug memori — ini masalah konteks.

Claude Code membuang semua deskripsi skill ke dalam system prompt. Deskripsi yang panjang bakal makan konteks. Nah, pas percakapan makin panjang, sistem mulai kompres atau motong system prompt biar muat. Deskripsi `team-conventions` kami waktu itu kayak tembok teks — tiga paragraf jargon korporat. Itu jadi hal pertama yang dibuang pas konteksnya mulai sempit.

Perbaikannya: kecilin deskripsinya jadi dua atau tiga kalimat, dan pindahin aturan lengkapnya ke file referensi di dalam folder skill. Sekarang deskripsinya cuma penunjuk arah: *"Use for commit message, branch naming, and PR conventions. Full rules in convention.md."* Model bisa nyimpen deskripsi seringkas itu, dan pas skill-nya kepanggil, dia baca file lengkapnya. Kami juga mindahin aturan non-skill ke file `CLAUDE.md`, yang loading-nya lebih reliable buat instruksi seluruh tim.

Perbaikan Praktis yang Bisa Kamu Coba Hari Ini

Setelah berminggu-minggu kesakitan, ini checklist yang pengen banget saya kasih ke diri saya sendiri di hari pertama.

Perlakukan Deskripsi Kayak Query Pencarian

Kalau seseorang search deskripsi skill-mu, apakah hasilnya cocok sama yang kamu mau? Tulis deskripsinya sebagai string pencarian semantik. Tambahin sinonim, frasa asli yang dipakai tim, dan pengecualian yang jelas. Jangan anggap model "tahu maksudmu." Dia cuma tahu apa yang kamu tulis.

Jaga File Skill Tetap Ramping

File skill yang panjangnya 500 baris itu liabilitas. Dia makan konteks, gampang kepotong, dan makin nggak reliable. Fokusin `SKILL.md` ke *keputusan* kapan skill ini kepanggil. Dorong detail beratnya ke file pembantu — `prompt.md`, `criteria.md`, `checklist.md` — yang cuma dibaca Claude setelah skill aktif.

Tambahin Contoh Negatif

Kedengerannya kontraintuitif, tapi ini manjur. Di deskripsi, tulis eksplisit skill ini *bukan* buat apa. Contoh: *"Not for general architecture discussions. Not for syntax questions."* Ini ngurangin false positive, sekaligus bantu model buat bedain skill yang mirip-mirip. Contoh negatif itu alat paling tajam di kotak peralatan.

Pakai `/` untuk Manual Override

Sehebat apa pun metadata-mu, bakal ada momen di mana auto-detection gagal. Biasain tim buat ngetik `/nama-skill` kalau mereka butuh maksa aktivasi. Ini bukan kegagalan — ini fallback. Tim yang paling pinter itu memperlakukan auto-firing skill sebagai kenyamanan, bukan ketergantungan.

Debug Kayak Debug Kode Lain

Claude Code punya flag `--debug`. Pakai. Periksa system prompt yang dirakit di awal sesi, dan pastikan deskripsi skill-mu beneran ada di situ. Kedengeran jelas, tapi kami nemuin koma di akhir salah satu blok YAML frontmatter bikin satu file skill gagal di-load diam-diam. Skill-nya nggak pernah ke-load. Bukan karena intent-matching gagal — tapi karena parse error. Output debug nangkep itu dalam sepuluh detik.

Tes dengan Berbagai Gaya Ngomong

Jangan cuma tes frasa persis yang ada di dokumentasi. Buka sesi baru, terus ketik cara ngomong yang berantakan, manusiawi, dan ambigu yang beneran dipakai tim kamu. "PR ini bakal meledak gak?" harusnya memicu skill review kamu kalau deskripsimu bener. Kalau nggak, deskripsimu belum cukup bagus.

FAQ

Kenapa skill saya jalan di sesi baru tapi berhenti kepanggil belakangan?

Itu hampir selalu context truncation. Deskripsi skill yang kepanjangan bakal dibuang dari system prompt pas percakapan makin gede. Kecilin deskripsinya, atau restrukturisasi pakai file referensi. Ini bukan masalah memori — ini masalah ruang.

Lebih baik pakai keyword atau natural language di deskripsi skill?

Dua-duanya, dengan rasio yang pas. Mulai dengan satu kalimat deskripsi semantik soal *intent* ("use for reviewing code changes"), terus tambahin daftar frasa pemicu yang umum. Jangan cuma ngandelin keyword, tapi jangan juga terlalu abstrak sampai nggak ada yang cocok.

Bisa nggak custom skill override behavior bawaan Claude Code?

Nggak bisa langsung. Behavior bawaan itu sudah terhubung di level yang nggak bisa di-override skill kamu. Tapi kamu bisa menang di babak pencocokan dengan bikin deskripsi skill lebih spesifik dan relevan dengan situasi tim kamu. Kalau mentok, pakai `/nama-skill` buat maksa, atau ubah redaksi request-nya sampai jalur bawaan nggak cocok lagi.

Gimana cara tahu skill file saya beneran ke-load?

Jalankan `claude --debug` dan periksa output-nya. Kamu harusnya lihat skill-skill kamu tercantum di perakitan system prompt. Kalau skill-mu nggak ada di daftar, cek YAML frontmatter, struktur folder, dan nama file-nya. Folder skill tanpa `SKILL.md` yang valid cuma jadi hiasan.

Intinya

Ini kebenaran yang nggak enak: pas skill nggak kepanggil, file skill-nya hampir nggak pernah jadi biang kerok. Masalahnya adalah seberapa baik kamu nerjemahin niat manusia — "review kerjaanku, ikutin aturan kita, benerin bug ini dengan cara yang udah kita sepakati" — ke dalam metadata yang beneran dibaca Claude. Ini bukan soal nulis kode yang lebih bagus. Ini soal nulis *penunjuk arah* yang lebih bagus.

Kalau kamu lagi kesel sama skill yang senyap, jangan tulis ulang markdown-mu dari nol. Tulis ulang deskripsinya. Tambahin contoh nyata. Tambahin pengecualian. Jaga file-nya tetap ramping. Dan kalau semua cara udah mentok, tinggal ketik `/nama-skill` langsung, dan lanjutin hari kamu.

Skill-nya nggak rusak. Dan percaya atau nggak, Claude juga nggak rusak. Kita cuma lupa kalau model itu perlu diundang ke pesta dengan lebih dari sekadar anggukan samar dari seberang ruangan.