Cara Kongsi Kemahiran Ejen Merentas Repositori

Cara berkongsi kemahiran ejen merentas repositori

Untuk berkongsi kemahiran ejen merentas repositori, hentikan amalan menyalin fail dan mula bergantung kepadanya. Kekalkan satu repositori kemahiran, berikan tag, dan biarkan setiap projek menetapkan (pin) tag tersebut. 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, fungsi alatan yang dikeluarkan pada 2026, dan cara membina keseluruhan sistem ini pada git remote yang dihoskan sendiri tanpa melibatkan perkhidmatan luar.

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 tiga lokasi, dan dokumentasi kemahiran menamakan setiap laluan tersebut.

• ~/.claude/skills/<skill-name>/SKILL.md adalah bersifat peribadi. Ia dimuatkan dalam semua projek anda dan bukan projek orang lain.
• .claude/skills/<skill-name>/SKILL.md adalah pada peringkat projek. Ia dimuatkan untuk sesiapa sahaja yang melakukan checkout repositori tersebut.
• <plugin>/skills/<skill-name>/SKILL.md disertakan di dalam plugin. Ia dimuatkan di mana-mana sahaja plugin tersebut diaktifkan.

Lokasi tengah adalah yang berguna untuk pasukan, kerana ia dikomit dan setiap orang yang melakukan clone repositori tersebut akan mendapatkannya. 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 menawarkan 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, name

Perhatikan apa yang tiada: tiada kunci version. Tiada apa-apa di dalam fail tersebut yang merekodkan salinan mana yang lebih baharu. Itu adalah munasabah, kerana kemahiran adalah dokumen dan bukannya pakej. Walau bagaimanapun, ini bermakna pemversian perlu datang daripada lapisan di sekeliling fail tersebut, dan lapisan itu adalah tugas 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 tahun 2026

Beberapa jawapan sedang muncul sekarang, dan terdapat perbezaan pendapat tentang lokasi sepatutnya bagi versi tersebut.

Lockfiles. Alat baris perintah skills daripada Vercel Labs (vercel-labs/skills, berlesen MIT, v1.5.22 setakat 5 Ogos 2026) memasang kemahiran (skills) daripada repositori git ke dalam mana-mana 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. Rekod tentang perkara yang dipasang disimpan sekali bagi setiap pengguna dan bukannya sekali bagi setiap repositori, dan satu permintaan terbuka pada projek tersebut (isu 283) meminta arahan skills install yang memasang semula setiap kemahiran yang dijejak daripada fail kunci (lock file) supaya mesin kedua berakhir dengan set yang sama. Anggap permintaan tersebut sebagai laporan status. Idea fail kunci sudah diputuskan. Bahagian yang khusus untuk setiap projek masih dalam pembinaan.

Spesifikasi dan ujian. SkillSpec mengambil sudut pandangan yang berbeza. Ia melayan SKILL.md sebagai kontrak untuk diperiksa 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 urutan (thread). skillspec boundary map <path> melaporkan perkara yang boleh dicapai oleh kemahiran tersebut, dan skillspec boundary assess <path> menyenaraikan dapatan tersebut mengikut risiko. Ia merupakan crate Rust, dilesenkan secara dwi-lesen MIT atau Apache 2.0, pada versi 0.2.2 setakat 29 Julai 2026. Pasang versi yang dipinkan dan bukannya versi terbaharu:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked membina dengan versi dependensi yang digunakan semasa crate tersebut diterbitkan, supaya binaan tidak berubah tanpa pengetahuan anda. 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. Ketepikan aspek skala dan mekanismenya adalah integrasi berterusan (CI) yang biasa. Setiap kemahiran melepasi linter untuk metadata frontmatter, kiraan baris, susun atur direktori dan penamaan sebelum ia digabungkan. Pemeriksa pautan akan menggagalkan binaan pada mana-mana URL yang mengembalikan 404, yang mengesan pautan munasabah yang dicipta oleh ejen. Penulis mesti menyediakan suite gesaan 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 dinamakan yang dijangka akan membaikinya apabila kualiti merosot.

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.

