Claude Code Mengabaikan Skill Saya 5 Kali. 1 Baris Memperbaikinya

Skill Claude Code bisa jalan sempurna saat dipanggil lewat nama, tetapi tidak pernah load sendiri. Skill kami jalan setiap kali kami mengetik namanya, dan dilewati setiap kali kami meminta tugas yang sama dengan kata biasa. Kami melihatnya dilewati, membaca sebabnya, lalu menulis ulang satu baris yang memperbaikinya.

Skill adalah kumpulan instruksi tersimpan yang diambil Claude Code sendiri saat permintaanmu cocok dengannya. Yang menentukan kecocokan itu satu baris yang dibaca Claude sebelum memilih, bukan instruksimu. Enam langkah di bawah membawamu dari prompt yang terus kamu ketik ulang sampai skill yang load sendiri, ditambah tes dua puluh permintaan yang menangkap skill yang dilewati sebelum timmu mengetahuinya.

Tes (permintaan sama, sesi baru)	Skill ter-load
Dipanggil lewat nama (/release-notes)	2 dari 2
Kata biasa, description asli	0 dari 5
Kata biasa, description yang ditulis ulang	5 dari 5

Skill adalah folder dengan satu file di dalamnya, SKILL.md. File itu diawali header singkat (name dan description satu kalimat), diikuti instruksi. Cara kerjanya seperti function: pemanggil membaca signature dan docstring, dan body baru jalan saat dipanggil. Simpan di folder home agar ada di setiap proyek, atau di dalam repository agar semua orang yang bekerja di sana mendapatkannya.

Mulailah dari tugas, bukan dari file. Pilih prompt yang terus kamu ketik ulang dan tulis output persis yang kamu inginkan. Punya kami release notes mingguan: commit sejak Senin, dikelompokkan per area, chore dibuang, satu baris per perubahan beserta nomor pull request-nya. Di repository open source Hono, prompt panjang itu menghasilkan catatan rapi untuk delapan perbaikan bug minggu itu, dan output itulah target yang harus dicapai skill.

Tidak semua prompt layak jadi skill. Pertanyaan sekali pakai tidak, dan skill yang tak pernah dipakai ulang hanyalah satu baris lagi yang harus dibaca Claude. Simpan daftar pendek prompt yang kamu ketik tiap minggu; yang paling atas menjadi skill pertamamu.

Buat .claude/skills/release-notes/SKILL.md di proyekmu: folder skills di dalam folder tersembunyi .claude, folder bernama sesuai skill, dan file skill di dalamnya. Foldernya penting. File release-notes.md yang tergeletak begitu saja tidak di-load sama sekali, dan docs menyebutnya hal pertama yang harus dicek.

Header berupa beberapa baris berlabel di antara dua baris tanda hubung, dan harus dimulai di baris pertama file, kalau tidak Claude Code mengabaikannya. Punya kami berisi name, release-notes, dan description yang akan ditulis kebanyakan orang:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Di bawah header, instruksi berupa langkah bernomor, yang akan kamu berikan ke rekan baru. Punya kami ada lima: cari commit sejak Senin, buang commit chore dan docs, kelompokkan menurut scope conventional-commit, tulis satu baris biasa per perubahan, dan keluarkan blok berjudul dengan ringkasan singkat di atasnya. Anthropic menyarankan bagian ini dibuat singkat. Tidak perlu restart: Claude Code mengambil skill yang baru atau yang diedit di sesi yang sedang kamu pakai.

Tes lewat nama: ketik garis miring, pilih skill di menu, tekan enter. Di sesi baru, skill kami membaca log commit, mengelompokkan perbaikan per area, dan menulis catatan persis seperti yang diinginkan, setiap kali. Masalahnya, kamu dan seluruh timmu harus ingat namanya.

Rekan setimmu tidak akan mengetik nama skill. Mereka membuka sesi baru dan meminta seperti meminta kepadamu. Jadi tes itu: buka sesi baru (percakapan baru tanpa apa pun ter-load) dan minta tugasnya dengan kata-katamu sendiri. Harus sesi baru, karena skill yang sudah dipakai tetap ada di percakapan, dan tes di sesi itu tidak membuktikan apa-apa.

Kami mengetik "what did we ship this week?". Claude menjalankan log commit sendiri dan menulis ringkasan dengan caranya, tanpa jejak skill. Jawabannya tidak buruk, tetapi berubah-ubah antar-run: satu menghitung dari Senin, satu lagi dari tag rilis terakhir dan ikut memasukkan perubahan docs yang akan dibuang skill. Dalam lima sesi baru, skill dilewati di kelimanya.

Lima run adalah demo, bukan statistik. Tapi skill yang jalan lewat nama dan dilewati setiap kali dengan kata biasa tidak menjalankan tugasnya, dan karena ia lulus tes nama di langkah dua, kamu tak akan pernah berpikir untuk mengeceknya.

Sebelum mengubah satu kata pun, jalankan tiga pengecekan:

1. /skills menampilkan semua skill yang bisa dilihat sesi. Cari milikmu. Punya kami terdaftar dan aktif, tetapi setup kami memuat 277 skill, dan beberapa skill plugin cocok dengan "release" sebelum milik kami.
2. claude --debug menulis log rinci tentang apa yang di-load Claude Code. Cari baris skills. Punya kami menunjukkan skill proyek ter-load, dan juga peringatan bahwa daftar skill melebihi budget, sehingga sebagian description dipotong.
3. claude plugin validate .claude/skills memeriksa bahwa header terbentuk dengan benar. Ini penting: header yang rusak tetap membiarkan skill jalan lewat nama, tetapi Claude tak lagi bisa mencocokkannya sendiri. Punya kami lolos.

