Skills Claude Code: cara kerja SKILL.md dan kapan agen memuatnya

Apa itu skills di Claude Code

Skill adalah folder dengan berkas SKILL.md yang berisi instruksi untuk jenis tugas tertentu: cara men-deploy proyek, cara melakukan review, cara merilis. Agen tahu bahwa skill itu ada sejak awal sesi, tetapi membacanya utuh hanya ketika tugas benar-benar membutuhkannya.

Claude Code skills memecahkan masalah yang dikenal setiap orang yang lama memelihara CLAUDE.md: berkas instruksi terus membengkak. Prosedur deploy sepanjang 80 baris dibutuhkan sekali seminggu, tetapi di berkas itu ia memakan tempat di konteks setiap sesi — termasuk ketika Anda hanya memperbaiki salah ketik di README. Skill memindahkan prosedur seperti itu dari konteks yang selalu hadir dan memuatnya sesuai kebutuhan.

Dari apa sebuah skill terdiri

Skill minimal adalah satu folder dan satu berkas. Skill proyek disimpan di repositori, skill pribadi di direktori home pengguna:

.claude/skills/deploy/SKILL.md      # skill proyek, dibagikan tim lewat git
~/.claude/skills/review/SKILL.md    # skill pribadi, tersedia di semua proyek

Di samping SKILL.md Anda bisa meletakkan berkas pendukung: template, skrip, referensi. Agen akan membukanya hanya jika teks utama skill merujuknya dan berkas itu dibutuhkan:

.claude/skills/deploy/
├── SKILL.md           # instruksi utama
├── checklist.md       # daftar periksa rinci, dibaca lewat tautan
└── rollback.sh        # skrip rollback

Frontmatter: name dan description

Berkas dimulai dengan blok YAML di antara baris ---. Dua field paling penting: name — nama pendek skill, dan description — deskripsi tentang apa yang dilakukan skill dan kapan menerapkannya.

---
name: deploy
description: Deploy situs ke hosting lewat FTP. Gunakan ketika perlu mengunggah perubahan ke server, memeriksa selisih dengan server, atau membatalkan deploy.
---

# Deploy

1. Mulai dengan uji coba: `./deploy.sh -n`.
2. Periksa daftar berkas: tidak boleh ada rahasia dan skrip uji.
3. Unggah: `./deploy.sh`.
4. Buka halaman yang berubah dan pastikan mengembalikan 200.

Rollback — lihat rollback.sh di folder ini.

Di bawah frontmatter adalah Markdown biasa: langkah, perintah, batasan, tautan ke berkas di sebelahnya. Tulislah seperti Anda menulis instruksi untuk rekan baru yang pertama kali mengerjakan tugas itu.

Kapan agen memuat skill

Di awal sesi, ke dalam konteks masuk hanya nama dan deskripsi setiap skill yang tersedia. Itu beberapa baris per skill, sehingga puluhan skill pun masih terjangkau. Ketika permintaan pengguna atau langkah kerja saat ini cocok dengan deskripsi, agen memanggil skill — dan baru saat itu teks lengkap SKILL.md dimuat.

Dari sini lahir aturan praktis: skill dipicu oleh deskripsinya. Agen tidak melihat isi skill sebelum memutuskan untuk membukanya. Jika di description tertulis «Skill pendukung», agen tidak akan tahu kapan ia dibutuhkan. Jika tertulis «Deploy ke hosting; gunakan ketika perlu mengunggah perubahan ke server atau membatalkan deploy» — agen tahu.

Selain pemilihan otomatis, skill bisa dipanggil langsung dengan namanya lewat garis miring, misalnya /deploy. Ini berguna ketika Anda tahu persis prosedur mana yang dibutuhkan dan tidak ingin mengandalkan pencocokan deskripsi oleh agen.

Cara menulis description agar skill terpicu

• Apa yang dilakukan — satu frasa dengan kata kerja: «Deploy situs», «Review perubahan sebelum commit».
• Kapan digunakan — sebutkan kalimat yang benar-benar dipakai pengguna untuk meminta tugas ini: «unggah ke server», «publikasikan», «batalkan».
• Kapan tidak digunakan, jika skill mudah tertukar dengan tetangganya: «bukan untuk deploy bot, hanya situs».
• Hindari frasa umum seperti «skill yang berguna» atau «membantu pekerjaan» — tidak membawa sinyal apa pun.

Progressive disclosure

Skills dibangun di atas prinsip progressive disclosure: informasi disajikan berlapis, dan setiap lapisan berikutnya dimuat hanya ketika dibutuhkan.

Ini ide yang sama dengan router alih-alih tumpukan teks di berkas instruksi: peta singkat selalu terlihat, rinciannya lewat tautan. Bedanya, skill menjadikan pemuatan seperti itu mekanisme bawaan, bukan harapan bahwa agen sendiri akan membuka dokumen yang tepat. Keuntungan tambahan: skrip di lapisan ketiga bisa langsung dijalankan agen, tanpa seluruh kodenya dimuat ke konteks.

Skills, CLAUDE.md, dan slash-command: apa bedanya

Ketiga mekanisme ini menyampaikan instruksi kepada agen, tetapi pada momen berbeda dan dengan biaya konteks berbeda.

Aturan praktis untuk memilih: jika instruksi dibutuhkan hampir di setiap tugas, tempatnya di CLAUDE.md. Jika dibutuhkan pada tugas jenis tertentu, itu skill. Jika Anda sendiri setiap kali mengetik permintaan panjang yang sama, itu kandidat untuk perintah atau skill yang dipanggil manual.

