Cara Berbagi Skill Agent Antar-Repo Tanpa Drift
Salin skill ke delapan repo membuat isinya drift. Kelola skill seperti dependensi: gunakan satu repo bersama, lalu kunci dan tinjau versi di tiap project.
Cara membagikan agent skills lintas repositori
Untuk membagikan agent skills lintas repositori, jangan lagi menyalin file. Jadikan file tersebut sebagai dependensi. Simpan satu repositori skills, beri tag, lalu biarkan setiap proyek menggunakan tag tertentu. Tambahkan smoke test untuk setiap skill, lalu tinjau setiap pembaruan seperti meninjau pembaruan dependensi.
Proses ini terdiri dari empat bagian: sumber kebenaran bersama, versi yang ditetapkan untuk setiap repositori, smoke test untuk setiap skill, dan alur peninjauan. Bagian berikut menjelaskan alasan setiap bagian diperlukan, cara tools yang dirilis pada 2026 menanganinya, serta cara membangun seluruh proses pada git remote yang di-host sendiri tanpa melibatkan git host eksternal atau package registry. Smoke test adalah satu-satunya pengecualian. Smoke test menjalankan Claude Code, yang mengirim setiap permintaan ke model API. Oleh karena itu, langkah tersebut tetap meninggalkan server Anda.
Agent skill adalah folder yang berisi file SKILL.md, beserta script dan file referensi yang diperlukan. Jika unit tersebut masih baru, baca apa itu agent skill dan cara kerja SKILL.md terlebih dahulu. Halaman ini membahas supply chain di sekitar unit tersebut.
Lokasi skill dan alasan berbagi sulit dilakukan
Claude Code memuat skill dari lokasi berikut, di antaranya, dan dokumentasi skill mencantumkan setiap path tersebut.
.claude/skills/<skill-name>/SKILL.mddi dalam direktori pengaturan terkelola adalah lokasi enterprise. Skill dimuat untuk setiap pengguna pada mesin tempat organisasi menerapkannya.~/.claude/skills/<skill-name>/SKILL.mdbersifat personal. Skill dimuat di semua project Anda dan tidak di project milik pengguna lain..claude/skills/<skill-name>/SKILL.mdberada pada level project. Skill dimuat untuk siapa pun yang melakukan checkout terhadap repository tersebut.<plugin>/skills/<skill-name>/SKILL.mddisertakan di dalam plugin. Skill dimuat di mana pun plugin tersebut diaktifkan.
Claude Code juga memuat skill dari direktori project bertingkat, direktori yang diberikan melalui --add-dir, serta skill yang diaktifkan untuk akun claude.ai Anda.
Skill pada level project adalah pilihan yang berguna bagi tim karena disimpan dalam commit, sehingga setiap orang yang melakukan clone repository akan mendapatkannya. Di sinilah masalah mulai muncul. Skill di .claude/skills/ hanya dimiliki oleh satu repository. Anda memiliki delapan repository. Jadi, skill tersebut disalin sebanyak delapan kali.
Frontmatter tidak membantu. Spesifikasi Agent Skills mengizinkan enam key, dan path distribusi yang menerapkan spesifikasi tersebut akan menampilkan daftar itu jika Anda menggunakan key lain:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, namePerhatikan hal yang tidak ada: tidak ada key version. Versi dapat dicatat di bawah metadata, tetapi spesifikasi tersebut tidak mendefinisikan pin dependensi atau mekanisme pembaruan. Hal ini masuk akal karena skill adalah dokumen, bukan package. Namun, artinya versioning harus berasal dari lapisan di sekitar file tersebut, dan lapisan itu menjadi tanggung jawab Anda.
Masalah pertama: delapan salinan yang perlahan tidak lagi sama
Salin-tempel berfungsi pada hari pertama. Pada hari keenam puluh, cara ini gagal. Seseorang memperbaiki instruksi yang salah di repo payments, tetapi tidak memperbarui tujuh salinan lainnya. Orang lain menambahkan aturan tentang pagination di orders. Sekarang, nama skill yang sama menghasilkan review yang berbeda, bergantung pada direktori tempat agent dijalankan, dan tidak ada developer yang menyadarinya.
Kegagalan ini tidak terlihat karena tidak ada status error. Skill berisi prosa. Instruksi yang sudah usang menghasilkan jawaban yang meyakinkan tetapi salah, dan jenis kesalahan inilah yang paling mahal. Agent tidak membandingkan salinan Anda dengan salinan orang lain. Satu-satunya sinyal adalah ketika seseorang menyadari bahwa dua repo tidak lagi sama.
Masalah kedua: tidak ada versi yang dikunci
Bahkan ketika tim menyimpan skill di satu tempat, metode berbagi yang umum adalah langkah penyalinan: skrip setup, baris curl dalam dokumen onboarding, atau shell alias yang menyinkronkan sebuah folder. Semua metode tersebut memasang apa pun yang saat ini berada di ujung branch.
Artinya, dua developer yang menggunakan commit yang sama dari aplikasi yang sama dapat menjalankan instruksi yang berbeda karena mereka melakukan sinkronisasi pada hari yang berbeda. Artinya juga, Anda tidak dapat menjawab pertanyaan penting setelah agent menjalankan tugas dengan buruk: versi skill mana yang menghasilkan ini? Tanpa revisi yang tercatat, proses tersebut tidak dapat direproduksi sehingga laporan bug tidak dapat ditindaklanjuti.
Masalah ketiga: tidak ada yang tahu bahwa skill tersebut masih berfungsi
Skill tidak memiliki compiler. Skill berisi instruksi untuk model, sehingga dapat berhenti berfungsi meskipun isi file tetap identik byte demi byte. Upgrade model dapat mengubah tingkat kepatuhan terhadap instruksi yang panjang. Command-line tool yang dipanggil skill dapat mengganti nama flag. URL dalam file referensi dapat mulai mengembalikan 404, lalu agent bekerja berdasarkan halaman error tersebut.
Tidak satu pun dari kasus itu menimbulkan kegagalan yang terlihat jelas. Agent tetap memberikan jawaban. Namun, kualitas jawabannya lebih buruk daripada bulan lalu, dan perubahan seperti ini sulit diketahui jika diperiksa satu pull request demi satu.
Solusi yang disediakan tools pada 2026
Beberapa solusi mulai tersedia saat ini, tetapi pendekatannya berbeda dalam menentukan lokasi penyimpanan versi.
Lockfile. Command-line tool skills dari Vercel Labs (vercel-labs/skills, berlisensi MIT, v1.7.2 per 9 October 2026) menginstal skill dari repositori git ke direktori yang diharapkan oleh agent Anda. Tool ini memahami struktur lebih dari seventy agent. npx skills add <repo> menginstal, npx skills update memperbarui, dan npx skills list menampilkan skill yang tersedia. Tool ini menyimpan dua lock file. Lock file global di ~/.agents/.skill-lock.json mencatat instalasi untuk satu user. Sejak v1.4.1 (20 February 2026), instalasi dalam cakupan project juga menulis skills-lock.json di root project. Source code tool menyatakan bahwa file tersebut harus di-commit ke version control. npx skills experimental_install memulihkan skill project dari file tersebut. Issue 283 meminta command skills install untuk memulihkan lock file global pada machine lain. Issue itu ditutup dengan status not planned pada 5 November 2026. Maintainer menyebutnya sebagai permintaan yang sama dengan issue 549. Perlakukan kedua issue tersebut sebagai laporan status. Lockfile per project sudah tersedia. Dalam v1.8.1 yang dirilis, command pemulihan masih diberi label experimental dalam help. Namun, npx skills install tanpa source juga memulihkan lockfile project.
Spesifikasi dan pengujian. SkillSpec menggunakan pendekatan yang berbeda. Tool ini memperlakukan SKILL.md sebagai contract yang harus diperiksa, bukan sebagai prosa yang dapat dipercaya. Tujuannya adalah membuat skill "followable, testable, and provable". skillspec doctor <path> melaporkan bagian tempat agent kemungkinan kehilangan konteks. skillspec boundary map <path> menampilkan isi skill, sedangkan skillspec boundary assess <path> melaporkan resource yang dapat diaksesnya dan mengurutkannya berdasarkan risiko. Tool ini adalah Rust crate dengan lisensi ganda MIT atau Apache 2.0. Version 0.2.2 dipublikasikan pada 29 July 2026 dan masih menjadi versi terbaru di crates.io per 10 October 2026. Instal version yang ditetapkan, bukan version terbaru:
cargo install skillspec --version 0.2.2 --locked
skillspec --versionSejak Cargo 1.100 dirilis pada 12 November 2026, cargo install secara default menggunakan lockfile yang dikemas, dan --locked tidak melakukan apa pun. skillspec --version seharusnya mencetak 0.2.2. Angka yang berbeda menunjukkan bahwa binary yang lebih lama di bagian awal PATH Anda sedang digunakan.
Praktik vendor. Google menjelaskan cara membangun skill dalam google/skills melalui tulisan tentang cara membangun, menguji, dan menskalakan skill agent. Jika faktor skalanya diabaikan, mekanismenya adalah continuous integration (CI) biasa. Setiap skill harus melewati linter untuk metadata frontmatter, jumlah baris, struktur direktori, dan penamaan sebelum di-merge. Link checker menggagalkan build jika ada URL yang mengembalikan 404. Ini menangkap link yang terlihat masuk akal tetapi dibuat oleh agent. Author harus menyediakan rangkaian prompt evaluasi dan rubric penilaian bersama skill. Job evaluasi terjadwal kemudian dijalankan setiap minggu terhadap seluruh library untuk mendeteksi regresi. Setiap skill juga memiliki owner yang ditetapkan dan diharapkan memperbaikinya ketika kualitas menurun.
Pola yang mendasari ketiga jawaban
Anda tidak harus memilih salah satu dari ketiganya. Di balik ketiganya terdapat satu pola, dan git biasa menyediakan semua yang Anda perlukan.
- Satu sumber kebenaran. Skill memiliki tepat satu lokasi, dan setiap repository merujuk ke lokasi tersebut tanpa menyimpan salinannya.
- Versi yang ditetapkan untuk setiap repository. Setiap proyek mencatat revisi persis yang digunakannya, sehingga upgrade menjadi sebuah commit dalam proyek tersebut, lengkap dengan author dan tanggal.
- Smoke test untuk setiap skill. Satu pemeriksaan yang dapat dijalankan untuk membuktikan bahwa skill tersebut masih menghasilkan hasil yang dijanjikan.
- Jalur review. Perubahan pada skill bersama harus melalui review, dan setiap konsumen dapat melihat diff sebelum menerapkannya.
Itulah pola sebuah dependency. Skill menjadi artefak bersama lebih cepat daripada perkembangan tooling di sekitarnya, sehingga tooling yang sudah Anda percayai menjadi pilihan paling aman.
Tata letak untuk tim kecil pada remote git yang di-host sendiri
Satu repositori menyimpan skills. Tidak ada hal lain di dalamnya, sehingga riwayatnya berfungsi sebagai changelog instruksi.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdRilis direpresentasikan sebagai tag. Gunakan annotated tag karena tag tersebut menyertakan pesan dan tanggal. Tulis pesan berdasarkan alasan konsumen memerlukan pembaruan tersebut:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Jika remote Anda adalah Gitea, Forgejo, GitLab, atau bare repository melalui SSH pada VPS milik Anda sendiri, tidak ada bagian berikutnya yang berubah. Semua yang digunakan di sini hanyalah git dan sebuah symlink.
Pinning dengan git submodule
Submodule mencatat satu commit tertentu dari repository lain di dalam repository Anda. Catatan tersebut adalah pin. Pada setiap project 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 adalah bagian yang membuat cara ini berfungsi. Entri skill pada level project dapat berupa symlink ke direktori lain di disk, dan Claude Code mengikutinya lalu membaca SKILL.md dari target tersebut. Dengan demikian, skill dimuat sebagai skill project biasa, sedangkan byte-nya berada di submodule pada commit yang Anda pilih.
Periksa pin:
git submodule statusBaris yang benar diawali spasi, lalu commit, path, dan tag terdekat:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)Awalan - berarti submodule belum pernah diinisialisasi, sehingga .claude/skills/api-review mengarah ke sesuatu yang tidak ada dan skill tidak dimuat tanpa pesan. Perbaiki dengan git submodule update --init. Awalan + berarti commit yang telah di-check out berbeda dari commit yang dicatat, sehingga developer tersebut menjalankan instruksi yang tidak dimiliki developer lain. Clone baru memerlukan git clone --recurse-submodules, dan perintah tersebut harus dicantumkan dalam README, karena clone biasa membiarkan vendor/agent-skills kosong dan tidak menampilkan error.
Upgrade 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 adalah jalur review. Baris tersebut menampilkan perubahan yang sama dengan yang akan dilihat semua repository pengguna lainnya dan dapat dimasukkan ke pull request.
Sebagai gantinya, gunakan pinning dengan marketplace plugin
Jika Anda tidak ingin meminta setiap developer mempelajari submodule, sistem plugin Claude Code dapat menangani distribusinya untuk Anda dan mendukung remote yang di-host sendiri. Letakkan katalog di .claude-plugin/marketplace.json dalam repository 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"
}
}
]
}Ada dua sumber berbeda yang digunakan di sini, dan kekeliruan antara keduanya merupakan kesalahan yang umum. Source marketplace, yaitu lokasi katalog diambil, menerima ref untuk branch atau tag dan, pada Claude Code v2.1.324 atau yang lebih baru, full lowercase commit SHA; source ini tidak menerima field sha terpisah. Source plugin di dalam katalog menerima keduanya. Jika keduanya diatur, sha menjadi pin yang efektif. Pin katalog melalui ref pada source marketplace-nya, dan pin plugin melalui sha pada entri katalog. Nama tipenya juga berbeda. Di dalam katalog, url berarti repository git yang akan di-clone. Dalam source marketplace, url berarti tautan langsung ke file marketplace.json, sedangkan repository git adalah git.
Setiap repository yang menggunakan plugin kemudian mendeklarasikan marketplace tersebut dalam .claude/settings.json yang di-commit:
{
"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 seorang rekan tim setelah mereka menerima dialog kepercayaan workspace untuk folder project, tanpa memerlukan halaman wiki yang menjelaskan langkah tersebut. Entri katalog mengarah ke URL git, bukan path relatif. Karena itu, plugin tidak di-install hanya dari pengaturan repository. Setiap rekan tim menjalankan claude plugin install team-skills@acme-agents --scope project sekali. Sebelum itu, Claude Code melaporkan bahwa plugin diaktifkan dalam pengaturan project, tetapi belum di-install. Setelah terpasang, skills dapat dipanggil melalui /team-skills:api-review karena plugin skills menggunakan namespace berdasarkan nama plugin dan tidak dapat bentrok dengan project skill yang memiliki nama sama. Setelah Anda melakukan push tag baru dan memperbarui pin dalam katalog serta repository yang menggunakan plugin, consumer memperbarui marketplace dengan /plugin marketplace update acme-agents, lalu menjalankan /reload-plugins jika ringkasan instalasi memintanya.
Menulis smoke test untuk satu skill
Smoke test adalah skrip agen yang dijalankan terhadap fixture dengan kesalahan yang diketahui, ditambah satu asersi. Claude Code berjalan secara non-interaktif dengan -p, dan skill yang dipanggil pengguna dapat bekerja di sana: masukkan /skill-name ke dalam string prompt dan itu akan diperluas sebelum eksekusi dimulai.
#!/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 adalah file pendek dengan satu kesalahan yang disengaja. Asersinya adalah skill tersebut menyebutkan file tersebut. jq -e keluar dengan status non-nol ketika filternya menghasilkan null, jadi skill yang berhenti mendeteksi kesalahan yang disisipkan akan menggagalkan skrip. claude sendiri keluar dengan status non-nol ketika eksekusi gagal, dan set -euo pipefail mengubah salah satu kegagalan tersebut menjadi tes yang gagal.
Model mengubah susunan kata jawabannya di antara setiap eksekusi, jadi jangan pernah melakukan asersi pada satu kalimat utuh. Lakukan asersi pada pengenal yang seharusnya dikeluarkan oleh skill, atau pada field dari skema yang Anda minta, dan buat fixture tetap kecil agar eksekusi tetap hemat biaya.
Dalam CI, tambahkan --bare. Tanpanya, claude -p akan memuat konteks yang sama dengan sesi interaktif, termasuk hook, plugin, dan CLAUDE.md dari mesin tempat ia berjalan, sehingga konfigurasi pribadi rekan tim dapat mengubah hasilnya. Bare mode melewati penemuan otomatis kecuali untuk skill di .claude/skills/ di bawah direktori yang disediakan secara eksplisit dengan --add-dir; mode ini melewati skill proyek yang sedang Anda uji di sini, jadi muat skill tersebut secara eksplisit. Bare mode juga tidak membaca login langganan Anda, jadi atur ANTHROPIC_API_KEY di lingkungan 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 jsonPlugin yang dimuat dengan --plugin-dir mengambil namanya dari .claude-plugin/plugin.json, dan tanpa manifes tersebut, plugin dinamai berdasarkan direktorinya. Commit plugin.json dengan "name": "team-skills" di sebelah katalog dalam repositori skill, atau perintah di atas harus memanggil /agent-skills:api-review sebagai gantinya.
Dengan --output-format stream-json, event system/init melaporkan plugin mana yang dimuat dan membawa array plugin_errors untuk plugin yang gagal dimuat. Event ini membuka stream kecuali jika event startup muncul lebih dulu. Gagalkan job CI jika plugin_errors tidak kosong. Hal ini akan menangkap pin yang ditujukan ke revisi yang sudah tidak ada, yang jika tidak, akan tampak sebagai agen yang diam-diam mengabaikan aturan internal Anda.
Keterampilan bersama adalah instruksi yang dapat dieksekusi
Dua fitur membuat pernyataan tersebut menjadi nyata, dan keduanya penting ketika file berasal dari tim lain.
Pertama, SKILL.md dapat menjalankan perintah shell sebelum model membaca apa pun. Baris seperti ini di dalam isi adalah pra-pemrosesan:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Perintah tersebut berjalan pada mesin yang memuat keterampilan, dan keluarannya menggantikan placeholder dalam teks yang diterima model. Blok yang dibuka dengan tiga backtick diikuti oleh ! menjalankan beberapa perintah dengan cara yang sama. Tidak ada seorang pun yang dimintai konfirmasi untuk hal ini saat runtime. Claude Code memeriksa setiap perintah terhadap aturan izin Anda. Di luar mode otomatis, perintah yang tidak diizinkan oleh aturan tersebut akan membatalkan keterampilan, kecuali jika keterampilan tersebut telah memberikan pra-persetujuan melalui fitur kedua di bawah ini. Aturan tolak dan tanya tetap mengesampingkan pra-persetujuan tersebut. Membaca keterampilan bersama berarti membaca substitusi perintahnya.
Kedua, frontmatter dapat memberikan pra-persetujuan alat. allowed-tools memberikan alat yang terdaftar tanpa permintaan izin untuk giliran yang memanggil keterampilan tersebut. Kepercayaan ruang kerja tidak membatasi pemberian tersebut: Claude Code menerapkan allowed-tools dari keterampilan proyek bahkan dalam -p yang dijalankan di folder yang belum dipercaya siapa pun. Dokumentasi Claude Code menyatakan konsekuensinya dengan jelas: sebuah keterampilan dapat memberikan akses alat yang luas kepada dirinya sendiri, jadi tinjau allowed-tools dari keterampilan yang dimasukkan ke dalam repositori sebelum Anda menjalankan Claude Code di sana. Sebuah organisasi dapat menahan bidang tersebut dari keterampilan proyek dan pribadi dengan mengatur allowManagedPermissionRulesOnly dalam pengaturan terkelola, yang memerlukan Claude Code v2.1.282 atau lebih baru.
Jadi, tangani pembaruan keterampilan persis seperti pembaruan dependensi. Sematkan berdasarkan commit yang tepat di mana pun mekanismenya memungkinkan, karena tag dapat dipindahkan dan branch berpindah secara definisi. Pada mesin yang dikunci, "disableSkillShellExecution": true dalam pengaturan menggantikan setiap substitusi perintah dengan teks literal [shell command execution disabled by policy] alih-alih menjalankannya, dan jika diterapkan melalui pengaturan terkelola, pengguna tidak dapat mengesampingkannya. Keterampilan yang dibundel dan dikelola dikecualikan dari pengaturan tersebut.
Perhatian yang sama berlaku untuk apa yang dibaca oleh sebuah keterampilan. Keterampilan yang menjalankan env atau membuka file konfigurasi akan menarik apa pun yang ditemukannya ke dalam konteks model, yang merupakan kegagalan yang dibahas dalam menjaga rahasia agar tidak masuk ke agen yang Anda jalankan. Keterampilan yang mengambil halaman atau menjalankan kueri adalah paparan yang sama yang diarahkan ke luar, karena teks yang diambil masuk ke dalam konteks dan terlihat persis seperti instruksi yang Anda tulis, sebuah batasan yang layak dibaca sebelum Anda mengarahkan agen ke instance SearXNG Anda sendiri untuk pencarian web.
Yang perlu dibaca saat menaikkan versi
- Diff dari setiap isi
SKILL.md, karena teks tersebut merupakan instruksi yang akan diikuti agen Anda. - Setiap substitusi perintah, karena perintah tersebut dijalankan pada mesin Anda saat skill dimuat.
- Setiap perubahan pada
allowed-tools, karena baris tersebut memberikan akses ke tool tanpa meminta konfirmasi. - Pengujian di balik tag tersebut. Jika repository bersama menjalankan smoke test sendiri di CI, tag yang Anda jadikan acuan harus memiliki hasil pengujian berhasil yang terlampir.
Reviewer yang tidak dapat membaca seluruh diff dalam sepuluh menit sedang meninjau skill yang sudah terlalu besar. Pisahkan skill tersebut. Argumen yang sama berlaku untuk dokumen repository yang dibaca agen Anda: simpan aturan yang berlaku jangka panjang dalam file yang dijelaskan di pemisahan AGENTS.md dan HUMAN.md, simpan alasan arsitektur dalam DESIGN.md yang ditulis untuk agen, dan pertahankan skill sebagai prosedur yang terbatas cakupannya.
Saat model atau tool merusak sebuah skill
Beberapa hal di balik sebuah skill dapat berubah tanpa ada yang mengeditnya. Upgrade model mengubah tingkat keandalan dalam mengikuti instruksi yang panjang, sehingga skill yang bergantung pada model untuk mencapai langkah sembilan mungkin tidak lagi mencapainya. Tool command line mengganti nama sebuah flag, sehingga agent menjalankan flag lama, membaca error, lalu berimprovisasi. URL yang dirujuk mulai mengembalikan 404. Harness agent mengubah cara pemilihan skill, sehingga description yang sebelumnya memenangkan pencocokan tidak lagi terpilih. Jika prosedur mulai berhenti lebih awal seperti itu, tidak ada version bump yang dapat memperbaikinya. Instruksi itu sendiri memerlukan struktur yang memaksa langkah-langkah terakhir dijalankan. Pendekatan ini digunakan dalam skill unlazy dan metode Depth Tree-nya.
Inilah alasan smoke test menjadi bagian terpenting dalam pengaturan ini. Jalankan pengujian setiap skill secara terjadwal dan setiap kali melakukan push. Google menjalankan evaluation job setiap minggu terhadap seluruh library untuk alasan ini. Weekly cron job pada VPS kecil sudah cukup untuk tim dengan sepuluh skill. Ini satu-satunya cara untuk mengetahui kerusakan sebelum developer menemukannya.
Portabilitas juga membantu. Spesifikasi Agent Skills membatasi frontmatter hingga enam key. Dengan demikian, skill yang ditulis sesuai spesifikasi tersebut dapat dimuat pada tool selain tool yang menjadi target awalnya. Sebaliknya, setiap key khusus harness yang Anda tambahkan merupakan taruhan pada satu vendor. Menulis skill yang tetap berfungsi setelah pergantian model adalah disiplin tersendiri, yang dibahas dalam membuat skill berfungsi pada model apa pun.
FAQ
Bagaimana cara membagikan satu skill agent ke beberapa repositori?
Simpan skill di repositori git khusus, beri tag pada setiap rilis, lalu minta setiap proyek pengguna merujuk tag tersebut, bukan menyalin file. Ada dua mekanisme yang dapat digunakan. Submodule git merekam commit tertentu, sedangkan symlink dari .claude/skills/<name> ke dalam submodule membuatnya dimuat sebagai skill proyek biasa. Marketplace plugin menjalankan fungsi yang sama melalui /plugin, dengan pin yang dideklarasikan dalam .claude/settings.json repositori pengguna. Keduanya menyimpan versi dalam riwayat git, sehingga Anda dapat menentukan instruksi yang menghasilkan suatu proses agent.
Apakah skill agent dapat dipatok ke versi tertentu?
Tidak dari dalam SKILL.md, karena frontmatter tersebut tidak memiliki key version. Pin harus berasal dari lapisan di sekitar file. Submodule git secara bawaan mematok commit tertentu. Dalam marketplace plugin Claude Code, sumber plugin menerima ref untuk branch atau tag dan sha untuk commit tertentu, dan sha digunakan jika keduanya tersedia. Sumber marketplace itu sendiri menerima ref untuk branch, tag, atau, pada Claude Code v2.1.324 atau yang lebih baru, SHA commit lengkap dalam huruf kecil. Utamakan pin commit karena tag dapat dipindahkan setelah Anda meninjaunya.
Apa yang harus diperiksa dalam smoke test skill?
Periksa sesuatu yang stabil. Jalankan skill secara non-interaktif terhadap fixture yang berisi kesalahan yang diketahui, lalu periksa apakah identifier tertentu muncul dalam output, misalnya id aturan yang seharusnya dilaporkan oleh skill. Meminta output terstruktur dengan --output-format json dan --json-schema membuat pemeriksaan menjadi tepat, sedangkan jq -e membuat skrip gagal jika nilainya tidak ada. Jangan memeriksa seluruh kalimat karena model dapat menyusun ulang jawabannya pada setiap proses.
Apakah aman menginstal skill bersama dari repositori tim lain?
Perlakukan skill tersebut sebagai dependensi kode karena berisi instruksi yang dapat dieksekusi. SKILL.md dapat menjalankan perintah shell saat dimuat melalui bentuk substitusi perintah !, dan field frontmatter allowed-tools dapat menyetujui tool terlebih dahulu tanpa prompt. Baca diff pada setiap pembaruan, gunakan pin commit tertentu alih-alih branch, dan utamakan sumber yang dikendalikan oleh tim Anda sendiri. Pada mesin terkelola, "disableSkillShellExecution": true dalam settings menghentikan substitusi perintah pada skill pengguna, proyek, plugin, dan direktori tambahan; skill yang dibundel dan dikelola tidak terpengaruh.
Apakah skill bersama akan berfungsi pada agent selain Claude Code?
Hal ini bergantung pada frontmatter yang digunakan. Spesifikasi Agent Skills mendefinisikan enam key: name, description, license, compatibility, metadata, dan allowed-tools. Skill yang hanya menggunakan key tersebut dapat dimuat pada tool yang mengimplementasikan spesifikasi ini, dan juga dapat dimuat di Claude Code tanpa perubahan. Key dan fitur body khusus harness di luar spesifikasi dapat diabaikan atau ditolak oleh tool lain. Karena itu, jangan gunakan fitur tersebut pada skill yang ingin Anda bagikan secara luas.