Cara Kongsi Kemahiran Ejen Merentas Repositori
Elakkan masalah drift dengan mengurus kemahiran ejen seperti dependensi. Gunakan repositori tunggal, tetapkan versi melalui tag git, dan jalankan ujian asap berkala.
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.
Lokasi skill dan sebab perkongsian sukar
Claude Code memuatkan skill dari lokasi berikut, antara lokasi lain, dan dokumentasi skills menyenaraikan setiap path.
.claude/skills/<skill-name>/SKILL.mddalam direktori tetapan terurus ialah lokasi perusahaan. Ia dimuatkan untuk setiap pengguna pada mesin yang digunakan oleh organisasi.~/.claude/skills/<skill-name>/SKILL.mdbersifat peribadi. Ia dimuatkan dalam semua projek anda dan tidak dimuatkan dalam projek pengguna lain..claude/skills/<skill-name>/SKILL.mdialah lokasi peringkat projek. Ia dimuatkan untuk sesiapa sahaja yang membuat checkout repository tersebut.<plugin>/skills/<skill-name>/SKILL.mddisertakan dalam plugin. Ia dimuatkan di mana-mana sahaja plugin tersebut didayakan.
Claude Code juga memuatkan skill dari direktori projek bersarang, direktori yang dibekalkan dengan --add-dir, serta skill yang didayakan untuk akaun claude.ai anda.
Lokasi peringkat projek ialah pilihan yang berguna untuk pasukan kerana fail tersebut boleh di-commit dan semua orang yang clone repo akan mendapatkannya. Di sinilah masalah bermula. Skill dalam .claude/skills/ tergolong pada satu repository. Anda mempunyai lapan repository. Jadi, skill tersebut disalin lapan kali.
Frontmatter tidak membantu. Spesifikasi Agent Skills membenarkan enam kunci, dan path pengedaran yang menguatkuasakan spesifikasi tersebut akan memaparkan senarai ini apabila anda menggunakan kunci lain:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, namePerhatikan perkara yang tiada: tiada kunci version. Versi boleh direkodkan di bawah metadata, tetapi spesifikasi tersebut tidak mentakrifkan pin dependency atau mekanisme kemas kini. Ini munasabah kerana skill ialah dokumen, bukannya package. Namun, penentuan versi perlu datang daripada lapisan di sekeliling fail tersebut, dan lapisan itu menjadi 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.
Penyelesaian oleh tools yang dikeluarkan pada 2026
Beberapa penyelesaian kini mula digunakan, dan pendekatannya berbeza tentang lokasi versi yang patut disimpan.
Lockfile. Command line tool skills daripada Vercel Labs (vercel-labs/skills, berlesen MIT, v1.7.2 pada 9 October 2026) memasang skills daripada git repository ke mana-mana directory yang dijangka oleh agent anda, serta mengetahui layout untuk lebih daripada seventy agent. npx skills add <repo> memasang, npx skills update menaik taraf dan npx skills list memaparkan perkara yang telah dipasang. Tool ini menyelenggara dua lock file. Satu fail global di ~/.agents/.skill-lock.json merekodkan perkara yang telah dipasang oleh seorang pengguna. Sejak v1.4.1 (20 February 2026), pemasangan pada project scope turut menulis skills-lock.json pada project root, dan source code tool ini menyatakan bahawa fail tersebut bertujuan untuk dimasukkan ke dalam version control. npx skills experimental_install memulihkan skills sesebuah project daripada fail itu. Issue 283, yang meminta command skills install untuk memulihkan global lock file pada mesin lain, ditutup sebagai tidak dirancang pada 5 November 2026; maintainer mengenal pasti permintaan itu sebagai sama dengan issue 549. Anggap kedua-duanya sebagai laporan status. Per-project lockfile memang wujud. Dalam v1.8.1 yang dikeluarkan, restore command masih dilabelkan sebagai experimental dalam help, tetapi npx skills install tanpa source turut memulihkan project lockfile.
Spec dan ujian. SkillSpec menggunakan pendekatan yang berbeza. Ia menganggap SKILL.md sebagai contract yang perlu diperiksa, bukannya prose yang boleh dipercayai, dengan matlamat yang dinyatakan untuk menjadikan skills "followable, testable, and provable". skillspec doctor <path> melaporkan lokasi agent berkemungkinan kehilangan konteks. skillspec boundary map <path> memaparkan kandungan skill, manakala skillspec boundary assess <path> melaporkan perkara yang boleh dicapainya, mengikut kedudukan risiko. Ia ialah Rust crate yang dilesenkan di bawah MIT atau Apache 2.0. Version 0.2.2 diterbitkan pada 29 July 2026 dan masih merupakan version terbaharu di crates.io pada 10 October 2026. Pasang version yang ditetapkan, bukan version terbaharu:
cargo install skillspec --version 0.2.2 --locked
skillspec --versionSejak Cargo 1.100 dikeluarkan pada 12 November 2026, cargo install menggunakan packaged lockfile secara lalai, manakala --locked tidak melakukan apa-apa. skillspec --version sepatutnya memaparkan 0.2.2. Nombor yang berbeza bermakna binary yang lebih lama dalam PATH anda sedang digunakan.
Amalan vendor. Google menerangkan cara mereka membina skills dalam google/skills melalui kiriman tentang cara mereka membina, menguji dan menskalakan agent skills. Jika aspek skala diketepikan, mekanismenya ialah continuous integration (CI) biasa. Setiap skill perlu melepasi linter untuk metadata frontmatter, bilangan baris, directory layout dan penamaan sebelum digabungkan. Link checker akan menggagalkan build bagi mana-mana URL yang mengembalikan 404. Ini mengesan link yang kelihatan munasabah tetapi direka oleh agent. Pengarang mesti menyediakan prompt suite penilaian dan scoring rubric bersama-sama skill tersebut. Evaluation job berjadual kemudiannya dijalankan setiap minggu terhadap keseluruhan library untuk mengesan regression, dan setiap skill mempunyai owner yang dinamakan serta dijangka 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.
Pinning dengan marketplace plugin
Jika anda tidak mahu setiap pembangun mempelajari submodul, sistem plugin Claude Code mengurus pengedaran untuk anda dan menyokong remote yang dihoskan sendiri. Letakkan katalog di .claude-plugin/marketplace.json dalam repositori skills:
{
"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"
}
}
]
}Dua sumber berbeza digunakan di sini dan kekeliruan antara kedua-duanya ialah kesilapan yang biasa berlaku. Sumber marketplace, iaitu lokasi katalog itu diambil, menerima ref untuk branch atau tag dan, dalam Claude Code v2.1.324 atau lebih baharu, full lowercase commit SHA; sumber ini tidak menerima medan sha yang berasingan. Sumber plugin dalam katalog menerima kedua-duanya. Jika kedua-duanya ditetapkan, sha ialah pin yang berkuat kuasa. Pin katalog melalui ref pada sumber marketplace dan pin plugin melalui sha pada entri katalog. Nama jenis juga berbeza. Dalam katalog, url bermaksud repositori git untuk diklon. Dalam sumber marketplace, url bermaksud pautan terus ke fail marketplace.json, manakala repositori git ialah git.
Setiap repositori yang menggunakan plugin kemudiannya mengisytiharkan marketplace dalam .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 marketplace untuk rakan sepasukan selepas mereka menerima dialog kepercayaan workspace bagi folder projek, tanpa memerlukan halaman wiki yang menerangkan langkah tersebut. Entri katalog menunjuk kepada URL git, bukan path relatif. Oleh itu, plugin itu sendiri tidak dipasang hanya melalui tetapan repositori. Setiap rakan sepasukan menjalankan claude plugin install team-skills@acme-agents --scope project sekali. Sebelum itu, Claude Code melaporkan bahawa plugin diaktifkan dalam tetapan projek tetapi belum dipasang. Skills tersebut kemudiannya boleh dipanggil melalui /team-skills:api-review kerana skills plugin menggunakan namespace berdasarkan nama plugin dan tidak boleh bertindih dengan project skill yang mempunyai nama sama. Selepas anda melakukan push tag baharu dan mengemas kini pin dalam katalog serta repositori yang menggunakan plugin, pengguna menjalankan refresh dengan /plugin marketplace update acme-agents, kemudian menjalankan /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 sana: 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 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 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 penemuan automatik kecuali untuk kemahiran dalam .claude/skills/ di bawah direktori yang dibekalkan secara eksplisit dengan --add-dir; ia melangkau kemahiran projek yang anda uji di sini, 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 itu, ia dinamakan mengikut direktorinya. Komit plugin.json dengan "name": "team-skills" di sebelah 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 datang dahulu. Gagalkan kerja CI jika plugin_errors tidak kosong. Ini mengesan pin yang ditujukan pada semakan (revision) yang tidak lagi wujud, yang jika tidak, akan kelihatan seperti ejen yang secara senyap mengabaikan peraturan dalaman anda.
Kemahiran yang dikongsi ialah arahan boleh laksana
Dua ciri menjadikan perkara ini literal, dan kedua-duanya penting apabila fail tersebut 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 berdasarkan 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. Peraturan deny dan ask masih mengatasi kelulusan awal tersebut. 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 tidak 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 kemas kini kemahiran sama seperti kemas kini dependensi. Sematkan mengikut commit yang tepat di mana-mana mekanisme membenarkannya, kerana tag boleh dialihkan dan cawangan (branch) berubah 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 diurus dikecualikan daripada tetapan itu.
Langkah berjaga-jaga yang sama terpakai pada perkara 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 perlu dibaca sebelum anda menghalakan ejen ke 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 saya berkongsi satu kemahiran ejen merentas beberapa repositori?
Letakkan kemahiran itu dalam repositori git khusus, tandakan keluaran dalam repositori tersebut, dan minta setiap projek yang menggunakannya merujuk kepada tag dan bukannya menyalin fail. Dua mekanisme boleh digunakan. Submodul git merekodkan commit yang tepat, manakala symlink daripada .claude/skills/<name> ke dalam submodul membolehkan kemahiran itu dimuatkan seperti kemahiran projek biasa. Marketplace pemalam menjalankan fungsi yang sama melalui /plugin, dengan pin dinyatakan dalam .claude/settings.json repositori yang menggunakannya. Kedua-duanya meletakkan versi dalam sejarah git, jadi anda boleh menentukan arahan yang menghasilkan sesuatu pelaksanaan ejen.
Bolehkah saya menetapkan pin kemahiran ejen kepada versi tertentu?
Bukan dari dalam SKILL.md, kerana frontmatter itu tidak mempunyai kunci version. Pin tersebut perlu datang daripada lapisan yang mengelilingi fail itu. Submodul git menetapkan pin kepada commit yang tepat mengikut reka bentuknya. Dalam marketplace pemalam Claude Code, sumber pemalam menerima ref untuk branch atau tag dan sha untuk commit yang tepat. Jika kedua-duanya ada, sha diutamakan. Sumber marketplace itu sendiri menerima ref untuk branch, tag atau, dalam Claude Code v2.1.324 atau lebih baharu, SHA commit penuh dalam huruf kecil. Utamakan pin commit kerana tag boleh dialihkan selepas anda menyemaknya.
Apakah yang perlu disahkan oleh ujian smoke kemahiran?
Buat pengesahan terhadap sesuatu yang stabil. Jalankan kemahiran secara tanpa interaksi pada fixture yang mengandungi kerosakan yang diketahui. Kemudian semak bahawa pengecam tertentu muncul dalam output, contohnya ID peraturan yang sepatutnya dilaporkan oleh kemahiran itu. Meminta output berstruktur dengan --output-format json dan --json-schema menjadikan semakan itu tepat. jq -e akan menggagalkan skrip apabila nilai tersebut tiada. Jangan buat pengesahan terhadap ayat penuh kerana model boleh menyusun semula jawapannya antara pelaksanaan.
Adakah selamat untuk memasang kemahiran dikongsi daripada repositori pasukan lain?
Anggap kemahiran itu sebagai kebergantungan kod kerana ia ialah arahan yang boleh dilaksanakan. Satu SKILL.md boleh menjalankan arahan shell semasa dimuatkan melalui bentuk penggantian arahan !. Medan frontmatter allowed-tools pula boleh memberikan pra-kelulusan kepada alat tanpa gesaan. Baca diff bagi setiap kemas kini. Tetapkan pin kepada commit yang tepat, bukan branch. Utamakan sumber yang dikawal oleh pasukan anda sendiri. Pada mesin terurus, "disableSkillShellExecution": true dalam tetapan menghentikan penggantian arahan dalam kemahiran pengguna, projek, pemalam dan direktori tambahan daripada berjalan. Kemahiran terbina dalam dan kemahiran terurus dikecualikan.
Adakah kemahiran dikongsi berfungsi dalam ejen selain Claude Code?
Hal ini bergantung pada frontmatter yang digunakan. Spesifikasi Agent Skills mentakrifkan enam kunci: name, description, license, compatibility, metadata dan allowed-tools. Kemahiran yang terhad kepada kunci tersebut boleh dimuatkan merentas alat yang melaksanakan spesifikasi itu. Kemahiran tersebut juga boleh dimuatkan dalam Claude Code tanpa perubahan. Kunci khusus harness dan ciri isi kandungan yang melangkaui spesifikasi mungkin diabaikan atau ditolak oleh alat lain. Oleh itu, jangan sertakannya dalam kemahiran yang hendak dikongsi secara meluas.