Cara Tulis Kemahiran Ejen Sendiri Dengan Berkesan

Tulis kemahiran ejen anda sendiri daripada satu kegagalan sebenar

Cara terbaik untuk menulis kemahiran ejen anda sendiri adalah dengan menyaringnya daripada satu kegagalan sebenar. Cari tugasan yang dilakukan dengan salah oleh ejen pengekodan anda sebanyak dua kali, tulis pembetulan yang anda taip pada kedua-dua kali tersebut, dan simpan pembetulan itu sebagai fail SKILL.md yang boleh dimuatkan oleh ejen itu sendiri. Segala-galanya selepas itu hanyalah mekanik: susun atur fail, dan satu baris yang menentukan sama ada kemahiran itu akan diaktifkan atau tidak.

Urutan itu penting. Kemahiran yang ditulis berdasarkan imaginasi mendokumentasikan masalah yang tidak pernah anda alami, dan ia tetap memakan ruang konteks dalam setiap sesi. Kemahiran yang disaring daripada kegagalan yang anda perhatikan hadir bersama ujiannya sendiri: tanya perkara yang sama sekali lagi, dan lihat sama ada ejen itu melakukannya dengan betul kali ini. Jika format itu sendiri baharu bagi anda, baca apakah kemahiran ejen dan bagaimana ejen memuatkannya terlebih dahulu, kemudian kembali dan tulis satu.

Mulakan daripada tugasan yang ejen lakukan dengan salah sebanyak dua kali

Sekali adalah kebetulan. Dua kali adalah corak, dan corak itu wajar dijadikan fail.

Berikut adalah kegagalan yang berulang pada pelayan sebenar. Anda meminta ejen menambah blok reverse proxy pada nginx. Ia menyunting /etc/nginx/conf.d/app.conf, kemudian menjalankan sudo systemctl restart nginx. Suntingan tersebut mempunyai ralat taip, jadi nginx enggan bermula, dan laman web tergendala sehingga anda membaikinya:

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 membetulkannya dalam sembang. Uji konfigurasi dengan sudo nginx -t sebelum menyentuh servis, kemudian gunakannya dengan reload dan bukannya restart. Seminggu kemudian, pada tugasan yang berbeza, kesilapan yang sama berulang. Kali kedua itu adalah isyaratnya.

Tuliskan dua perkara semasa kegagalan itu masih di depan mata anda: permintaan yang anda taip, dan pembetulan yang anda berikan, menggunakan perkataan anda sendiri. Dua baris itu menjadi kemahiran. Permintaan tersebut memberitahu anda apa yang perlu dipadankan oleh pencetus (trigger). Pembetulan itu adalah kandungan keseluruhannya.

Panduan penulisan Anthropic sendiri meletakkan perkara ini di tempat pertama. Jalankan ejen pada tugasan wakilan tanpa kemahiran, rekod di mana ia gagal, kemudian tulis arahan minimum yang membaiki kegagalan tersebut. Kegagalan itu adalah spesifikasi, jadi kemahiran yang anda tidak dapat jejak kembali kepada satu kegagalan biasanya merupakan kemahiran yang tidak diperlukan oleh sesiapa pun.

Untuk contoh kerja bagi penyulingan yang sama, Ponytail menukar satu kegagalan berulang, iaitu ejen yang menulis semula lebih banyak daripada yang anda minta, menjadi satu kemahiran anda boleh membacanya dari awal hingga akhir sebelum menulis kemahiran anda sendiri.

Anatomi sesuatu skill

Sesuatu skill ialah direktori yang mengandungi satu fail wajib di dalamnya.

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

SKILL.md bermula dengan blok frontmatter, iaitu beberapa tetapan yang ditulis dalam YAML (format konfigurasi yang sama digunakan oleh fail Docker Compose) di antara penanda ---, diikuti dengan arahan dalam markdown. Berikut adalah keseluruhan skill bagi 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).

