Cara Menulis Skill Agent dari Kegagalan Nyata

Tulis skill agent Anda sendiri berdasarkan satu kegagalan nyata

Cara terbaik untuk menulis skill agent sendiri adalah menyaringnya dari satu kegagalan nyata. Temukan tugas yang dua kali salah dikerjakan oleh coding agent Anda, catat koreksi yang Anda ketik pada kedua kesempatan tersebut, lalu simpan koreksi itu sebagai file SKILL.md yang dapat dimuat agent secara mandiri. Setelah itu, sisanya hanya mekanisme: tata letak file dan satu baris yang menentukan apakah skill tersebut akan aktif.

Urutan ini penting. Skill yang ditulis berdasarkan imajinasi mendokumentasikan masalah yang belum pernah Anda alami, tetapi tetap menggunakan context pada setiap session. Skill yang disaring dari kegagalan yang Anda saksikan memiliki pengujian bawaan: ajukan permintaan yang sama sekali lagi, lalu lihat apakah agent berhasil melakukannya dengan benar kali ini. Jika format ini masih baru bagi Anda, baca apa itu agent skill dan bagaimana agent memuatnya terlebih dahulu, lalu kembali dan tulis satu skill.

Mulai dari tugas yang dua kali ditangani agen secara keliru

Sekali bisa jadi kebetulan. Dua kali menjadi pola, dan pola layak disimpan dalam sebuah file.

Berikut adalah kegagalan yang berulang pada server nyata. Anda meminta agen menambahkan blok reverse proxy ke nginx. Agen mengedit /etc/nginx/conf.d/app.conf, lalu menjalankan sudo systemctl restart nginx. Edit tersebut mengandung kesalahan ketik, sehingga nginx menolak untuk berjalan dan situs tidak dapat diakses sampai Anda memperbaikinya:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Perbaiki kesalahan tersebut melalui chat. Uji konfigurasi dengan sudo nginx -t sebelum menyentuh service, lalu terapkan dengan reload, bukan restart. Seminggu kemudian, pada tugas yang berbeda, kesalahan yang sama terjadi lagi. Pengulangan kedua itu adalah sinyalnya.

Catat dua hal saat kegagalan masih terlihat: permintaan yang Anda ketik dan koreksi yang Anda berikan, menggunakan kata-kata yang sama seperti saat itu. Dua baris tersebut menjadi skill. Permintaan menentukan pemicu yang harus dicocokkan. Koreksi menjadi seluruh isi skill.

Panduan penulisan dari Anthropic sendiri menempatkan langkah ini sebagai langkah pertama. Jalankan agen pada tugas yang representatif tanpa skill, catat bagian yang gagal, lalu tulis instruksi minimum untuk memperbaiki kegagalan tersebut. Kegagalan adalah spesifikasinya. Karena itu, skill yang tidak dapat ditelusuri kembali ke satu kegagalan biasanya merupakan skill yang tidak dibutuhkan siapa pun.

Untuk contoh penerapan distilasi yang sama, Ponytail mengubah satu kegagalan berulang—agen menulis ulang jauh lebih banyak daripada yang Anda minta—menjadi sebuah skill dapat dibaca dari awal sampai akhir sebelum Anda menulis skill sendiri.

Anatomi skill

Skill adalah direktori yang berisi satu file wajib.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md diawali blok frontmatter, yaitu beberapa pengaturan yang ditulis dalam YAML (format konfigurasi yang sama dengan yang digunakan file Docker Compose) di antara marker ---, kemudian diikuti instruksi dalam markdown. Berikut adalah keseluruhan skill untuk kegagalan di atas.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

File tersebut berisi kurang dari dua puluh baris dan sudah merupakan skill lengkap. Bagian-bagiannya:

• name: maksimal 64 karakter, hanya boleh berisi huruf kecil, angka, dan tanda hubung, serta tidak boleh memuat kata claude atau anthropic. Dalam skill personal atau project, bagian ini hanya menjadi label tampilan. Perintah yang Anda ketik berasal dari nama direktori, sehingga skill ini dipanggil dengan /nginx-config-changes.
• description: menjelaskan fungsi skill dan kapan skill digunakan, maksimal 1.024 karakter. Baris ini menjalankan fungsi utama, dan bagian berikutnya hanya membahas hal tersebut.
• Isi: instruksi yang dimuat hanya ketika skill benar-benar aktif.
• reference/: file tambahan yang dibaca agent sesuai kebutuhan. Tautkan file tersebut dari SKILL.md dan buat tautannya hanya satu tingkat, karena file yang dirujuk dari file rujukan lain sering kali hanya dibaca sebagian.
• scripts/: file yang dijalankan agent, bukan dibaca. Hanya output-nya yang menggunakan context, sehingga script sepanjang 300 baris tidak mahal.

Lokasi direktori menentukan siapa yang dapat menggunakan skill tersebut.

• .claude/skills/<name>/SKILL.md di dalam repository: hanya untuk project ini, dan ikut tersedia bagi semua orang yang melakukan clone terhadap repo.
• ~/.claude/skills/<name>/SKILL.md: untuk setiap project di mesin Anda, tetapi tidak tersedia bagi orang lain.
• <plugin>/skills/<name>/SKILL.md: disertakan di dalam plugin dan tersedia di mana pun plugin tersebut diaktifkan.

Buat skill dengan mkdir -p .claude/skills/nginx-config-changes, lalu tulis file tersebut. Claude Code memantau direktori ini, sehingga perubahan pada skill yang sudah ada berlaku di dalam session yang sedang berjalan. Pembuatan direktori skills tingkat teratas yang belum ada ketika session dimulai memerlukan restart, karena belum ada direktori yang dapat dipantau saat session dimulai.

Kolom description adalah baris dengan dampak terbesar dalam file

Saat startup, agent memuat name dan description dari setiap skill yang tersedia ke dalam context-nya. Agent tidak memuat isi skill. Saat request Anda diterima, satu baris tersebut menjadi satu-satunya dasar untuk menentukan apakah skill ini relevan. Karena itu, isi skill yang sempurna di balik description yang samar tidak akan pernah dibaca.

Tulis description dalam bentuk orang ketiga. "Tests and reloads nginx safely" dapat digunakan. "I can help you with nginx" tidak dapat digunakan karena teks tersebut disisipkan ke system prompt. Dalam konteks itu, bentuk orang pertama terbaca seolah-olah model sedang membicarakan dirinya sendiri.

Cantumkan dua hal di dalamnya: fungsi skill dan kondisi yang membuatnya berlaku. Letakkan use case penting di awal karena Claude Code memotong entri listing setelah 1,536 karakter. Tersedia field when_to_use opsional untuk frasa pemicu tambahan dan contoh request. Field tersebut ditambahkan ke description dalam batas karakter yang sama.

Selanjutnya, gunakan kata-kata yang benar-benar akan Anda ketik. description: Helps with nginx tidak akan cocok dengan apa pun karena tidak ada orang yang mengetik "helps with". Versi sebelumnya menyebut /etc/nginx, server block, reverse proxy, dan TLS (transport layer security) certificate path. Istilah-istilah tersebut kurang lebih merupakan kosakata yang digunakan dalam request apa pun yang seharusnya memicu skill ini.

Berikut adalah pengujian untuk description. Berikan satu baris tersebut kepada seseorang yang belum pernah melihat isi skill, bersama request yang akan Anda ketik. Tanyakan apakah skill tersebut berlaku. Jika orang itu tidak dapat menentukannya, model juga tidak akan dapat menentukannya.

Jaga isi tetap ringkas karena isinya tetap berada dalam konteks

Saat sebuah skill dipanggil, konten hasil render-nya masuk ke percakapan sebagai satu pesan dan tetap berada di sana selama sisa sesi. Claude Code tidak membaca ulang file tersebut pada giliran berikutnya. Setiap baris yang Anda tulis menjadi biaya untuk seluruh sesi, bukan hanya untuk satu jawaban.