Larangan keras jangan dipindahkan ke skill. Skill mungkin tidak dimuat, sedangkan aturan «jangan pernah commit rahasia» harus berlaku selalu. Invarian seperti itu tetap di CLAUDE.md dan sebisa mungkin didukung mekanisme: hook, izin akses, pemeriksaan di CI.

Cara membuat skill untuk Claude Code, langkah demi langkah

1. Temukan prosedur yang berulang. Tanda baiknya: Anda sudah tiga kali menjelaskan hal yang sama kepada agen, atau ada bagian di CLAUDE.md yang hanya dibutuhkan dalam satu dari sepuluh tugas.
2. Buat folder .claude/skills/<nama>/ dan berkas SKILL.md di dalamnya.
3. Tulis frontmatter dengan name dan description yang jelas menyebut kapan skill diterapkan.
4. Jelaskan langkahnya dengan perintah konkret dan kriteria selesai: apa yang diperiksa dan hasil seperti apa yang dianggap berhasil.
5. Pindahkan bagian panjang ke berkas terpisah dan rujuk dari teks utama.
6. Hapus duplikasi dari CLAUDE.md, sisakan satu baris penunjuk: «Deploy — skill deploy».
7. Uji: di sesi baru, minta tugasnya dengan kata-kata Anda sendiri tanpa menyebut nama skill, lalu lihat apakah agen memakainya. Jika tidak, tulis ulang deskripsinya.

Contoh skill

Skill deploy

Kandidat klasik: prosedurnya jarang, panjang, dan berbahaya, serta kesalahan mahal. Di skill dicatat urutan langkah (uji coba dulu, baru unggah), apa yang tidak boleh diunggah, bagaimana memeriksa hasilnya, dan cara membatalkannya. Agen tidak perlu menyimpan semua itu di kepala setiap kali mengedit kode — hanya ketika pembicaraan menyangkut server.

Skill review

---
name: review
description: Review perubahan yang sedang berjalan sebelum commit. Gunakan ketika diminta memeriksa diff, mencari kesalahan dalam perubahan, atau menyiapkan perubahan untuk commit.
---

# Review perubahan

1. Ambil diff: `git diff` dan `git diff --staged`.
2. Untuk setiap berkas yang berubah, periksa:
   - input pengguna di-escape saat ditampilkan;
   - kueri SQL memakai parameter;
   - tidak ada output debug dan berkas sementara.
3. Jalankan tes dan linter proyek (perintahnya ada di CLAUDE.md).
4. Laporan: daftar masalah dengan berkas dan baris, dari yang serius ke yang kecil.
   Jika tidak ada masalah, katakan begitu, tanpa mengarang catatan.

Skill seperti ini mengubah «coba lihat, apakah semuanya baik» menjadi pemeriksaan yang bisa diulang dengan daftar butir yang sama dari waktu ke waktu.

Skill penutupan sesi

Jenis lain yang berguna adalah ritual di akhir kerja: menghentikan lingkungan lokal, menghapus berkas sementara, menulis ke jurnal kemajuan apa yang sudah dikerjakan dan apa yang tersisa, lalu membuat commit dengan deskripsi rinci. Ini langsung mengatasi kehilangan konteks antarsesi: sesi berikutnya dimulai dari keadaan repositori yang mutakhir, bukan dari tebakan.

Kesalahan umum

• Deskripsi yang kabur. Skill ada, tetapi agen tidak memanggilnya. Solusinya menulis ulang description dengan pemicu yang konkret.
• Skill berupa tumpukan teks. Seluruh bagian lama sepanjang 400 baris dipindahkan ke SKILL.md. Masalah konteks yang membengkak kembali, hanya lebih belakangan. Jaga teks utama tetap pendek, rincian di berkas pendamping.
• Duplikasi dengan CLAUDE.md. Prosedur yang sama ditulis di dua tempat dan lama-lama berbeda. Sumber kebenaran harus hanya satu.
• Skill yang tumpang-tindih. Dua skill dengan deskripsi serupa — agen memilih di antara keduanya secara acak. Pisahkan dengan batasan tegas «gunakan / jangan gunakan».
• Perintah yang sudah usang. Skrip diganti namanya, tetapi skill masih merujuk nama lama. Skill adalah bagian dari kode proyek: perbaiki bersama prosedurnya dalam commit yang sama.

Bagaimana tahu saatnya memindahkan bagian ke skill

Berkala, telusuri CLAUDE.md dan untuk setiap bagian tanyakan: dalam berapa persen tugas biasa bagian ini benar-benar dibutuhkan? Jika hampir selalu, tempatnya memang di sana. Jika hanya di satu dari sepuluh tugas, itu kandidat skill.

Sinyal kedua adalah panjang. Bagian yang tidak muat satu layar hampir pasti menjelaskan prosedur, bukan aturan. Prosedur lebih mudah dibaca utuh pada saat dijalankan, bukan dipegang sepanjang sesi.

Sinyal ketiga adalah penjelasan yang berulang. Jika Anda terus-menerus menulis kepada agen klarifikasi yang sama untuk tugas yang sama, tuliskan sekali di skill. Seminggu kemudian lihat apakah jumlah koreksi manual berkurang — itulah bukti bahwa skill bekerja.

Ringkasan

Claude Code skills adalah cara menyimpan prosedur di dekat proyek tanpa membayarnya dengan konteks di setiap sesi. Deskripsi skill terlihat selalu, isinya dimuat sesuai kebutuhan, dan berkas pendukung lebih belakangan lagi. Di CLAUDE.md tetap tinggal peta proyek dan aturan keras, sedangkan deploy, review, rilis, dan tugas lain yang bersifat tipe-tertentu pindah ke skill. Struktur berkas instruksi dan progressive disclosure dibahas praktis di kursus harness engineering.