Fail tersebut kurang daripada dua puluh baris dan ia merupakan satu skill yang lengkap. Bahagian-bahagiannya:

• name: sehingga 64 aksara, hanya huruf kecil, digit dan tanda sempang, serta tidak boleh mengandungi perkataan claude atau anthropic. Dalam skill peribadi atau projek, ini hanyalah label paparan. Perintah yang anda taip datang daripada nama direktori, jadi yang ini bertindak balas kepada /nginx-config-changes.
• description: fungsi skill tersebut dan bila untuk menggunakannya, sehingga 1,024 aksara. Baris ini melakukan kerja sebenar, dan bahagian seterusnya adalah khusus mengenai perkara ini.
• Bahagian badan: arahan-arahan, yang dimuatkan hanya apabila skill tersebut benar-benar dijalankan.
• reference/: fail tambahan yang dibaca oleh ejen apabila diminta. Pautkan fail tersebut daripada SKILL.md dan pastikan pautan tersebut hanya sedalam satu tahap, kerana fail yang dirujuk daripada fail lain yang turut dirujuk sering kali hanya dibaca sebahagian sahaja.
• scripts/: fail yang dilaksanakan oleh ejen dan bukannya dibaca. Hanya outputnya yang menggunakan kos konteks, jadi skrip sepanjang 300 baris adalah murah.

Sesuatu skill akan berkembang menjadi susun atur penuh apabila tingkah laku yang diperbetulkannya cukup degil sehingga memerlukannya, dan skill yang tidak malas menggunakan ruang tersebut untuk Depth Tree, satu set fail gates dan kontrak PLAN.md bagi menghalang ejen daripada mengumumkan kerja selesai sedangkan keseluruhan cabang kerja masih belum disentuh.

Lokasi anda meletakkan direktori tersebut menentukan siapa yang mendapat akses kepada skill itu.

• .claude/skills/<name>/SKILL.md dalam repositori: hanya untuk projek ini, dan ia akan disertakan kepada sesiapa sahaja yang melakukan clone terhadap repo tersebut.
• ~/.claude/skills/<name>/SKILL.md: setiap projek pada mesin anda, dan tidak melibatkan orang lain.
• <plugin>/skills/<name>/SKILL.md: dihantar di dalam plugin, tersedia di mana-mana sahaja plugin tersebut diaktifkan.

Cipta satu dengan mkdir -p .claude/skills/nginx-config-changes dan tulis fail tersebut. Claude Code memantau direktori-direktori ini, jadi menyunting skill sedia ada akan berkuat kuasa di dalam sesi yang sedang berjalan. Mencipta direktori skills peringkat atasan yang tidak wujud semasa sesi bermula memerlukan permulaan semula (restart), kerana tiada apa yang dipantau apabila sesi tersebut bermula.

Medan perihalan ialah baris paling berkesan dalam fail tersebut

Semasa permulaan, ejen memuatkan name dan description bagi setiap kemahiran yang tersedia ke dalam konteksnya. Ia tidak memuatkan bahagian badan. Apabila permintaan anda tiba, baris tunggal itu menjadi asas keseluruhan untuk menentukan sama ada kemahiran ini relevan, jadi badan yang sempurna di sebalik perihalan yang samar tidak akan dibaca.

Tulis perihalan dalam orang ketiga. "Menguji dan memuat semula nginx dengan selamat" adalah berkesan. "Saya boleh membantu anda dengan nginx" tidak berkesan, kerana teks tersebut disuntik ke dalam prompt sistem, di mana orang pertama dibaca sebagai model yang bercakap tentang dirinya sendiri.

Sertakan dua perkara di dalamnya: perkara yang dilakukan oleh kemahiran tersebut, dan syarat yang membolehkannya digunakan. Letakkan kes penggunaan penting di hadapan, kerana Claude Code memotong entri penyenaraian pada 1,536 aksara. Terdapat medan when_to_use pilihan untuk frasa pencetus tambahan dan contoh permintaan, dan ia dilampirkan pada perihalan di bawah had yang sama.

