Cara Membuat Skill Agent dari Kegagalan Nyata

Tulis skill agent Anda sendiri dari satu kegagalan nyata

Cara terbaik untuk menulis skill agent Anda sendiri adalah mengekstraknya dari satu kegagalan nyata. Temukan tugas yang dua kali ditangani secara keliru 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, semuanya hanya mekanisme: struktur 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 diekstrak dari kegagalan yang Anda saksikan sudah memiliki pengujian: ajukan permintaan yang sama lagi dan lihat apakah agent dapat menanganinya dengan benar kali ini. Jika format tersebut 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 dikerjakan agen secara keliru

Sekali bisa terjadi karena kebetulan. Dua kali menunjukkan pola, dan pola layak dicatat 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 start 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.

Anda memperbaikinya 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. Kejadian kedua itulah sinyalnya.

Catat dua hal saat kegagalan tersebut masih terlihat di hadapan Anda: permintaan yang Anda ketik dan koreksi yang Anda berikan, menggunakan kata-kata yang Anda pakai. Kedua baris tersebut menjadi skill. Permintaan menentukan pemicu yang harus dicocokkan. Koreksi menjadi seluruh isinya.

Panduan penulisan dari Anthropic sendiri menempatkan langkah ini sebagai prioritas pertama. Jalankan agen pada tugas yang representatif tanpa skill, catat bagian yang gagal, lalu tulis instruksi minimum yang 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, baca Ponytail mengubah satu kegagalan berulang—agen yang menulis ulang jauh lebih banyak daripada yang Anda minta—menjadi sebuah skill dari awal hingga akhir sebelum menulis skill Anda 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 dengan blok frontmatter, yaitu beberapa pengaturan yang ditulis dalam YAML (format konfigurasi yang sama seperti yang digunakan file Docker Compose) di antara penanda ---, lalu diikuti instruksi dalam markdown. Berikut adalah keseluruhan skill untuk kegagalan tersebut.

---
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. Komponennya:

• name: maksimal 64 karakter, hanya boleh berisi huruf kecil, digit, dan tanda hubung, serta tidak boleh memuat kata claude atau anthropic. Pada skill pribadi atau proyek, 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 saat skill benar-benar dijalankan.
• reference/: file tambahan yang dibaca agen sesuai kebutuhan. Tautkan file tersebut dari SKILL.md dan pertahankan tautan pada kedalaman satu tingkat, karena file yang dirujuk dari file rujukan lain sering kali hanya dibaca sebagian.
• scripts/: file yang dijalankan agen, bukan dibaca. Hanya output-nya yang menggunakan konteks, sehingga skrip 300 baris tetap ringan.

Skill berkembang menjadi struktur lengkap ketika perilaku yang diperbaikinya cukup sulit sehingga memerlukannya. Skill unlazy menggunakan ruang tersebut untuk Depth Tree, kumpulan file gates, dan kontrak PLAN.md agar agen tidak menyatakan pekerjaannya selesai ketika seluruh cabang pekerjaan masih belum ditangani.

Lokasi direktori menentukan siapa yang memperoleh skill tersebut.

• .claude/skills/<name>/SKILL.md di repositori: hanya untuk proyek ini, dan ikut tersedia bagi semua orang yang melakukan clone repositori.
• ~/.claude/skills/<name>/SKILL.md: untuk setiap proyek 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 sesi yang sedang berjalan. Jika Anda membuat direktori skills tingkat teratas yang belum ada saat sesi dimulai, Anda perlu memulai ulang sesi, karena belum ada direktori yang dapat dipantau ketika sesi 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. Ketika 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 pernah dibaca.

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

Cantumkan dua hal di dalamnya: fungsi skill dan kondisi penerapannya. Letakkan use case penting di awal karena Claude Code memotong entri listing pada 1,536 karakter. Tersedia kolom when_to_use opsional untuk frasa pemicu tambahan dan contoh request. Kolom ini ditambahkan ke description dalam batas yang sama.

Selanjutnya, gunakan kata-kata yang benar-benar akan Anda ketik. description: Helps with nginx tidak cocok dengan apa pun karena tidak ada orang yang mengetik "helps with". Versi di atas menyebut /etc/nginx, server block, reverse proxy, dan TLS (transport layer security) certificate path. Itu kurang lebih merupakan kosakata dari setiap request yang seharusnya memicunya.

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.