1. Satu sumber kebenaran. Kemahiran tersebut mempunyai satu lokasi utama, dan setiap repositori merujuk kepada lokasi tersebut dan bukannya menyimpan salinan.
2. 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.
3. Ujian asap (smoke test) bagi setiap kemahiran. Satu pemeriksaan boleh laksana yang membuktikan kemahiran tersebut masih menghasilkan keputusan yang dijanjikan.
4. 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.md

Releases 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.0

Jika 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 status

Baris 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 menggunakan pasaran pemalam sebagai alternatif

Jika anda tidak mahu meminta setiap pembangun mempelajari submodul, sistem pemalam Claude Code menguruskan pengedaran untuk anda, dan ia berfungsi dengan pelayan jauh yang dihoskan sendiri. Letakkan katalog di .claude-plugin/marketplace.json dalam repositori kemahiran:

{
  "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 merupakan kesilapan biasa. 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 menjadi pin yang berkesan. Jadi, pin komit yang tepat diletakkan dalam entri katalog.

Setiap repositori pengguna kemudian mengisytiharkan pasaran tersebut dalam .claude/settings.json yang dikomitkan:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Rakan sepasukan yang mempercayai folder projek akan digesa untuk memasang pasaran tersebut, dan pemalam akan didayakan untuk mereka tanpa perlu merujuk halaman wiki untuk melakukannya. Kemahiran tersebut kemudian menjawab kepada /team-skills:api-review, kerana kemahiran pemalam mempunyai ruang nama mengikut nama pemalam dan tidak boleh bertembung dengan kemahiran projek yang mempunyai nama yang sama. Selepas anda menolak (push) tag baharu, pengguna memuat semula 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) dengan kerosakan yang 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 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/null

fixtures/orders-api.md ialah fail pendek dengan satu kerosakan yang disengajakan. Asersinya ialah kemahiran tersebut menamakannya. jq -e keluar dengan nilai bukan sifar apabila penapisnya menghasilkan null, jadi kemahiran yang berhenti mengesan kerosakan yang disemai akan menyebabkan skrip gagal. claude sendiri keluar dengan nilai bukan sifar apabila larian gagal, dan set -euo pipefail menukarkan mana-mana kegagalan menjadi ujian yang gagal.

Model akan menyusun semula 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 semua penemuan automatik, yang bermaksud ia juga melangkau kemahiran yang 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 json

Dengan --output-format stream-json, acara pertama larian melaporkan pemalam mana yang dimuatkan dan membawa tatasusunan plugin_errors untuk pemalam yang tidak dimuatkan. Gagalkan kerja CI pada plugin_errors yang tidak kosong. Ini menangkap pin yang ditujukan pada semakan yang tidak lagi wujud, yang jika tidak, akan kelihatan sebagai ejen yang secara senyap mengabaikan peraturan dalaman anda.

Kemahiran yang dikongsi merupakan 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 merupakan 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 meluluskan perkara ini semasa masa jalan (run time). Membaca kemahiran yang dikongsi bermakna membaca penggantian arahannya.

Kedua, frontmatter boleh meluluskan alatan terlebih dahulu. allowed-tools memberikan kebenaran kepada alatan yang disenaraikan tanpa gesaan kebenaran untuk giliran yang memanggil kemahiran tersebut. Bagi kemahiran projek, pemberian itu berkuat kuasa sebaik sahaja seseorang menerima dialog kepercayaan ruang kerja untuk folder tersebut. Dokumentasi Claude Code menyatakan akibatnya dengan jelas: semak kemahiran projek sebelum mempercayai repositori, kerana sesuatu kemahiran boleh memberikan akses alatan yang luas kepada dirinya sendiri.

Oleh itu, kendalikan peningkatan kemahiran sama seperti peningkatan dependensi. Lakukan pin mengikut commit yang tepat di mana-mana mekanisme yang 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 ia digunakan melalui tetapan terurus yang tidak boleh diatasi oleh pengguna. Kemahiran yang dibundel dan diurus dikecualikan daripada tetapan tersebut.

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 diliputi dalam menjaga rahsia daripada ejen yang anda jalankan. Kemahiran yang mengambil halaman atau menjalankan pertanyaan merupakan pendedahan yang sama yang dihalakan ke luar, memandangkan teks yang diperoleh 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.