Kemudian gunakan perkataan yang akan anda taip sebenarnya. description: Helps with nginx tidak memadankan apa-apa, kerana tiada siapa yang menaip "membantu dengan". Versi di atas menamakan /etc/nginx, server block, reverse proxy dan TLS (transport layer security) certificate path, yang secara kasarnya merupakan kosa kata bagi mana-mana permintaan yang sepatutnya mencetuskannya.

Berikut ialah ujian untuk perihalan. Berikan baris tunggal itu kepada seseorang yang tidak pernah melihat bahagian badan, bersama-sama dengan permintaan yang anda akan taip, dan tanya mereka sama ada kemahiran itu terpakai. Jika mereka tidak dapat menentukannya, model tersebut juga tidak akan dapat.

Pastikan badan kandungan kecil kerana ia kekal dalam konteks

Apabila sesuatu kemahiran (skill) dipanggil, kandungan yang dijana akan masuk ke dalam perbualan sebagai satu mesej dan kekal di situ sepanjang sesi. Claude Code tidak membaca semula fail tersebut pada pusingan seterusnya. Setiap baris yang anda tulis adalah kos yang anda bayar untuk keseluruhan sesi, bukan untuk satu jawapan sahaja.

Anthropic mengesyorkan agar SKILL.md dikekalkan di bawah 500 baris dan memindahkan perincian ke dalam fail berasingan. Pemadatan (compaction) menunjukkan sebab angka tersebut tidak ditetapkan secara sewenang-wenangnya. Apabila perbualan diringkaskan untuk mengosongkan konteks, Claude Code akan melampirkan semula panggilan terbaharu bagi setiap kemahiran, mengekalkan hanya 5,000 token pertama bagi setiap satu, dan mengisi bajet gabungan 25,000 token bermula daripada kemahiran yang paling baru dipanggil. Kemahiran yang panjang akan terpotong di tengah jalan. Beberapa kemahiran yang panjang akan menyebabkan satu sama lain disingkirkan sepenuhnya.

Oleh itu, tulis hanya perkara yang belum diketahui oleh model. Ia sudah mengetahui apa itu nginx dan fungsi reverse proxy. Ia tidak mengetahui peraturan dalaman anda tentang reload berbanding restart, dan peraturan itulah satu-satunya sebab fail ini wujud.

Jika kemahiran tersebut mengarahkan ejen untuk menjalankan skrip yang dibundel, namakan laluan tersebut dengan ${CLAUDE_SKILL_DIR} supaya ia dapat diselesaikan di mana sahaja kemahiran itu dipasang, dan pra-luluskan (pre-approve) arahan yang sama supaya proses larian tidak terhenti pada gesaan kebenaran.

---
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 kebenaran (grant) meliputi pusingan yang memanggil kemahiran tersebut dan akan dibersihkan apabila anda menghantar mesej seterusnya, jadi ia tidak akan menjadi kebenaran kekal secara senyap.

Cara membuktikan kemahiran diaktifkan

Memerhati kemahiran dimuatkan memberitahu anda bahawa ejen telah menemuinya. Ia tidak memberitahu anda sama ada jawapan telah berubah. Semak kedua-duanya, dan semak dalam sesi baharu, kerana sesi tempat anda menulis kemahiran tersebut sudah menyimpan semua yang anda katakan semasa menulisnya. Konteks yang tertinggal itu menyembunyikan kelompangan dalam fail.