Pertahankan isi tetap singkat 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 menyarankan agar SKILL.md berisi kurang dari 500 baris dan detail dipindahkan ke file terpisah. Proses compaction menjelaskan alasan angka tersebut. Saat percakapan diringkas untuk mengosongkan konteks, Claude Code melampirkan kembali pemanggilan terbaru dari setiap skill, mempertahankan hanya 5,000 token pertama dari masing-masing skill, lalu mengisi anggaran gabungan sebesar 25,000 token dengan memulai 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 agen untuk menjalankan skrip yang disertakan, tulis path dengan ${CLAUDE_SKILL_DIR} agar path tersebut dapat ditemukan di mana pun skill diinstal, lalu setujui perintah yang sama terlebih dahulu agar proses 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 *)
---

Pemberian izin tersebut mencakup giliran yang memanggil skill dan dihapus saat Anda mengirim pesan berikutnya. Dengan demikian, izin tersebut tidak diam-diam menjadi izin permanen.

Cara membuktikan skill aktif

Memantau pemuatan skill hanya menunjukkan bahwa agent menemukannya. Hal itu tidak menunjukkan bahwa jawabannya berubah. Periksa keduanya, dan lakukan pemeriksaan dalam sesi baru, karena sesi tempat Anda menulis skill sudah menyimpan semua hal yang Anda katakan saat menulisnya. Konteks yang tersisa tersebut dapat menyembunyikan kekurangan dalam file.

1. Mulai sesi baru dengan claude di project.
2. Ketik permintaan seperti yang biasa Anda lakukan pada hari kerja, menggunakan kata-kata Anda sendiri dan 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, mengonfirmasi bahwa masalahnya ada pada trigger, bukan pada instruksi.
5. Jalankan permintaan yang sama dengan skill dinonaktifkan, lalu bandingkan kedua jawaban. Di menu /skills, sorot skill tersebut, tekan Space untuk mengubah statusnya ke off, lalu tekan Enter untuk menyimpan. Tindakan itu menulis entri skillOverrides ke dalam .claude/settings.local.json. Setelah selesai, tekan Space lagi untuk mengubah statusnya kembali ke on.
6. Tulis beberapa permintaan yang seharusnya tidak mengaktifkan skill, lalu periksa bahwa skill tetap tidak aktif untuk permintaan tersebut.

Untuk mengotomatiskan siklus tersebut, 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 masing-masing, sehingga setiap proses dimulai dengan konteks yang bersih. Plugin kemudian menulis perbandingan with-skill terhadap without-skill. Inilah angka yang lebih akurat: peningkatan tingkat kelulusan yang diukur terhadap token dan waktu yang digunakan skill.

Skill juga dapat menyertakan pembuktiannya sendiri, alih-alih menyerahkannya kepada proses eval terpisah. Itulah yang dilakukan skill Old Coder ketika meminta agent mengembalikan laporan bukti yang dapat Anda jalankan ulang sendiri.

Mode kegagalan: skill tidak pernah aktif

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

• Deskripsi menjelaskan fungsi skill, tetapi tidak pernah menyatakan kapan skill tersebut harus digunakan. Akibatnya, tidak ada bagian dalam permintaan Anda yang cocok dengannya.
• Deskripsi menghindari kata-kata yang Anda gunakan. Jika Anda mengatakan "nginx", deskripsi juga harus menyebutkan nginx.
• disable-model-invocation: true ditetapkan dalam frontmatter. Ini membuat deskripsi tidak dimuat ke dalam konteks model dan menyebabkan 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 tidak tersedia sama sekali.

Mode kegagalan: skill terus terpicu

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

Persempit deskripsi hingga mencakup kondisi yang benar-benar penting, lalu sebutkan file atau perintah yang dicakupnya. Tambahkan glob paths jika skill hanya berlaku untuk file tertentu. Untuk tindakan apa pun yang menimbulkan efek samping, seperti deploy atau commit, tetapkan disable-model-invocation: true dan panggil sendiri dengan /name agar agent tidak memutuskan sendiri bahwa sekarang adalah waktu yang tepat untuk melakukan deploy.

Mode kegagalan: skill seharusnya berada di rules file

Rules file seperti CLAUDE.md atau AGENTS.md dimuat pada awal setiap sesi dan berlaku untuk setiap tugas. Isi skill hanya dimuat ketika skill tersebut dipicu. Frekuensi menjadi penentu utama. Fakta yang berlaku untuk setiap tugas di repository, seperti package manager yang digunakan, seharusnya berada di rules file. Prosedur yang hanya berlaku pada sebagian kecil tugas, seperti aturan nginx di atas, seharusnya berada di skill, karena tidak menimbulkan beban pada hari ketika tidak ada yang mengedit nginx.

