Oleh Matt Connor
Cara Kongsi Kemahiran Ejen Merentas Repositori
Hentikan amalan menyalin fail kemahiran ejen yang sering menyebabkan ralat drift. Gunakan kaedah dependensi dengan satu repositori pusat, versi tag, dan ujian asap yang ketat.
Cara berkongsi kemahiran ejen merentas repositori
Untuk berkongsi kemahiran ejen merentas repositori, hentikan amalan menyalin fail dan mula bergantung kepadanya. Kekalkan satu repositori kemahiran, tag repositori tersebut, dan benarkan setiap projek menetapkan (pin) tag tertentu. Kemudian, tambahkan ujian asap (smoke test) bagi setiap kemahiran, dan semak setiap peningkatan versi (bump) seperti anda menyemak peningkatan dependensi.
Terdapat empat bahagian: sumber kebenaran yang dikongsi, versi yang ditetapkan bagi setiap repositori, ujian asap bagi setiap kemahiran, dan laluan semakan. Segala maklumat di bawah menjelaskan sebab setiap bahagian wujud, tindakan yang dilakukan oleh alatan yang dikeluarkan pada tahun 2026, serta cara membina keseluruhan sistem ini pada git remote yang dihoskan sendiri tanpa melibatkan hos git luar atau daftar pakej. Ujian asap adalah satu-satunya pengecualian. Ujian ini menjalankan Claude Code, yang menghantar setiap permintaan kepada API model, jadi langkah tersebut masih melibatkan komunikasi luar pelayan anda.
Kemahiran ejen ialah folder yang mengandungi fail SKILL.md, berserta sebarang skrip dan fail rujukan yang diperlukan. Jika unit tersebut adalah baharu, baca apakah kemahiran ejen dan cara SKILL.md berfungsi terlebih dahulu. Halaman ini membincangkan rantaian bekalan di sekitar unit tersebut.
Tempat kemahiran disimpan, dan sebab perkongsian itu sukar
Claude Code memuatkan kemahiran daripada empat lokasi, dan dokumentasi kemahiran menamakan setiap laluan tersebut.
.claude/skills/<skill-name>/SKILL.mddi dalam direktori tetapan terurus ialah lokasi perusahaan. Ia dimuatkan untuk setiap pengguna pada mesin di mana organisasi melaksanakannya.~/.claude/skills/<skill-name>/SKILL.mdadalah bersifat peribadi. Ia dimuatkan dalam semua projek anda dan bukan projek orang lain..claude/skills/<skill-name>/SKILL.mdadalah pada peringkat projek. Ia dimuatkan untuk sesiapa sahaja yang melakukan checkout repositori tersebut.<plugin>/skills/<skill-name>/SKILL.mddisertakan di dalam pemalam. Ia dimuatkan di mana-mana sahaja pemalam tersebut didayakan.
Lokasi peringkat projek adalah yang paling berguna untuk pasukan, kerana ia dikomitkan dan setiap orang yang mengklon repositori tersebut akan mendapatnya. Di sinilah masalah bermula. Sesuatu kemahiran dalam .claude/skills/ tergolong dalam satu repositori. Anda mempunyai lapan repositori. Jadi, kemahiran tersebut disalin sebanyak lapan kali.
Frontmatter tidak memberikan sebarang bantuan. Spesifikasi Agent Skills membenarkan enam kunci, dan laluan pengedaran yang menguatkuasakannya akan mencetak senarai tersebut apabila anda menggunakan kunci lain:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, namePerhatikan apa yang tiada: tiada kunci version. Tiada apa-apa di dalam fail tersebut yang merekodkan salinan mana yang lebih baharu. Itu munasabah, kerana kemahiran adalah dokumen dan bukannya pakej. Namun, ini bermakna pemversian perlu datang daripada lapisan di sekeliling fail tersebut, dan lapisan itu adalah tanggungjawab anda.
Masalah satu: lapan salinan yang menyimpang secara senyap
Fungsi salin-tampal berfungsi pada hari pertama. Ia gagal pada hari keenam puluh. Seseorang membetulkan arahan yang salah dalam repo payments dan tidak menyentuh tujuh yang lain. Seseorang yang lain menambah peraturan tentang penomboran halaman dalam orders. Kini, nama kemahiran yang sama memberikan dua ulasan berbeza bergantung pada direktori mana ejen itu dimulakan, dan tiada pembangun yang menyedarinya.
Kegagalan ini berlaku secara senyap kerana tiada status ralat. Sesuatu kemahiran adalah prosa. Arahan yang lapuk menghasilkan jawapan yang yakin tetapi salah, iaitu jenis kegagalan yang mahal. Tiada apa-apa dalam ejen yang membandingkan salinan anda dengan salinan orang lain, jadi satu-satunya isyarat ialah apabila seseorang menyedari bahawa dua repo tidak sepadan.
Masalah dua: tiada penetapan versi
Walaupun pasukan menyimpan kemahiran di satu lokasi, kaedah perkongsian yang biasa digunakan ialah langkah penyalinan: skrip persediaan, baris curl dalam dokumen onboarding, atau alias shell yang menyegerakkan folder. Semua kaedah tersebut memasang apa sahaja yang berada di hujung cawangan (head of the branch) pada masa itu.
Ini bermakna dua pembangun yang menggunakan commit yang sama bagi aplikasi yang sama boleh menjalankan arahan yang berbeza, kerana mereka melakukan penyegerakan pada hari yang berlainan. Ini juga bermakna anda tidak dapat menjawab soalan penting selepas satu larian ejen yang bermasalah: versi kemahiran yang manakah menghasilkan output ini? Tanpa semakan (revision) yang direkodkan, larian tersebut tidak boleh dihasilkan semula, maka laporan pepijat tidak boleh diambil tindakan.
Masalah tiga: tiada siapa yang tahu kemahiran tersebut masih berfungsi
Sesuatu kemahiran tidak mempunyai pengkompil. Ia hanyalah arahan yang ditujukan kepada model, jadi ia boleh berhenti berfungsi walaupun fail tersebut kekal sama dari segi bait. Peningkatan versi model mengubah tahap kepatuhan terhadap arahan yang panjang. Alat baris perintah yang dipanggil oleh kemahiran tersebut menamakan semula flag. URL dalam fail rujukan mula mengembalikan ralat 404 dan ejen tersebut bekerja berdasarkan halaman ralat itu.
Tiada apa-apa yang gagal secara ketara dalam mana-mana kes tersebut. Ejen masih memberikan jawapan. Jawapannya cuma lebih buruk berbanding bulan lepas, sesuatu yang sukar untuk disedari jika dilihat satu pull request pada satu masa.
Masalah yang diselesaikan oleh alatan yang dilancarkan pada 2026
Beberapa jawapan sedang muncul sekarang, dan terdapat perbezaan pendapat tentang lokasi sepatutnya bagi sesuatu versi.
Lockfiles. Alat baris perintah skills daripada Vercel Labs (vercel-labs/skills, berlesen MIT, v1.7.2 setakat 9 Oktober 2026) memasang kemahiran (skills) daripada repositori git ke dalam direktori yang dijangkakan oleh ejen anda, dan ia mengenali susun atur untuk lebih daripada tujuh puluh ejen. npx skills add <repo> melakukan pemasangan, npx skills update melakukan naik taraf, dan npx skills list memaparkan apa yang anda miliki. Ia mengekalkan dua fail kunci (lock files). Fail global pada ~/.agents/.skill-lock.json merekodkan apa yang telah dipasang oleh seorang pengguna. Sejak v1.4.1 (20 Februari 2026), pemasangan pada skop projek juga menulis skills-lock.json di akar projek, dan kod sumber alat tersebut menyatakan bahawa fail itu bertujuan untuk dimasukkan ke dalam kawalan versi. npx skills experimental_install memulihkan kemahiran projek daripadanya. Satu permintaan terbuka pada projek tersebut (isu 283) masih meminta arahan skills install yang memasang semula setiap kemahiran dalam fail kunci global, supaya mesin kedua berakhir dengan set peribadi yang sama. Baca kedua-duanya sebagai laporan status. Fail kunci per-projek memang wujud. Arahan yang memulihkan daripadanya masih dilabelkan sebagai eksperimental.
Spesifikasi dan ujian. SkillSpec mengambil sudut pandangan yang berbeza. Ia menganggap SKILL.md sebagai kontrak untuk disemak dan bukannya prosa untuk dipercayai, dengan matlamat yang dinyatakan untuk menjadikan kemahiran "boleh diikuti, boleh diuji, dan boleh dibuktikan". skillspec doctor <path> melaporkan di mana ejen berkemungkinan menggugurkan thread. skillspec boundary map <path> menunjukkan kandungan kemahiran tersebut, dan skillspec boundary assess <path> melaporkan apa yang boleh dicapainya, disusun mengikut risiko. Ia merupakan crate Rust, dilesenkan secara dwi-lesen MIT atau Apache 2.0. Versi 0.2.2 telah diterbitkan pada 29 Julai 2026 dan masih merupakan yang terbaharu di crates.io setakat 10 Oktober 2026. Pasang versi yang dipinkan dan bukannya versi terbaharu:
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked dibina dengan versi dependensi yang digunakan semasa crate tersebut diterbitkan, supaya binaan tidak berubah tanpa disedari. skillspec --version sepatutnya mencetak 0.2.2. Nombor yang berbeza bermakna binari yang lebih lama yang berada lebih awal dalam PATH anda sedang digunakan.
Amalan vendor. Google menerangkan cara ia membina kemahiran dalam google/skills melalui hantaran tentang cara ia membina, menguji dan menskalakan kemahiran ejen. Jika diketepikan aspek skala, mekanismenya hanyalah integrasi berterusan (CI) biasa. Setiap kemahiran melepasi linter untuk metadata frontmatter, kiraan baris, susun atur direktori dan penamaan sebelum ia digabungkan (merge). Pemeriksa pautan akan menggagalkan binaan pada mana-mana URL yang mengembalikan 404, yang mengesan pautan munasabah yang dicipta oleh ejen. Penulis mesti menyediakan suite prompt penilaian dan rubrik pemarkahan bersama-sama dengan kemahiran tersebut. Kerja penilaian berjadual kemudiannya dijalankan setiap minggu terhadap keseluruhan pustaka untuk mengesan regresi, dan setiap kemahiran mempunyai pemilik yang dinamakan yang dijangka akan membaikinya apabila kualiti menurun.
Corak di sebalik ketiga-tiga jawapan
Anda tidak perlu memilih salah satu daripadanya. Di bawahnya terdapat satu bentuk tunggal, dan git yang ringkas memberikan anda kesemuanya.
- Satu sumber kebenaran. Kemahiran tersebut mempunyai satu lokasi utama, dan setiap repositori merujuk kepada lokasi tersebut dan bukannya menyimpan salinan.
- Versi yang disemat (pinned) bagi setiap repositori. Setiap projek merekodkan semakan (revision) tepat yang digunakannya, jadi menaik taraf adalah satu commit dalam projek tersebut dengan pengarang dan tarikh.
- Ujian asap (smoke test) bagi setiap kemahiran. Satu pemeriksaan boleh laksana yang membuktikan kemahiran tersebut masih menghasilkan keputusan yang dijanjikan.
- Laluan semakan. Perubahan pada kemahiran yang dikongsi melalui proses semakan, dan setiap pengguna melihat diff sebelum menerimanya.
Itulah bentuk bagi satu dependensi. Kemahiran menjadi artifak yang dikongsi lebih pantas daripada perkembangan alatan di sekelilingnya, jadi alatan yang anda sudah percayai adalah pilihan paling selamat untuk digunakan.
Susun atur untuk pasukan kecil pada git remote yang dihoskan sendiri
Satu repositori menyimpan kemahiran tersebut. Tiada perkara lain yang disimpan di dalamnya, jadi sejarahnya dibaca sebagai changelog bagi arahan.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdReleases adalah tag. Gunakan annotated tags, kerana ia membawa mesej dan tarikh, serta tulis mesej tersebut sebagai sebab mengapa pengguna mahukan peningkatan versi tersebut:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Jika remote anda ialah Gitea, Forgejo, GitLab atau repositori bare melalui SSH pada VPS anda sendiri, tiada apa yang berikut akan berubah. Segala-galanya di sini adalah git berserta symlink.
Pinning dengan git submodule
Submodule merekodkan satu commit tepat daripada repositori lain di dalam repositori anda. Rekod tersebut ialah pin. Dalam setiap projek yang menggunakannya:
git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"Symlink ialah bahagian yang membolehkan perkara ini berfungsi. Entri skill pada peringkat projek boleh menjadi symlink ke direktori di tempat lain pada cakera, dan Claude Code akan mengikutinya serta membaca SKILL.md daripada sasaran tersebut. Oleh itu, skill dimuatkan sebagai skill projek biasa, manakala bait-baitnya berada dalam submodule pada commit yang anda pilih.
Semak pin tersebut:
git submodule statusBaris yang sihat bermula dengan ruang kosong, diikuti commit, kemudian laluan, dan seterusnya tag terdekat:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)Awalan - bermaksud submodule tidak pernah dimulakan, jadi .claude/skills/api-review tidak menunjuk kepada apa-apa dan skill tersebut tidak dimuatkan secara senyap. Selesaikan perkara ini dengan git submodule update --init. Awalan + bermaksud commit yang telah di-checkout berbeza daripada yang direkodkan, jadi pembangun tersebut sedang menjalankan arahan yang tidak dimiliki oleh orang lain. Clone baharu memerlukan git clone --recurse-submodules, dan baris tersebut perlu diletakkan dalam README, kerana clone biasa akan membiarkan vendor/agent-skills kosong dan tidak mencetak sebarang ralat.
Proses naik taraf dilakukan secara sengaja, itulah tujuan utamanya:
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"Baris diff ialah laluan semakan. Ia menunjukkan perubahan yang sama yang akan dilihat oleh setiap repositori lain yang menggunakannya, dan ia sesuai untuk disertakan dalam pull request.
Pematuhan versi (pinning) menggunakan pasaran pemalam (plugin marketplace)
Jika anda tidak mahu meminta setiap pembangun mempelajari submodul, sistem pemalam Claude Code akan menguruskan pengedaran untuk anda, dan ia berfungsi dengan repositori jauh yang dihoskan sendiri. Letakkan katalog di .claude-plugin/marketplace.json dalam repositori kemahiran (skills repository):
{
"name": "acme-agents",
"owner": { "name": "Platform team", "email": "platform@example.com" },
"plugins": [
{
"name": "team-skills",
"description": "Shared review and release skills",
"version": "1.4.0",
"source": {
"source": "url",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0",
"sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
}
}
]
}Terdapat dua sumber berbeza yang terlibat di sini, dan kekeliruan antara keduanya adalah kesilapan yang biasa berlaku. Sumber pasaran, iaitu tempat katalog itu sendiri diambil, menerima ref untuk cawangan (branch) atau tag dan tidak menerima sha. Sumber pemalam di dalam katalog menerima kedua-duanya, dan apabila kedua-duanya ditetapkan, sha adalah nilai pin yang berkesan. Jadi, pin komit yang tepat (exact-commit pin) perlu diletakkan dalam entri katalog. Nama jenis (type names) juga berbeza. Di dalam katalog, url bermaksud repositori git untuk diklon. Dalam sumber pasaran, url bermaksud pautan terus ke fail marketplace.json, dan repositori git adalah git.
Setiap repositori pengguna kemudian mengisytiharkan pasaran tersebut dalam fail .claude/settings.json yang dikomit:
{
"extraKnownMarketplaces": {
"acme-agents": {
"source": {
"source": "git",
"url": "https://git.example.com/team/agent-skills.git",
"ref": "v1.4.0"
}
}
},
"enabledPlugins": {
"team-skills@acme-agents": true
}
}Claude Code mendaftarkan pasaran untuk ahli pasukan sebaik sahaja mereka menerima dialog kepercayaan ruang kerja (workspace trust dialog) untuk folder projek, tanpa memerlukan halaman wiki untuk memberitahu mereka melakukannya. Entri katalog menghala ke URL git dan bukannya laluan relatif, jadi pemalam itu sendiri tidak dipasang hanya daripada tetapan repositori. Setiap ahli pasukan menjalankan claude plugin install team-skills@acme-agents --scope project sekali, dan sehingga itu Claude Code melaporkan bahawa pemalam didayakan dalam tetapan projek tetapi belum dipasang. Kemahiran tersebut kemudian menjawab kepada /team-skills:api-review, kerana kemahiran pemalam mempunyai ruang nama (namespaced) mengikut nama pemalam dan tidak boleh bertindih dengan kemahiran projek yang mempunyai nama yang sama. Selepas anda menolak (push) tag baharu, pengguna menyegarkan dengan /plugin marketplace update acme-agents, kemudian jalankan /reload-plugins jika ringkasan pemasangan memintanya.
Menulis ujian asap untuk satu kemahiran
Ujian asap ialah larian ejen berskrip terhadap lekapan (fixture) yang mempunyai kerosakan diketahui, berserta satu asersi. Claude Code berjalan secara tidak interaktif dengan -p, dan kemahiran yang dipanggil pengguna berfungsi di situ: letakkan /skill-name dalam rentetan gesaan dan ia akan dikembangkan sebelum larian bermula.
#!/usr/bin/env bash
set -euo pipefail
claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--allowedTools "Read" \
--output-format json \
--json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
| jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/nullfixtures/orders-api.md ialah fail pendek dengan satu kerosakan yang disengajakan. Asersinya ialah kemahiran tersebut menamakan kerosakan itu. jq -e keluar dengan kod bukan sifar apabila penapisnya menghasilkan null, jadi kemahiran yang berhenti mengesan kerosakan yang disemai akan menyebabkan skrip gagal. claude sendiri keluar dengan kod bukan sifar apabila larian gagal, dan set -euo pipefail menukarkan mana-mana kegagalan tersebut menjadi ujian yang gagal.
Model akan mengubah suai jawapannya antara larian, jadi jangan sekali-kali membuat asersi pada keseluruhan ayat. Buat asersi pada pengecam yang sepatutnya dikeluarkan oleh kemahiran tersebut, atau pada medan skema yang anda minta, dan pastikan lekapan kecil supaya larian kekal murah.
Dalam CI, tambahkan --bare. Tanpanya, claude -p akan memuatkan konteks yang sama seperti sesi interaktif, termasuk cangkuk (hooks), pemalam dan CLAUDE.md daripada mesin tempat ia dijalankan, jadi konfigurasi peribadi rakan sepasukan boleh mengubah keputusan. Mod bare melangkau semua penemuan automatik, yang bermaksud ia juga melangkau kemahiran yang sedang anda uji, jadi muatkan kemahiran itu secara eksplisit. Mod bare juga tidak membaca log masuk langganan anda, jadi tetapkan ANTHROPIC_API_KEY dalam persekitaran terlebih dahulu:
claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
--plugin-dir vendor/agent-skills \
--allowedTools "Read" \
--output-format jsonPemalam yang dimuatkan dengan --plugin-dir mengambil namanya daripada .claude-plugin/plugin.json, dan tanpa manifes tersebut, ia dinamakan mengikut direktori pemalam itu. Komit plugin.json dengan "name": "team-skills" bersebelahan dengan katalog dalam repositori kemahiran, atau arahan di atas perlu memanggil /agent-skills:api-review sebaliknya.
Dengan --output-format stream-json, peristiwa system/init melaporkan pemalam yang dimuatkan dan membawa tatasusunan plugin_errors untuk pemalam yang gagal dimuatkan. Ia membuka strim melainkan peristiwa permulaan berlaku terlebih dahulu. Gagalkan kerja CI jika plugin_errors tidak kosong. Ini akan mengesan pin yang ditujukan kepada semakan (revision) yang tidak lagi wujud, yang jika tidak, akan kelihatan seperti ejen yang secara senyap mengabaikan peraturan dalaman anda.
Kemahiran yang dikongsi adalah arahan boleh laksana
Dua ciri menjadikan perkara ini literal, dan kedua-duanya penting apabila fail datang daripada pasukan lain.
Pertama, SKILL.md boleh menjalankan arahan shell sebelum model membaca apa-apa. Baris seperti ini dalam badan teks ialah prapemprosesan:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Arahan tersebut berjalan pada mesin yang memuatkan kemahiran itu, dan outputnya menggantikan pemegang tempat dalam teks yang diterima oleh model. Blok berpagar yang dibuka dengan tiga tanda backtick diikuti oleh ! menjalankan beberapa arahan dengan cara yang sama. Tiada sesiapa yang akan diminta untuk mengesahkan perkara ini semasa masa jalan. Claude Code menyemak setiap arahan terhadap peraturan kebenaran anda. Di luar mod auto, arahan yang tidak dibenarkan oleh peraturan tersebut akan membatalkan kemahiran itu, melainkan kemahiran tersebut telah meluluskannya terlebih dahulu melalui ciri kedua di bawah. Membaca kemahiran yang dikongsi bermakna membaca penggantian arahannya.
Kedua, frontmatter boleh meluluskan alatan terlebih dahulu. allowed-tools memberikan alatan yang disenaraikan tanpa gesaan kebenaran untuk giliran yang memanggil kemahiran tersebut. Kepercayaan ruang kerja tidak menyekat pemberian tersebut: Claude Code menggunakan allowed-tools kemahiran projek walaupun dalam -p yang dijalankan dalam folder yang belum dipercayai oleh sesiapa. Dokumentasi Claude Code menyatakan akibatnya dengan jelas: sesuatu kemahiran boleh memberikan akses alatan yang luas kepada dirinya sendiri, jadi semak allowed-tools kemahiran yang dimasukkan ke dalam repositori sebelum anda menjalankan Claude Code di sana. Organisasi boleh menahan medan tersebut daripada kemahiran projek dan peribadi dengan menetapkan allowManagedPermissionRulesOnly dalam tetapan terurus, yang memerlukan Claude Code v2.1.282 atau lebih baharu.
Oleh itu, kendalikan peningkatan kemahiran sama seperti peningkatan dependensi. Tetapkan pada commit yang tepat di mana sahaja mekanisme membenarkannya, kerana tag boleh dialihkan dan cawangan (branch) bergerak mengikut definisinya. Pada mesin yang dikunci, "disableSkillShellExecution": true dalam tetapan menggantikan setiap penggantian arahan dengan teks literal [shell command execution disabled by policy] dan bukannya menjalankannya, dan jika digunakan melalui tetapan terurus, pengguna tidak boleh mengatasi tetapan tersebut. Kemahiran yang dibundel dan diuruskan dikecualikan daripada tetapan itu.
Penjagaan yang sama terpakai kepada apa yang dibaca oleh sesuatu kemahiran. Kemahiran yang menjalankan env atau membuka fail konfigurasi akan menarik apa sahaja yang ditemuinya ke dalam konteks model, iaitu kegagalan yang dibincangkan dalam menjaga rahsia daripada ejen yang anda jalankan. Kemahiran yang mengambil halaman atau menjalankan pertanyaan adalah pendedahan yang sama yang dihalakan ke luar, memandangkan teks yang diambil akan masuk ke dalam konteks dan kelihatan sama seperti arahan yang anda tulis, satu sempadan yang wajar dibaca sebelum anda menghalakan ejen kepada instans SearXNG anda sendiri untuk carian web.
Perkara yang perlu dibaca semasa peningkatan versi
- Diff bagi setiap badan
SKILL.md, kerana teks tersebut merupakan arahan yang akan diikuti oleh ejen anda. - Setiap penggantian arahan (command substitution), kerana ia dijalankan pada mesin anda apabila skill dimuatkan.
- Sebarang perubahan pada
allowed-tools, kerana baris tersebut memberikan akses kepada alatan tanpa sebarang gesaan. - Ujian yang dijalankan di sebalik tag tersebut. Jika repositori kongsi menjalankan ujian smoke tersendiri dalam CI, tag yang anda gunakan sebagai rujukan haruslah mempunyai status ujian yang berjaya (hijau).
Penyemak yang tidak mampu membaca keseluruhan diff dalam masa sepuluh minit bermakna skill tersebut telah menjadi terlalu besar. Pecahkan skill tersebut. Hujah yang sama terpakai kepada dokumen repositori yang dibaca oleh ejen anda: simpan peraturan kekal dalam fail yang diterangkan dalam pemisahan AGENTS.md dan HUMAN.md serta alasan seni bina dalam fail DESIGN.md yang ditulis untuk ejen, dan biarkan skill kekal sebagai prosedur yang khusus.
Apabila perubahan model atau alat merosakkan kemahiran
Beberapa perkara berubah di sebalik tabir sesuatu kemahiran tanpa sesiapa pun menyuntingnya. Peningkatan model mengubah tahap kebolehpercayaan arahan panjang dipatuhi, jadi kemahiran yang bergantung pada model untuk mencapai langkah sembilan mungkin berhenti melakukannya. Alat baris perintah menamakan semula flag, jadi ejen menjalankan flag lama, membaca ralat, dan melakukan improvisasi. URL yang dirujuk mula mengembalikan 404. Harness ejen mengubah cara ia memilih kemahiran, jadi description yang dahulunya memenangi padanan kini tidak lagi. Apabila prosedur mula berakhir lebih awal seperti itu, tiada peningkatan versi yang dapat membaikinya dan arahan itu sendiri memerlukan struktur yang memaksa langkah terakhir dilakukan, iaitu pendekatan di sebalik kemahiran tidak malas dan kaedah Depth Tree-nya.
Inilah sebabnya ujian asap (smoke test) membawa beban penting dalam aturan ini. Jalankan ujian setiap kemahiran mengikut jadual serta semasa push. Google menjalankan kerja penilaiannya setiap minggu terhadap keseluruhan pustaka atas sebab ini, dan cron job mingguan pada VPS kecil sudah memadai untuk pasukan dengan sepuluh kemahiran. Ia adalah satu-satunya cara anda mengetahui tentang kerosakan sebelum pembangun mengetahuinya.
Kebolehalihtanganan (portability) juga membantu. Spesifikasi Agent Skills mengekalkan frontmatter kepada enam kunci, jadi kemahiran yang ditulis mengikut spesifikasi tersebut dimuatkan dalam alat selain daripada alat yang anda tulis untuknya, manakala setiap kunci khusus harness yang anda tambah adalah pertaruhan pada satu vendor. Menulis kemahiran yang bertahan daripada pertukaran model adalah disiplin tersendiri, yang diliputi dalam menjadikan kemahiran berfungsi pada mana-mana model.
FAQ
Bagaimanakah cara untuk berkongsi satu kemahiran ejen merentasi beberapa repositori?
Letakkan kemahiran tersebut dalam repositori git yang khusus, tandakan (tag) setiap keluaran, dan minta setiap projek yang menggunakannya merujuk kepada tag tersebut dan bukannya menyalin fail. Terdapat dua mekanisme yang berkesan. Submodul git merekodkan commit yang tepat, dan symlink daripada .claude/skills/<name> ke dalam submodul tersebut membolehkannya dimuatkan sebagai kemahiran projek biasa. Pasaran pemalam (plugin marketplace) melakukan tugas yang sama melalui /plugin, dengan pin diisytiharkan dalam .claude/settings.json repositori yang menggunakannya. Kedua-duanya meletakkan versi dalam sejarah git, supaya anda boleh menjawab arahan mana yang menghasilkan sesuatu larian ejen.
Bolehkah saya menetapkan (pin) kemahiran ejen kepada versi tertentu?
Tidak boleh dari dalam SKILL.md, kerana frontmatter tersebut tidak mempunyai kunci version. Penetapan pin perlu datang daripada lapisan di sekeliling fail tersebut. Submodul git menetapkan commit yang tepat secara reka bentuk. Dalam pasaran pemalam Claude Code, sumber pemalam menerima ref untuk cawangan (branch) atau tag dan sha untuk commit yang tepat, dan sha akan diutamakan apabila kedua-duanya hadir. Sumber pasaran itu sendiri hanya menerima ref. Utamakan pin commit, kerana tag boleh diubah selepas anda menyemaknya.
Apakah yang perlu disahkan oleh ujian smoke kemahiran?
Sahkan sesuatu yang stabil. Jalankan kemahiran secara bukan interaktif terhadap fixture yang mengandungi kerosakan yang diketahui, kemudian periksa sama ada pengecam tertentu muncul dalam output, contohnya id peraturan yang sepatutnya dilaporkan oleh kemahiran tersebut. Meminta output berstruktur dengan --output-format json dan --json-schema menjadikan semakan tersebut tepat, dan jq -e akan menggagalkan skrip apabila nilai tersebut tiada. Jangan sekali-kali membuat pengesahan pada ayat penuh, kerana model akan mengubah suai jawapannya antara setiap larian.
Adakah selamat untuk memasang kemahiran kongsi daripada repositori pasukan lain?
Anggap ia sebagai dependensi kod, kerana ia merupakan arahan boleh laksana. SKILL.md boleh menjalankan perintah shell semasa waktu muat melalui bentuk penggantian perintah !, dan medan frontmatter allowed-tools boleh meluluskan alatan terlebih dahulu tanpa sebarang gesaan. Baca diff pada setiap peningkatan versi, tetapkan pin kepada commit yang tepat dan bukannya cawangan, serta utamakan sumber yang dikawal oleh pasukan anda sendiri. Pada mesin terurus, "disableSkillShellExecution": true dalam tetapan akan menghentikan penggantian perintah daripada berjalan sama sekali.
Adakah kemahiran kongsi akan berfungsi dalam ejen selain Claude Code?
Itu bergantung pada frontmatter yang anda gunakan. Spesifikasi Agent Skills mentakrifkan enam kunci: name, description, license, compatibility, metadata dan allowed-tools. Kemahiran yang terhad kepada kunci tersebut akan dimuatkan merentasi alatan yang melaksanakan spesifikasi tersebut, dan ia juga dimuatkan dalam Claude Code tanpa sebarang perubahan. Kunci khusus harness dan ciri badan di luar spesifikasi akan diabaikan atau ditolak di tempat lain, jadi elakkan penggunaannya dalam mana-mana kemahiran yang anda ingin kongsi secara meluas.