1. Mulakan sesi baharu dengan claude dalam projek tersebut.
2. Taip permintaan seperti yang anda lakukan pada hari kerja biasa, dengan kata-kata anda sendiri, tanpa menyebut nama kemahiran.
3. Perhatikan pengaktifannya. Jika kemahiran tidak diaktifkan, betulkan deskripsinya. Bahagian kandungan (body) belum menjadi masalahnya lagi.
4. Aktifkan secara manual dengan /nginx-config-changes sebagai kawalan. Tingkah laku yang betul apabila diaktifkan secara manual dan tingkah laku yang salah apabila diaktifkan melalui permintaan mengesahkan masalah pencetus (trigger) dan bukannya masalah arahan.
5. Jalankan permintaan yang sama dengan kemahiran dimatikan dan bandingkan kedua-dua jawapan. Dalam menu /skills, sorot kemahiran tersebut, tekan Space untuk menukar statusnya kepada off, kemudian Enter untuk menyimpan. Tindakan itu menulis entri skillOverrides ke dalam .claude/settings.local.json, dan menekan Space sekali lagi akan menukarnya kembali kepada on apabila anda selesai.
6. Tulis beberapa permintaan yang tidak sepatutnya mencetuskan kemahiran tersebut, dan pastikan ia kekal tidak aktif bagi permintaan tersebut.

Untuk mengautomasikan gelung tersebut, pasang pemalam skill-creator daripada gedung rasmi.

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

Jika output pemasangan menyatakan Run /reload-plugins to activate., jalankan arahan tersebut. Kemudian minta Claude menilai kemahiran anda mengikut nama. Pemalam tersebut menyimpan kes ujian dalam evals/evals.json di dalam direktori kemahiran dan menjalankan setiap kes dalam subejennya sendiri, jadi setiap larian bermula dengan konteks yang bersih. Ia kemudian menulis perbandingan antara dengan-kemahiran dan tanpa-kemahiran, yang merupakan angka yang tepat: peningkatan kadar lulus yang diukur berdasarkan token dan masa yang diambil oleh kemahiran tersebut.

Sesuatu kemahiran juga boleh membawa bukti sendiri dan tidak perlu bergantung pada larian penilaian berasingan, itulah yang dilakukan oleh kemahiran Old Coder apabila ia membuat ejen menyerahkan laporan bukti yang boleh anda jalankan semula sendiri.

Mod kegagalan: skill tidak dicetuskan

Anda menaip permintaan, ejen melakukan tindakan lama yang salah, dan tiada baris skill muncul. Selesaikan perkara ini mengikut urutan.

• Deskripsi menyatakan fungsi skill tetapi tidak menyatakan bila untuk menggunakannya, jadi tiada apa-apa dalam permintaan anda yang sepadan dengannya.
• Deskripsi tidak mengandungi perkataan yang anda taip. Jika anda menyebut "nginx", deskripsi tersebut mestilah mengandungi perkataan nginx.
• disable-model-invocation: true ditetapkan dalam frontmatter. Ini menghalang deskripsi daripada dimasukkan ke dalam konteks model sepenuhnya, dan menyebabkan skill hanya boleh dipanggil oleh anda menggunakan /name.
• Glob paths dalam frontmatter mengehadkan pengaktifan kepada fail yang sepadan, dan fail yang sedang anda kerjakan tidak sepadan.
• Skill tersebut berada dalam direktori .claude/skills/ bersarang di bawah direktori permulaan anda. Direktori tersebut hanya dimuatkan selepas ejen membaca atau menyunting fail di dalam subdirektori itu, jadi sehingga itu, skill tersebut tidak tersedia sama sekali.

Mod kegagalan: kemahiran tercetus secara berterusan

Masalah sebaliknya ialah deskripsi yang terlalu luas sehingga kemahiran tersebut tercetus pada kerja yang tidak berkaitan. "Gunakan semasa bekerja pada pelayan" sepadan dengan hampir semua permintaan dalam repositori pelayan. Badan kemahiran kemudian dimuatkan pada tugasan yang tidak dapat dibantunya, dan ia kekal dalam konteks untuk sepanjang sesi tersebut.

