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, catatkan pembetulan yang anda taip pada kedua-dua kali tersebut, dan simpan pembetulan itu sebagai fail SKILL.md yang boleh dimuatkan sendiri oleh ejen tersebut. Segala-galanya selepas itu hanyalah mekanik: susun atur fail, dan satu baris yang menentukan sama ada kemahiran itu akan dicetuskan atau tidak.

Urutan itu penting. Kemahiran yang ditulis berdasarkan imaginasi mendokumentasikan masalah yang tidak pernah anda alami, dan ia tetap menggunakan 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.

Bermula daripada tugasan yang ejen lakukan dengan salah sebanyak dua kali

Sekali mungkin kebetulan. Dua kali adalah satu 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 tidak dapat diakses 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.

Catatkan 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. Pembetulan itu adalah kandungan keseluruhannya.

Panduan penulisan daripada Anthropic 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 tidak dapat dikesan puncanya biasanya adalah kemahiran yang tidak diperlukan oleh sesiapa pun.

Untuk contoh kerja bagi penyulingan yang sama, Ponytail menukarkan satu kegagalan berulang, iaitu ejen yang menulis semula jauh 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 format YAML (format konfigurasi yang sama digunakan oleh fail Docker Compose) di antara penanda ---, diikuti dengan arahan dalam format 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 mempunyai kurang daripada dua puluh baris dan ia merupakan satu skill yang lengkap. Bahagian-bahagiannya adalah:

• 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 skill ini bertindak balas kepada /nginx-config-changes.
• description: fungsi skill tersebut dan bila untuk menggunakannya, sehingga 1,024 aksara. Baris ini melaksanakan tugas sebenar, dan bahagian seterusnya adalah khusus mengenai perkara ini.
• Bahagian badan: 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 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 output fail tersebut yang menggunakan kos konteks, jadi skrip sepanjang 300 baris adalah murah.

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 repositori tersebut.
• ~/.claude/skills/<name>/SKILL.md: untuk setiap projek pada mesin anda, dan tidak boleh diakses oleh orang lain.
• <plugin>/skills/<name>/SKILL.md: disertakan di dalam plugin, tersedia di mana-mana sahaja plugin tersebut diaktifkan.

Cipta satu skill 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 serta-merta dalam sesi yang sedang berjalan. Mencipta direktori skills peringkat atas yang tidak wujud semasa sesi bermula memerlukan permulaan semula (restart), kerana tiada apa-apa yang dipantau apabila sesi tersebut dimulakan.

Medan perihalan ialah baris yang 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 anda akan taipkan 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 ringkas kerana ia kekal dalam konteks

Apabila sesuatu 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 merupakan 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 fail berasingan. Pemadatan menunjukkan sebab angka tersebut tidak ditetapkan secara sewenang-wenangnya. Apabila perbualan diringkaskan untuk mengosongkan konteks, Claude Code akan melampirkan semula panggilan terbaharu bagi setiap skill, mengekalkan hanya 5,000 token pertama bagi setiap satu, dan mengisi bajet gabungan sebanyak 25,000 token bermula daripada skill yang paling baru dipanggil. Skill yang panjang akan terpotong di tengah jalan. Beberapa skill yang panjang akan menyebabkan satu sama lain terkeluar 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 mengenai reload berbanding restart, dan peraturan itu adalah satu-satunya sebab fail ini wujud.

Jika skill tersebut mengarahkan ejen untuk menjalankan skrip yang disertakan, namakan laluan tersebut dengan ${CLAUDE_SKILL_DIR} supaya ia dapat diselesaikan di mana sahaja skill 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 *)
---

Kebenaran ini meliputi pusingan yang memanggil skill tersebut dan akan tamat apabila anda menghantar mesej seterusnya, jadi ia tidak akan menjadi kebenaran kekal secara senyap.

Cara membuktikan kemahiran (skill) diaktifkan

Memerhatikan kemahiran dimuatkan hanya 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 bekerja biasa, dengan kata-kata anda sendiri, tanpa menyebut nama kemahiran tersebut.
3. Perhatikan pengaktifannya. Jika kemahiran tidak diaktifkan, betulkan penerangannya. Bahagian isi (body) belum lagi menjadi masalahnya.
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 tersebut. Dalam menu /skills, serlahkan 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 menukarkannya kembali kepada on apabila anda selesai.
6. Tulis beberapa permintaan yang tidak sepatutnya mencetuskan kemahiran tersebut, dan pastikan ia kekal tidak aktif pada permintaan tersebut.

Untuk mengautomasikan gelung tersebut, pasang pemalam skill-creator daripada pasaran 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 penggunaan kemahiran dengan tanpa kemahiran, yang merupakan angka sebenar: peningkatan kadar lulus yang diukur berdasarkan token dan masa yang diambil oleh kemahiran tersebut.

Mod kegagalan: skill tidak pernah dicetuskan

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

• Penerangan menyatakan fungsi skill tetapi tidak menyatakan bila untuk menggunakannya, jadi tiada apa-apa dalam permintaan anda yang sepadan dengannya.
• Penerangan tersebut tidak mengandungi perkataan yang anda taip. Jika anda menyebut "nginx", penerangan tersebut mestilah mengandungi perkataan nginx.
• disable-model-invocation: true ditetapkan dalam frontmatter. Ini menghalang penerangan tersebut 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 mana-mana 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 tersebut hanya terpakai pada fail tertentu. Bagi sebarang perkara 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 berada dalam fail peraturan. Prosedur yang hanya terpakai untuk sebahagian kecil tugasan, seperti peraturan nginx di atas, sepatutnya berada 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. sempadan antara kemahiran, pelayan MCP dan fail peraturan membincangkan 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 berkesan

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

Satu nota tentang mudah alih. 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 enam medan tersebut dan fail yang sama akan dimuatkan dalam Claude Code serta semua sistem lain yang membaca standard tersebut. Menulis arahan itu sendiri supaya ia kekal berkesan apabila dipindahkan ke model lain 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 badan fail 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 dibundel akan dilaksanakan dan bukannya dibaca, jadi ia hanya menelan kos berdasarkan outputnya sahaja.

Mengapakah kemahiran saya tidak pernah dicetuskan?

Penerangan adalah punca yang biasa, 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 penting bagi sebahagian kecil tugasan sahaja. 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 menentukan 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 badan seperti suntikan arahan shell yang tidak dijalankan oleh alat 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.