Anthropic merekomendasikan agar SKILL.md memiliki kurang dari 500 baris dan detailnya dipindahkan ke file terpisah. Compaction menunjukkan alasan angka tersebut tidak dibuat secara sembarangan. Saat percakapan diringkas untuk membebaskan konteks, Claude Code memasang kembali pemanggilan terbaru dari setiap skill, hanya mempertahankan 5,000 token pertama dari masing-masing skill, lalu mengisi batas gabungan 25,000 token mulai dari skill yang paling baru dipanggil. Skill yang panjang akan terpotong di tengah. Beberapa skill yang panjang dapat saling mengeluarkan sepenuhnya.

Jadi, tulis hanya hal yang belum diketahui model. Model sudah mengetahui apa itu nginx dan fungsi reverse proxy. Model tidak mengetahui aturan internal Anda tentang reload di atas restart. Aturan tersebut adalah satu-satunya alasan file ini ada.

Jika skill menginstruksikan agent untuk menjalankan script yang disertakan, tulis path dengan ${CLAUDE_SKILL_DIR} agar path tersebut dapat ditemukan di mana pun skill diinstal, lalu lakukan pra-persetujuan untuk perintah yang sama agar eksekusi tidak berhenti karena permintaan izin.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

Grant tersebut berlaku untuk giliran yang memanggil skill dan dihapus saat Anda mengirim pesan berikutnya. Dengan demikian, grant tidak diam-diam menjadi izin permanen.

Cara membuktikan skill aktif

Memantau pemuatan skill menunjukkan bahwa agent menemukannya. Hal itu tidak menunjukkan bahwa jawabannya berubah. Periksa keduanya dalam sesi baru, karena sesi tempat Anda menulis skill sudah menyimpan semua hal yang Anda sampaikan saat menulisnya. Konteks yang tersisa itu dapat menyamarkan kekurangan dalam file.

1. Mulai sesi baru dengan claude di project.
2. Tulis permintaan seperti yang akan Anda tulis pada hari kerja biasa, dengan kata-kata Anda sendiri, tanpa menyebut nama skill.
3. Pantau pemanggilannya. Jika skill tidak aktif, perbaiki deskripsinya. Isi skill belum menjadi masalah.
4. Panggil skill secara manual dengan /nginx-config-changes sebagai kontrol. Perilaku yang benar saat dipanggil secara manual tetapi salah saat dipanggil melalui permintaan menunjukkan masalah pemicu, bukan masalah instruksi.
5. Jalankan permintaan yang sama saat skill dinonaktifkan, lalu bandingkan kedua jawaban. Di menu /skills, sorot skill tersebut, tekan Space untuk mengubah statusnya hingga menjadi off, lalu tekan Enter untuk menyimpan. Tindakan itu menulis entri skillOverrides ke dalam .claude/settings.local.json, dan menekan Space lagi akan mengubahnya kembali menjadi on setelah selesai.
6. Tulis beberapa permintaan yang seharusnya tidak memicu skill, lalu pastikan skill tetap tidak aktif untuk permintaan tersebut.

Untuk mengotomatiskan proses itu, instal plugin skill-creator dari marketplace resmi.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Jika output instalasi menampilkan Run /reload-plugins to activate., jalankan perintah tersebut. Kemudian minta Claude mengevaluasi skill Anda berdasarkan namanya. Plugin tersebut menyimpan kasus pengujian di evals/evals.json dalam direktori skill dan menjalankan setiap kasus di subagent terpisah, sehingga setiap proses dimulai dengan konteks yang bersih. Plugin kemudian menulis perbandingan with-skill terhadap without-skill. Itulah angka yang valid: peningkatan tingkat kelulusan yang diukur terhadap token dan waktu yang digunakan skill.

Mode kegagalan: skill tidak pernah terpicu

Anda memasukkan permintaan, tetapi agent tetap melakukan tindakan lama yang salah dan tidak menampilkan baris skill. Periksa hal berikut secara berurutan.