Sempitkan deskripsi kepada syarat yang benar-benar penting, dan namakan fail atau perintah yang diliputi olehnya. Tambahkan paths glob apabila kemahiran hanya terpakai pada fail tertentu. Untuk sebarang tindakan yang mempunyai kesan sampingan, seperti deploy atau commit, tetapkan disable-model-invocation: true dan panggil sendiri dengan /name, supaya ejen tidak membuat keputusan sendiri bahawa sekarang adalah masa yang sesuai untuk melakukan deploy.

Mod kegagalan: kemahiran tersebut sepatutnya berada dalam fail peraturan anda

Fail peraturan seperti CLAUDE.md atau AGENTS.md dimuatkan pada permulaan setiap sesi dan digunakan untuk setiap tugasan. Badan kemahiran hanya dimuatkan apabila kemahiran tersebut dicetuskan. Kekerapan adalah penentu utama. Fakta yang terpakai untuk setiap tugasan dalam repositori, seperti pengurus pakej yang anda gunakan, sepatutnya diletakkan dalam fail peraturan. Prosedur yang hanya terpakai untuk sebahagian kecil tugasan, seperti peraturan nginx di atas, sepatutnya diletakkan dalam kemahiran, di mana ia tidak memakan sumber pada hari tiada sesiapa pun menyunting nginx.

Kegagalan sebenar adalah meletakkannya di kedua-dua tempat. Dua salinan akan menjadi tidak selaras, dan apabila ejen melakukan tindakan yang salah, anda tidak dapat menentukan salinan mana yang diikuti. Pilih satu lokasi untuk setiap arahan. Peraturan yang sudah berada di satu lokasi yang tepat tetapi masih diabaikan adalah masalah yang berbeza, dan mekanisme di sebalik arahan yang diabaikan wajar diperiksa sebelum anda memindahkannya ke dalam kemahiran dengan harapan pemindahan tersebut menyelesaikan masalah. sempadan antara kemahiran, pelayan MCP dan fail peraturan membincangkan kes-kes yang lebih rumit, termasuk apabila jawapan yang tepat ialah pelayan MCP (model context protocol) yang memberikan ejen alat baharu dan bukannya arahan baharu.

Kongsi setelah ia terbukti berbaloi

Kemahiran yang bertahan selepas seminggu kerja sebenar adalah berbaloi untuk dikekalkan. Kemahiran projek dalam .claude/skills/ disemak seperti kod dan disertakan bersama repositori, jadi rakan sepasukan yang melakukan clone akan mendapat pembetulan anda tanpa perlu langkah penyediaan tambahan. Memindahkan kemahiran antara repositori tanpa perlu menyalin dan menampal adalah masalah tersendiri, yang dibincangkan dalam cara berkongsi kemahiran ejen merentas repositori.

Satu nota mengenai kebolehalihtanganan. Claude Code menerima senarai medan frontmatter yang panjang, tetapi standard Agent Skills hanya membenarkan enam: name, description, license, compatibility, metadata dan allowed-tools. Jika anda memuat naik kemahiran ke claude.ai, atau membungkusnya untuk Skills API, dengan menyertakan medan lain dalam frontmatter, ia akan gagal serta-merta dan bukannya mengabaikan medan tersebut:

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

Kekal dalam lingkungan enam medan tersebut dan fail yang sama akan dimuatkan dalam Claude Code serta dalam mana-mana sistem lain yang membaca standard tersebut. Lokasi fail dimuatkan tetap menentukan perkara yang boleh dilakukannya, kerana Cowork berjalan dalam sandbox Anthropic manakala Claude Code berjalan pada mesin atau VPS anda sendiri, jadi kemahiran nginx di atas berbaloi untuk dibawa ke direktori rakan sepasukan tetapi tidak berguna dalam sandbox yang tidak boleh mencapai pelayan tersebut. Menulis arahan itu sendiri supaya ia boleh digunakan apabila dipindahkan ke model yang berbeza adalah tugas yang berasingan, dan menulis kemahiran yang berfungsi dengan mana-mana model membincangkan perkara ini.

FAQ