Pengecekan	Yang diberitahukan	Hasil kami
/skills	Apakah skill terlihat dan aktif?	Terdaftar, aktif (277 skill)
--debug	Apakah ter-load? Apakah daftarnya dipotong?	Ter-load; peringatan daftar melebihi budget
plugin validate	Apakah header ter-parse?	Lolos

Dengan file ter-load dan header valid, penyebabnya adalah description. Sampai memutuskan me-load sebuah skill, Claude tidak membaca instruksimu. Ia membaca satu baris per skill, name dan description, lalu mencocokkannya dengan kata-katamu. Punya kami berbunyi "generates changelog documents from repository history"; permintaannya "what did we ship this week". Kedua kalimat itu tidak punya satu kata pun yang sama. Claude tak pernah membaca instruksi kami; ia membaca satu baris, dan baris itu tidak memakai kata-kata kami.

Peringatan budget berarti Claude Code memangkas description agar muat, dimulai dari skill yang paling jarang dipakai, dan skill yang baru dibuat adalah yang paling jarang dipakai. Cek apakah milikmu selamat: punya kami selamat, karena permintaan dengan kata-katanya sendiri tetap me-load-nya.

Tulis description untuk saat seseorang meminta, bukan untuk file. Sebutkan apa yang dikerjakan skill, kapan dipakai, dan kata yang benar-benar diketik orang. Punya kami menjadi:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Panduan penulisan Anthropic menambahkan satu aturan: tulis dalam sudut pandang orang ketiga ("Writes"), jangan pernah "I can help" atau "You can use this".

Lalu buktikan di sesi baru dengan permintaan yang sama. "What did we ship this week?" kini me-load skill sebelum Claude menyentuh apa pun, dan catatannya keluar dalam format kami, di lima dari lima sesi baru.

Jalankan juga baseline: matikan skill dengan skill override di file settings lokalmu (ini menyembunyikan skill tanpa menghapusnya). Saat mati, Claude kembali ke ringkasannya sendiri; saat hidup, skill ter-load. Skill-lah yang membuat bedanya, bukan kebetulan.

Batasannya: description yang cocok dengan terlalu banyak hal membuat skill aktif di tempat yang tidak semestinya. Tambahkan kata yang benar-benar kamu pakai, bukan semua kata yang terpikir.

Satu permintaan membuktikan perbaikan kami, tetapi skill yang diandalkan tim diminta dengan banyak cara. Skill-creator Anthropic menjelaskan tesnya: dua puluh permintaan, campuran yang seharusnya me-load skill dan near miss yang tidak boleh. Near miss terdengar mirip tetapi pekerjaan lain, seperti "write a commit message for my staged changes". Jalankan tiap permintaan di sesi barunya sendiri dan catat apakah skill ter-load. Skrip milik skill-creator tidak melihat skill di versi Claude Code kami, jadi kami menjalankan dua puluh permintaan yang sama dengan skrip pendek buatan sendiri.

Description	Permintaan should-load yang me-load-nya	Near miss yang me-load-nya
Asli	4 dari 10	0 dari 10
Ditulis ulang	10 dari 10	0 dari 10

Sebelum penulisan ulang, skill hanya ter-load pada permintaan yang sudah memuat "release notes", "changelog", atau "release": pencocokan kata dari langkah empat, terlihat jelas. Sesudahnya, ia ter-load pada setiap permintaan yang semestinya, dan tetap tidak masuk ke satu pun near miss.

Untuk skill yang tak boleh meleset, paksa. Ketik namanya, atau tambahkan hook (skrip kecil yang dijalankan Claude Code pada saat tertentu, di sini setiap kali kamu mengirim pesan) yang outputnya menyuruh Claude memakai skill itu untuk tugas tersebut. Dengan hook terpasang, bahkan description asli ter-load pada permintaan biasa. Batasannya: setiap run tes memakai usage sungguhan dan hook menambah satu baris di tiap pesan, jadi simpan untuk beberapa skill yang benar-benar harus aktif. Jalankan ulang daftarmu setiap kali mengubah description.

Skill release-notes kami jalan setiap kali lewat nama, dilewati di setiap sesi baru dengan kata biasa, dan satu baris yang ditulis ulang membuatnya ter-load setiap kali. Sebabnya: Claude membaca satu baris per skill sebelum memutuskan, dan ia mencocokkan kata-katamu, bukan maksudmu.

Skill berguna untuk tugas yang kamu ulang dengan output tetap: catatan mingguan, deskripsi pull request, checklist rilis. Tidak untuk pertanyaan sekali pakai, dan bukan alat untuk aturan yang harus selalu berlaku; itu tugas hook. Tumpukan skill yang tak dipakai juga merugikan, karena kalau terlalu banyak, Claude Code mulai memotong description, yang paling jarang dipakai lebih dulu. Description yang bagus menaikkan peluang, tetapi tak akan membuat skill aktif untuk pekerjaan yang memang bukan untuknya, dan segelintir run hanyalah demo, jadi daftar permintaan tesmu adalah pengecekan yang sebenarnya.

Satu aturannya: tulis description dengan kata yang benar-benar kamu ketik saat meminta tugas itu.