• Deskripsi hanya menjelaskan fungsi skill, tetapi tidak pernah menjelaskan kapan skill harus digunakan. Akibatnya, tidak ada bagian dalam permintaan Anda yang cocok dengannya.
• Deskripsi tidak menggunakan kata-kata yang Anda ketik. Jika Anda mengatakan "nginx", deskripsi juga harus menyebutkan nginx.
• disable-model-invocation: true diatur dalam frontmatter. Pengaturan tersebut sepenuhnya menghapus deskripsi dari konteks model dan membuat skill hanya dapat dipanggil oleh Anda menggunakan /name.
• Glob paths dalam frontmatter membatasi aktivasi pada file yang cocok. File yang sedang Anda kerjakan tidak cocok.
• Skill berada dalam direktori .claude/skills/ bertingkat di bawah direktori awal Anda. Skill tersebut baru dimuat setelah agent membaca atau mengedit file di dalam subdirektori itu. Sebelum itu, skill sama sekali tidak tersedia.

Mode kegagalan: skill terus terpicu

Masalah sebaliknya terjadi jika deskripsinya terlalu luas sehingga skill terpicu saat mengerjakan tugas yang tidak berkaitan. "Gunakan saat bekerja pada server" cocok dengan hampir semua permintaan dalam repositori server. Isi skill kemudian dimuat untuk tugas yang tidak dapat dibantu olehnya dan tetap berada dalam konteks selama sisa sesi.

Persempit deskripsi hingga mencakup kondisi yang benar-benar relevan, lalu sebutkan file atau perintah yang dicakupnya. Tambahkan glob paths jika skill hanya berlaku untuk file tertentu. Untuk tindakan yang memiliki efek samping, seperti deploy atau commit, tetapkan disable-model-invocation: true dan panggil skill tersebut sendiri menggunakan /name agar agent tidak memutuskan sendiri bahwa saat itu merupakan waktu yang tepat untuk melakukan deploy.

Mode kegagalan: aturan tersebut seharusnya berada dalam file rules

File rules seperti CLAUDE.md atau AGENTS.md dimuat pada awal setiap sesi dan berlaku untuk setiap tugas. Isi skill hanya dimuat ketika skill tersebut aktif. Frekuensi menjadi satu-satunya dasar pengambilan keputusan. Fakta yang berlaku untuk setiap tugas dalam repository, seperti package manager yang digunakan, seharusnya berada dalam file rules. Prosedur yang hanya berlaku untuk sebagian kecil tugas, seperti aturan nginx di atas, seharusnya berada dalam skill. Dengan demikian, prosedur tersebut tidak menambah beban pada hari ketika tidak ada yang mengedit nginx.

Kesalahan sebenarnya adalah menempatkannya di kedua tempat. Dua salinan dapat berbeda seiring waktu. Ketika agent melakukan tindakan yang salah, Anda tidak dapat mengetahui salinan mana yang diikutinya. Tentukan satu tempat untuk setiap instruksi. batas antara skill, server MCP, dan file rules membahas kasus yang lebih sulit, termasuk ketika jawaban yang tepat adalah server MCP (model context protocol) yang memberikan tool baru kepada agent, bukan instruksi baru.

Bagikan setelah terbukti bermanfaat

Skill yang mampu bertahan selama satu minggu pekerjaan nyata layak di-commit. Project skill di .claude/skills/ ditinjau seperti kode dan disertakan bersama repository, sehingga rekan satu tim yang melakukan clone akan mendapatkan perbaikan Anda tanpa langkah penyiapan tambahan. Memindahkan skill antar-repository tanpa copy dan paste merupakan masalah tersendiri, yang dibahas dalam cara membagikan agent skill antar-repository.

Ada satu catatan tentang portabilitas. Claude Code menerima banyak field frontmatter, tetapi standar Agent Skills hanya mengizinkan enam: name, description, license, compatibility, metadata dan allowed-tools. Jika Anda mengunggah skill ke claude.ai atau mengemasnya untuk Skills API dengan field lain di dalam frontmatter, proses tersebut langsung gagal, bukan mengabaikan field itu:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Gunakan hanya enam field tersebut agar file yang sama dapat dimuat di Claude Code dan di semua sistem lain yang membaca standar tersebut. Menulis instruksinya agar tetap berfungsi saat dipindahkan ke model lain merupakan pekerjaan terpisah, dan menulis skill yang berfungsi dengan model apa pun membahasnya.