Berapakah panjang fail SKILL.md yang sepatutnya?

Pastikan ia di bawah 500 baris, dan jangkakan kebanyakan kemahiran yang berguna adalah jauh lebih pendek daripada itu. Kandungan fail ini akan dimasukkan ke dalam perbualan apabila kemahiran tersebut dipanggil dan kekal di sana sepanjang sesi, jadi setiap baris merupakan kos berulang dan bukannya kos sekali sahaja. Pindahkan bahan rujukan yang panjang ke dalam fail berasingan di dalam direktori kemahiran dan pautkannya daripada SKILL.md, satu tahap ke dalam, supaya ejen hanya membacanya apabila perlu. Skrip yang disertakan akan dilaksanakan dan bukannya dibaca, jadi kosnya hanyalah berdasarkan outputnya sahaja.

Mengapa kemahiran saya tidak pernah dicetuskan?

Penerangan biasanya menjadi punca utama, kerana ia merupakan satu-satunya bahagian kemahiran yang berada dalam konteks apabila model membuat keputusan. Pastikan ia menyatakan bila untuk menggunakan kemahiran tersebut, bukan sekadar apa yang dilakukannya, dan pastikan ia mengandungi perkataan yang anda taip dalam permintaan anda. Jika penerangan kelihatan betul, periksa frontmatter untuk disable-model-invocation: true, yang menyembunyikan kemahiran daripada model sepenuhnya, dan untuk glob paths yang mengehadkannya kepada fail yang tidak anda sentuh. Kemahiran dalam direktori .claude/skills/ yang bersarang di bawah direktori permulaan anda adalah punca lain: ia hanya dimuatkan selepas ejen membaca atau menyunting fail dalam subdirektori tersebut.

Patutkah ini menjadi kemahiran atau baris dalam fail peraturan saya?

Tanya diri anda berapa banyak tugasan anda yang memerlukannya. Fail peraturan dimuatkan dalam setiap sesi, jadi ia harus mengandungi fakta yang benar untuk setiap tugasan, seperti pengurus pakej atau konvensyen penamaan cawangan. Kemahiran hanya dimuatkan apabila ia dicetuskan, jadi ia adalah tempat yang sesuai untuk prosedur yang hanya penting bagi sebahagian kecil tugasan. Jangan sekali-kali menulis arahan yang sama di kedua-dua tempat, kerana kedua-dua salinan akan menjadi tidak selari dan anda akan kehilangan keupayaan untuk mengetahui yang mana satu diikuti oleh ejen.

Bagaimanakah saya tahu sesuatu kemahiran itu benar-benar membantu?

Bandingkannya dengan garis dasar. Kumpulkan beberapa permintaan sebenar, jalankan setiap satu dalam sesi baharu dengan kemahiran tersedia, kemudian jalankannya semula dengan kemahiran dimatikan daripada menu /skills, dan baca kedua-dua jawapan bersebelahan. Sesi baharu adalah penting kerana perbualan di mana anda menulis kemahiran tersebut masih mengandungi penjelasan anda, yang menjadikan fail yang tidak lengkap kelihatan lengkap. Pemalam skill-creator menjalankan perbandingan ini untuk anda dan melaporkan kadar lulus di sebelah kos token.

Bolehkah saya menggunakan SKILL.md yang sama dengan ejen yang berbeza?

Ya, selagi anda kekal dalam medan yang ditetapkan oleh standard Agent Skills: name, description, license, compatibility, metadata dan allowed-tools. Claude Code menerima lebih banyak medan, dan ia juga menyokong ciri kandungan seperti suntikan arahan shell yang tidak dijalankan oleh alatan lain. Memuat naik kemahiran dengan medan di luar standard akan gagal dengan ralat eksplisit yang menyenaraikan sifat yang dibenarkan, jadi tentukan lebih awal sama ada kemahiran tersebut bertujuan untuk kekal dalam Claude Code atau untuk digunakan di tempat lain.