Kegagalan yang sebenarnya adalah menempatkannya di kedua tempat. Dua salinan dapat berbeda, dan ketika agent melakukan hal yang salah, Anda tidak dapat mengetahui salinan mana yang diikutinya. Tentukan satu tempat untuk setiap instruksi. Aturan yang sudah berada tepat di satu tempat tetapi tetap diabaikan merupakan masalah yang berbeda, dan mekanisme di balik instruksi yang diabaikan perlu diperiksa sebelum Anda memindahkannya ke skill dengan harapan pemindahan tersebut akan memperbaiki masalah. batas antara skill, MCP server, dan rules file membantu menangani kasus yang lebih sulit, termasuk ketika jawaban yang tepat adalah MCP (model context protocol) server yang memberikan tool baru kepada agent, bukan instruksi baru.

Bagikan setelah terbukti berguna

Skill yang tetap berguna setelah digunakan selama satu minggu dalam pekerjaan nyata layak di-commit. Skill proyek dalam .claude/skills/ ditinjau seperti kode dan disertakan bersama repository, sehingga rekan kerja 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 skills antar-repository.

Satu catatan tentang portabilitas. Claude Code menerima daftar panjang 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 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 keenam field tersebut agar file yang sama dapat dimuat di Claude Code dan di semua perangkat lunak lain yang membaca standar tersebut. Tempat file dimuat tetap menentukan hal yang dapat dilakukannya, karena Cowork berjalan dalam sandbox Anthropic, sedangkan Claude Code berjalan di mesin atau VPS Anda sendiri. Oleh karena itu, skill nginx di atas layak dibawa ke checkout rekan kerja, tetapi tidak berguna dalam sandbox yang tidak dapat menjangkau server. Menulis instruksi agar tetap berfungsi ketika 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, dan 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 dalam direktori skill, lalu tautkan file tersebut dari SKILL.md dengan kedalaman satu tingkat. Dengan begitu, agent hanya membacanya saat diperlukan. Script yang disertakan akan dieksekusi, bukan dibaca, sehingga hanya output-nya yang menambah biaya.

Mengapa skill saya tidak pernah terpicu?

Penyebab yang paling umum adalah deskripsi, karena hanya bagian tersebut yang tersedia dalam konteks saat model mengambil keputusan. Pastikan deskripsi menjelaskan kapan skill harus digunakan, bukan hanya fungsinya, dan mencantumkan kata-kata yang benar-benar Anda ketik dalam permintaan. Jika deskripsinya sudah benar, periksa frontmatter untuk disable-model-invocation: true, yang sepenuhnya menyembunyikan skill dari model, serta glob paths yang membatasi skill pada file yang tidak sedang Anda ubah. Skill dalam direktori .claude/skills/ bertingkat di bawah direktori awal juga dapat menjadi penyebab. Skill tersebut baru dimuat setelah agent membaca atau mengubah file dalam subdirektori itu.

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

Pertimbangkan berapa banyak tugas Anda yang menerapkannya. File aturan dimuat dalam setiap sesi, sehingga isinya harus berupa fakta yang berlaku untuk semua tugas, seperti package manager atau konvensi penamaan branch. Skill hanya dimuat saat terpicu, sehingga cocok untuk prosedur yang relevan pada sebagian kecil tugas. Jangan menulis instruksi yang sama di kedua tempat. Kedua salinan tersebut dapat berubah secara tidak sinkron, dan Anda tidak dapat lagi mengetahui salinan mana yang diikuti agent.

Bagaimana saya mengetahui bahwa skill benar-benar membantu?

Bandingkan hasilnya dengan baseline. Kumpulkan beberapa permintaan nyata, jalankan masing-masing dalam sesi baru dengan skill tersedia, lalu jalankan kembali dengan skill dinonaktifkan dari menu /skills. Setelah itu, baca kedua jawaban secara berdampingan. Sesi baru penting karena percakapan tempat Anda menulis skill masih berisi penjelasan Anda, sehingga file yang tidak lengkap dapat terlihat seolah-olah sudah lengkap. Plugin skill-creator menjalankan perbandingan ini untuk Anda dan melaporkan tingkat keberhasilan di samping biaya token.

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

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