FAQ

Seberapa panjang file SKILL.md seharusnya?

Batasi panjangnya hingga kurang dari 500 baris. Sebagian besar skill yang berguna biasanya jauh lebih pendek. Isi file dimasukkan ke dalam percakapan saat skill dipanggil dan tetap berada di sana selama sisa sesi. Karena itu, setiap baris menjadi biaya berulang, bukan biaya satu kali. Pindahkan materi referensi yang panjang ke file terpisah di direktori skill, lalu tautkan file tersebut dari SKILL.md dengan kedalaman satu tingkat. Dengan demikian, agent hanya membacanya saat diperlukan. Script yang disertakan akan dieksekusi, bukan dibaca, sehingga biayanya hanya berasal dari output script tersebut.

Mengapa skill saya tidak pernah dipicu?

Penyebab yang paling umum adalah deskripsi. Deskripsi merupakan satu-satunya bagian skill yang berada dalam context saat model mengambil keputusan. Pastikan deskripsi menjelaskan kapan skill harus digunakan, bukan hanya fungsinya. Pastikan juga deskripsi memuat kata-kata yang benar-benar Anda ketik dalam permintaan. Jika deskripsinya sudah benar, periksa frontmatter untuk mencari disable-model-invocation: true, yang sepenuhnya menyembunyikan skill dari model. Periksa juga glob paths yang membatasi skill hanya pada file yang tidak sedang Anda akses. Skill di dalam direktori .claude/skills/ bertingkat di bawah direktori awal juga dapat menjadi penyebab. Skill tersebut baru dimuat setelah agent membaca atau mengedit file di subdirektori tersebut.

Apakah ini sebaiknya menjadi skill atau baris dalam file aturan saya?

Tentukan berapa banyak tugas yang menerapkannya. File aturan dimuat pada setiap sesi. Karena itu, file tersebut sebaiknya berisi fakta yang berlaku untuk setiap tugas, seperti package manager atau konvensi penamaan branch. Skill hanya dimuat saat dipicu. Jadi, skill cocok untuk prosedur yang hanya diperlukan pada sebagian kecil tugas. Jangan menulis instruksi yang sama di kedua tempat. Kedua salinan tersebut dapat berubah dan Anda akan kehilangan kemampuan untuk mengetahui salinan mana yang diikuti agent.

Bagaimana saya tahu bahwa skill benar-benar membantu?

Bandingkan hasilnya dengan baseline. Kumpulkan beberapa permintaan nyata. Jalankan setiap permintaan dalam sesi baru saat skill tersedia. Setelah itu, jalankan kembali permintaan tersebut dengan skill dinonaktifkan dari menu /skills, lalu baca kedua jawaban secara berdampingan. Sesi baru penting karena percakapan tempat Anda menulis skill masih berisi penjelasan Anda. Hal ini dapat membuat file yang belum lengkap terlihat lengkap. Plugin skill-creator menjalankan perbandingan ini untuk Anda dan melaporkan tingkat keberhasilan di sebelah biaya token.

Apakah saya dapat menggunakan SKILL.md yang sama dengan agent lain?

Ya, selama Anda tetap menggunakan field yang ditetapkan oleh standar Agent Skills: name, description, license, compatibility, metadata, dan allowed-tools. Claude Code menerima lebih banyak field. Claude Code juga mendukung fitur dalam body, seperti injeksi perintah shell, yang tidak dijalankan oleh tool lain. Pengunggahan skill dengan field di luar standar akan gagal dan menampilkan error eksplisit yang mencantumkan properti yang diizinkan. Karena itu, tentukan sejak awal apakah skill hanya akan digunakan di Claude Code atau akan digunakan lintas tool.