Yazan Ajan yeteneklerini depolar arası paylaşma ve yönetme
Ajan yeteneklerini kopyalamak yerine bağımlılık olarak yönetin. Tek bir depo üzerinden sürüm sabitleme ve duman testi yöntemleriyle kod tutarsızlığını nasıl önleyeceğinizi öğrenin.
Ajan yeteneklerini depolar arasında paylaşma
Ajan yeteneklerini depolar arasında paylaşmak için dosyayı kopyalamayı bırakın ve ona bağımlı hale gelin. Tek bir yetenek deposu tutun, etiketleyin ve her projenin bir etiketi sabitlemesine izin verin. Ardından her yetenek için bir duman testi (smoke test) ekleyin ve her sürüm yükseltmesini bir bağımlılık yükseltmesini inceler gibi inceleyin.
Bu süreç dört bölümden oluşur: paylaşılan bir doğruluk kaynağı, depo başına sabitlenmiş bir sürüm, yetenek başına bir duman testi ve bir inceleme yolu. Aşağıdaki her şey, her bir bölümün neden var olduğunu, 2026 yılında kullanıma sunulan araçların bu konuda neler yaptığını ve tüm bu yapının dışarıdan hiçbir servis kullanılmadan, kendi kendine barındırılan (self-hosted) bir git uzak sunucusu üzerinde nasıl kurulacağını açıklar.
Ajan yeteneği, bir SKILL.md dosyasını ve ihtiyaç duyduğu tüm betikleri ve referans dosyalarını içeren bir klasördür. Eğer bu birim yeniyse, önce ajan yeteneğinin ne olduğu ve SKILL.md dosyasının nasıl çalıştığı konusunu okuyun. Bu sayfa, söz konusu birimin tedarik zinciri hakkındadır.
Bir yeteneğin nerede barındığı ve paylaşımın neden zor olduğu
Claude Code, yetenekleri üç farklı konumdan yükler ve yetenek dokümantasyonu her bir yolu belirtir.
~/.claude/skills/<skill-name>/SKILL.mdkişiseldir. Sadece sizin projelerinizde yüklenir, başkalarının projelerinde yüklenmez..claude/skills/<skill-name>/SKILL.mdproje düzeyindedir. Depoyu (repository) kim klonlarsa onun için yüklenir.<plugin>/skills/<skill-name>/SKILL.mdbir eklenti içinde gelir. Eklentinin etkinleştirildiği her yerde yüklenir.
Ekip için en kullanışlı olanı ortadakidir; çünkü bu yetenek commit edilir ve depoyu klonlayan herkes ona sahip olur. Sorun da tam burada başlar. .claude/skills/ içindeki bir yetenek tek bir depoya aittir. Sekiz deponuz olduğunu varsayalım; bu durumda yetenek sekiz kez kopyalanmış olur.
Ön bilgi (frontmatter) kısmı bu konuda bir çözüm sunmaz. Agent Skills spesifikasyonu altı anahtara izin verir ve dağıtım yolları, başka bir anahtar kullandığınızda desteklenen listeyi yazdırır:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameNeyin eksik olduğuna dikkat edin: version anahtarı yoktur. Dosya içinde hangi kopyanın daha yeni olduğunu kaydeden hiçbir veri bulunmaz. Bir yetenek paket değil, bir doküman olduğu için bu durum makuldür. Ancak bu, sürüm yönetiminin dosyanın dışındaki katmandan gelmesi gerektiği anlamına gelir ve o katman sizin sorumluluğunuzdadır.
Sorun bir: sessizce birbirinden uzaklaşan sekiz kopya
Kopyala-yapıştır yöntemi ilk gün çalışır. Altmışıncı günde ise başarısız olur. Bir kişi payments deposundaki hatalı bir talimatı düzeltir ancak diğer yedisine dokunmaz. Başka biri orders içinde sayfalama ile ilgili bir kural ekler. Artık aynı yetenek ismi, ajanın hangi dizinde başlatıldığına bağlı olarak iki farklı değerlendirme sunar ve geliştiricilerin bundan haberi olmaz.
Hata durumu oluşmadığı için bu başarısızlık sessizce gerçekleşir. Bir yetenek düz metinden ibarettir. Güncelliğini yitirmiş bir talimat, maliyeti yüksek olan kendinden emin ancak yanlış bir cevap üretir. Ajan içerisinde kopyanızı diğerleriyle karşılaştıran bir mekanizma yoktur; bu nedenle tek belirti, bir kişinin iki deponun birbiriyle çeliştiğini fark etmesidir.
Sorun iki: hiçbir sürüm sabitlenmiyor
Bir ekip yetenekleri tek bir yerde tutsa bile, yaygın paylaşım yöntemi bir kopyalama adımıdır: bir kurulum betiği, işe alım dokümanındaki bir curl satırı veya bir klasörü eşitleyen bir shell alias. Bunların tümü, o anda branch'in en başında ne varsa onu kurar.
Bu durum, aynı uygulamanın aynı commit'i üzerinde çalışan iki geliştiricinin, eşitleme işlemini farklı günlerde yaptıkları için farklı talimatlar çalıştırabileceği anlamına gelir. Ayrıca, hatalı bir agent çalışmasından sonra önemli olan şu soruyu yanıtlayamayacağınız anlamına da gelir: bu yeteneğin hangi sürümü bunu üretti? Kaydedilmiş bir revizyon olmadan çalışma tekrarlanamaz, bu nedenle hata raporu üzerinde işlem yapılamaz.
Üçüncü sorun: becerinin hala çalıştığını kimse bilemez
Bir becerinin derleyicisi yoktur. Bu, bir modele yönelik talimatlar bütünüdür; bu nedenle dosya bayt düzeyinde aynı kalsa bile çalışma yetisini kaybedebilir. Model yükseltmeleri, uzun bir talimatın ne kadar yakından takip edileceğini değiştirir. Beceri tarafından çağrılan bir komut satırı aracı bir bayrağı (flag) yeniden adlandırabilir. Bir referans dosyasındaki URL 404 hatası döndürmeye başlayabilir ve aracı, hata sayfası üzerinden çalışmaya devam eder.
Bu durumların hiçbirinde belirgin bir hata oluşmaz. Aracı hala yanıt verir. Yanıt sadece geçen aya göre daha kötüdür; bu da her bir pull request aşamasında fark edilmesi zor bir durumdur.
2026 yılında kullanıma sunulan araçların çözdüğü sorunlar
Şu anda birçok yanıt gelmekte ve sürüm bilgisinin nerede tutulması gerektiği konusunda görüş ayrılıkları bulunmaktadır.
Lockfile dosyaları. Vercel Labs tarafından geliştirilen skills komut satırı aracı (vercel-labs/skills, MIT lisanslı, 5 Ağustos 2026 itibarıyla v1.5.22), yetenekleri (skills) bir git deposundan ajanınızın beklediği dizine kurar ve yetmişten fazla ajan için dizin yapısını bilir. npx skills add <repo> kurulum yapar, npx skills update yükseltme yapar ve npx skills list mevcut olanları listeler. Kurulanların kaydı depo başına değil kullanıcı başına bir kez tutulur; projedeki açık bir istek (issue 283), lock dosyasındaki tüm takip edilen yetenekleri yeniden kuran bir skills install komutu talep etmektedir; böylece ikinci bir makine aynı setle yapılandırılabilir. Bu isteği bir durum raporu olarak değerlendirin. Lockfile fikri kesinleşmiştir. Proje bazlı kısmı ise halen geliştirilmektedir.
Spesifikasyonlar ve testler. SkillSpec konuya farklı bir açıdan yaklaşır. Bir SKILL.md dosyasını güvenilmesi gereken bir metin yerine kontrol edilmesi gereken bir sözleşme olarak ele alır; amacı yetenekleri "izlenebilir, test edilebilir ve kanıtlanabilir" kılmaktır. skillspec doctor <path>, ajanın iş parçacığını (thread) nerede bırakma ihtimalinin yüksek olduğunu raporlar. skillspec boundary map <path>, yeteneğin nelere erişebileceğini bildirir ve skillspec boundary assess <path> bu bulguları risk seviyesine göre sıralar. Bu bir Rust kütüphanesidir, MIT veya Apache 2.0 ile çift lisanslıdır ve 29 Temmuz 2026 itibarıyla 0.2.2 sürümündedir. En yeni sürüm yerine sabitlenmiş sürümü kurun:
cargo install skillspec --version 0.2.2 --locked
skillspec --version--locked, kütüphanenin yayınlandığı bağımlılık sürümleriyle derleme yapar, böylece derleme süreci kontrolünüz dışında değişmez. skillspec --version komutu 0.2.2 çıktısını vermelidir. Farklı bir sayı, PATH yolunuzdaki daha eski bir ikili dosyanın öncelik kazandığı anlamına gelir.
Vendor uygulamaları. Google, google/skills içindeki yetenekleri nasıl inşa ettiğini ajan yeteneklerini inşa etme, test etme ve ölçeklendirme konulu bir yazıda açıklamıştır. Ölçeklendirme kısmını çıkardığınızda mekanizma standart bir sürekli entegrasyon (CI) sürecidir. Her yetenek, birleştirilmeden önce frontmatter meta verileri, satır sayısı, dizin düzeni ve isimlendirme standartları için linter kontrollerinden geçer. Bir bağlantı denetleyicisi (link checker), 404 hatası döndüren herhangi bir URL'de derlemeyi durdurur; bu, ajanın uydurduğu olası bağlantıları yakalar. Yazarlar, yetenekle birlikte bir değerlendirme istemi paketi ve puanlama kriteri sunmak zorundadır. Planlanmış değerlendirme işleri, gerilemeleri yakalamak için tüm kütüphane üzerinde haftalık olarak çalıştırılır ve her yeteneğin, kalite düştüğünde düzeltmesi beklenen atanmış bir sahibi vardır.
Üç yanıtın altındaki ortak örüntü
Bunlardan birini seçmek zorunda değilsiniz. Hepsini kapsayan tek bir yapı mevcuttur ve standart git size bunun tamamını sunar.
- Tek bir doğruluk kaynağı. Yeteneğin tam olarak bir ana merkezi vardır ve her depo, bir kopyasını tutmak yerine bu merkeze referans verir.
- Her depo için sabitlenmiş bir sürüm. Her proje kullandığı kesin revizyonu kaydeder; bu nedenle yükseltme işlemi, o projede yazar ve tarih bilgisi içeren bir commit ile gerçekleştirilir.
- Her yetenek için bir duman testi (smoke test). Yeteneğin vaat ettiği sonucu hala ürettiğini kanıtlayan çalıştırılabilir bir kontrol.
- Bir inceleme yolu. Paylaşılan bir yetenekte yapılan değişiklik incelemeden geçer ve her kullanıcı, değişikliği kabul etmeden önce farkları (diff) görür.
Bağımlılığın yapısı budur. Yetenekler, etraflarında araçlar gelişmeden önce paylaşılan birer yapıta dönüştü; bu nedenle halihazırda güvendiğiniz araçlar, başvurulacak en güvenli yöntemdir.
Küçük bir ekip için self-hosted git uzak sunucu düzeni
Tek bir depo, tüm becerileri barındırır. İçinde başka hiçbir şey bulunmaz; bu sayede geçmişi, talimatların bir değişiklik günlüğü (changelog) gibi okunmasını sağlar.
agent-skills/
skills/
api-review/
SKILL.md
release-notes/
SKILL.md
tests/
api-review.sh
release-notes.sh
CHANGELOG.mdSürümler (releases) etiketlerden (tags) oluşur. Açıklamalı etiketler kullanın; çünkü bu etiketler bir mesaj ve tarih bilgisi taşır. Mesajı, bir kullanıcının sürüm yükseltmeyi neden isteyeceğine dair gerekçeyi içerecek şekilde yazın:
git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0Uzak sunucunuz Gitea, Forgejo, GitLab veya kendi VPS'niz üzerinde SSH üzerinden çalışan çıplak (bare) bir depo ise, aşağıdakilerin hiçbiri değişmez. Buradaki her şey git ve bir sembolik bağdan (symlink) ibarettir.
git submodule ile sabitleme
Bir submodule, başka bir deponun tam olarak bir commit'ini kendi deponuzun içinde kayıt altına alır. Bu kayıt, sabitleme (pinning) işlemidir. Her tüketici projede:
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"Sembolik bağ (symlink), bu mekanizmanın çalışmasını sağlayan kısımdır. Proje seviyesindeki bir yetenek girişi, diskteki başka bir dizine işaret eden bir sembolik bağ olabilir; Claude Code bunu takip eder ve hedefteki SKILL.md dosyasını okur. Böylece yetenek normal bir proje yeteneği gibi yüklenirken, veriler seçtiğiniz bir commit'teki submodule içinde barınır.
Sabitlemeyi kontrol edin:
git submodule statusSağlıklı bir satır bir boşluk, ardından commit, ardından yol ve en yakın etiket (tag) ile başlar:
4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)Başta yer alan bir -, submodule'un hiçbir zaman başlatılmadığı anlamına gelir; bu durumda .claude/skills/api-review hiçbir yeri işaret etmez ve yetenek sessizce yüklenmez. Bunu git submodule update --init ile düzeltin. Başta yer alan bir +, check-out edilen commit'in kayıtlı olandan farklı olduğu anlamına gelir; bu da ilgili geliştiricinin başka kimsenin sahip olmadığı talimatları çalıştırdığı demektir. Yeni klonlar git clone --recurse-submodules komutuna ihtiyaç duyar ve bu satır README dosyasında yer almalıdır, çünkü düz bir klon işlemi vendor/agent-skills dizinini boş bırakır ve herhangi bir hata mesajı vermez.
Yükseltme işlemi bilinçli bir tercihtir ve tüm amaç da budur:
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"diff satırı inceleme yoludur. Diğer tüm tüketici depoların göreceği değişikliğin aynısını gösterir ve bir pull request içine dahil edilebilir.
Bunun yerine bir eklenti pazaryeri ile sabitleme
Her geliştiriciden submodule öğrenmesini istemiyorsanız, Claude Code eklenti sistemi dağıtımı sizin yerinize yapar ve bu sistem self-hosted bir uzak sunucu ile çalışır. Yetenek deposundaki .claude-plugin/marketplace.json konumuna bir katalog yerleştirin:
{
"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"
}
}
]
}Burada iki farklı kaynak söz konusudur ve bunları birbirine karıştırmak yaygın bir hatadır. Kataloğun kendisinin çekildiği yer olan pazaryeri kaynağı, bir branch veya tag için ref değerini kabul eder ancak sha değerini kabul etmez. Katalog içindeki bir eklenti kaynağı ise her ikisini de kabul eder; her ikisi de ayarlandığında sha geçerli sabitleme (pin) değeridir. Dolayısıyla, tam commit sabitlemesi katalog girdisine aittir.
Bunu kullanan her depo, kendi commit edilmiş .claude/settings.json dosyasında pazaryerini şu şekilde tanımlar:
{
"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
}
}Proje klasörüne güvenen bir ekip üyesinin pazaryerini yüklemesi istenir ve eklenti, bunu yapmasını söyleyen bir wiki sayfasına gerek kalmadan kendisi için etkinleştirilir. Yetenekler daha sonra /team-skills:api-review komutuna yanıt verir, çünkü eklenti yetenekleri eklenti adına göre ad alanlandırılır (namespaced) ve aynı isimdeki bir proje yeteneği ile çakışamaz. Yeni bir tag push ettikten sonra, kullanıcılar /plugin marketplace update acme-agents ile yenileme yapar ve ardından yükleme özeti talep ederse /reload-plugins komutunu çalıştırır.
Bir yetenek için duman testi (smoke test) yazma
Duman testi, bilinen bir hataya sahip bir fikstür ve bir doğrulama (assertion) üzerinde çalıştırılan betik tabanlı bir aracıdır. Claude Code, -p ile etkileşimsiz olarak çalışır ve kullanıcı tarafından çağrılan bir yetenek burada işlev görür: istem dizisine /skill-name ekleyin; bu ifade, çalışma başlamadan önce genişletilir.
#!/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, içinde tek bir kasıtlı hata bulunan kısa bir dosyadır. Doğrulama, yeteneğin bu hatayı isimlendirmesi üzerinedir. jq -e, filtresi null ürettiğinde sıfır olmayan bir değerle çıkar; bu nedenle, ekilen hatayı yakalamayı bırakan bir yetenek betiği başarısız kılar. claude, çalışma başarısız olduğunda sıfır olmayan bir değerle çıkar ve set -euo pipefail, her iki başarısızlığı da başarısız bir test sonucuna dönüştürür.
Bir model, çalıştırmalar arasında yanıtlarını yeniden ifade eder; bu nedenle asla tüm bir cümle üzerinde doğrulama yapmayın. Yeteneğin yayması gereken bir tanımlayıcı veya talep ettiğiniz bir şemanın alanı üzerinde doğrulama yapın ve çalıştırmanın maliyetini düşük tutmak için fikstürü küçük tutun.
CI ortamında --bare ekleyin. Bu olmadan claude -p, etkileşimli bir oturumun yükleyeceği aynı bağlamı yükler; buna makine üzerindeki kancalar, eklentiler ve CLAUDE.md dahildir. Dolayısıyla bir ekip arkadaşının kişisel yapılandırması sonucu değiştirebilir. "Bare" modu tüm otomatik keşifleri atlar, bu da test ettiğiniz yeteneği de atlayacağı anlamına gelir; bu yüzden ilgili yeteneği açıkça yükleyin. "Bare" modu abonelik giriş bilgilerinizi de okumaz, bu nedenle önce ortamda ANTHROPIC_API_KEY değişkenini ayarlayın:
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--output-format stream-json ile, çalıştırmanın ilk olayı hangi eklentilerin yüklendiğini raporlar ve yüklenmeyenler için bir plugin_errors dizisi taşır. Boş olmayan bir plugin_errors durumunda CI işini başarısız sayın. Bu, artık var olmayan bir revizyona yönelik bir sabitlemeyi yakalar; aksi takdirde bu durum, aracın kurallarınızı sessizce görmezden gelmesi gibi görünür.
Paylaşılan bir yetenek yürütülebilir bir talimattır
İki özellik bunu gerçek kılar ve her ikisi de dosya başka bir ekipten geldiğinde önem taşır.
İlk olarak, bir SKILL.md, model herhangi bir şeyi okumadan önce kabuk komutlarını çalıştırabilir. Gövde içindeki bunun gibi bir satır ön işleme görevi görür:
- Current branch: !`git rev-parse --abbrev-ref HEAD`Komut, yeteneği yükleyen makinede çalışır ve çıktısı, modelin aldığı metindeki yer tutucunun yerini alır. Üç ters tırnak ve ardından ! ile açılan bir blok, birkaç komutu aynı şekilde çalıştırır. Çalışma zamanında kimse bunların hiçbirini onaylamaz. Paylaşılan bir yeteneği okumak, onun komut değişimlerini okumak anlamına gelir.
İkinci olarak, ön bilgi (frontmatter) araçları önceden onaylayabilir. allowed-tools, yeteneği çağıran oturum için izin istemi olmaksızın listelenen araçlara erişim sağlar. Bir proje yeteneği için bu izin, birisi klasör için çalışma alanı güven iletişim kutusunu kabul ettiğinde yürürlüğe girer. Claude Code belgeleri sonucu açıkça belirtir: bir depoya güvenmeden önce proje yeteneklerini gözden geçirin, çünkü bir yetenek kendisine geniş araç erişimi sağlayabilir.
Bu nedenle, bir yetenek güncellemesini tıpkı bir bağımlılık güncellemesi gibi ele alın. Mekanizma izin verdiği her yerde tam commit ile sabitleyin, çünkü bir etiket taşınabilir ve bir dal tanımı gereği hareket eder. Kısıtlanmış bir makinede, ayarlardaki "disableSkillShellExecution": true, her komut değişimini çalıştırmak yerine [shell command execution disabled by policy] değişmez metniyle değiştirir ve yönetilen ayarlar aracılığıyla uygulandığında kullanıcı bunu geçersiz kılamaz. Paketlenmiş ve yönetilen yetenekler bu ayardan muaftır.
Aynı özen, bir yeteneğin ne okuduğu için de geçerlidir. env çalıştıran veya bir yapılandırma dosyası açan bir yetenek, bulduğu her şeyi modelin bağlamına çeker; bu, sırları çalıştırdığınız aracıların dışında tutmak konusunda ele alınan hatadır. Bir sayfa getiren veya bir sorgu çalıştıran yetenek, dışa dönük aynı maruziyeti oluşturur; çünkü alınan metin, bağlama tıpkı sizin yazdığınız talimatlar gibi görünerek yerleşir. Bu, bir aracıyı web araması için kendi SearXNG örneğinize yönlendirmeden önce okunması gereken bir sınırdır.
Sürüm yükseltmelerinde nelerin incelenmesi gerektiği
- Her bir
SKILL.mdgövdesinin diff çıktısı; çünkü bu metin, temsilcinizin izleyeceği talimatları içerir. - Her komut ikamesi; çünkü bunlar, yetenek yüklendiğinde makinenizde çalıştırılır.
allowed-toolsüzerindeki her türlü değişiklik; çünkü bu satır, herhangi bir onay istemeden araçlara erişim izni verir.- Etiketin arkasındaki test çalışması. Eğer paylaşılan depo kendi CI duman testlerini (smoke tests) çalıştırıyorsa, sabitlediğiniz etiketin yeşil bir test sonucuna sahip olması gerekir.
Tüm diff çıktısını on dakika içinde okuyamayan bir incelemeci, gereğinden fazla büyümüş bir yeteneği inceliyor demektir. Bu yeteneği bölün. Aynı mantık, temsilcilerinizin okuduğu depo belgeleri için de geçerlidir: kalıcı kuralları AGENTS.md ve HUMAN.md ayrımı içinde açıklanan dosyalarda, mimari gerekçeleri ise temsilciler için yazılmış bir DESIGN.md dosyasında tutun ve yeteneklerin dar kapsamlı prosedürler olarak kalmasını sağlayın.
Bir model veya araç değişikliği bir yeteneği bozduğunda
Bir yetenek üzerinde kimse düzenleme yapmasa bile, arka planda birçok şey değişebilir. Bir model yükseltmesi, uzun bir talimatın ne kadar güvenilir bir şekilde takip edildiğini değiştirir; bu nedenle modelin dokuzuncu adıma ulaşmasına dayanan bir yetenek, artık o adıma ulaşamayabilir. Bir komut satırı aracı bir flag ismini değiştirir; bu durumda ajan eski flag ile çalıştırılır, hatayı okur ve doğaçlama yapar. Referans verilen bir URL 404 hatası döndürmeye başlar. Bir ajan harness'ı yetenekleri seçme yöntemini değiştirir; bu yüzden eskiden eşleşmeyi kazanan bir description artık kazanamaz hale gelir. Bir prosedür bu şekilde erken sonlanmaya başladığında, hiçbir sürüm yükseltmesi sorunu çözmez; talimatların kendisi, son adımları zorunlu kılan bir yapıya ihtiyaç duyar. Tembel olmayan yetenek ve onun Derinlik Ağacı yöntemi arkasındaki yaklaşım budur.
Bu düzenlemede smoke testinin bu kadar önemli olmasının nedeni budur. Her yeteneğin testini hem push anında hem de belirli bir zaman çizelgesine göre çalıştırın. Google, bu nedenle tüm kütüphanesine karşı değerlendirme işlerini haftalık olarak çalıştırır; on yeteneğe sahip bir ekip için küçük bir VPS üzerinde haftalık bir cron job yeterlidir. Bozulmayı bir geliştiriciden önce öğrenmenizin tek yolu budur.
Taşınabilirlik de yardımcı olur. Agent Skills spesifikasyonu, ön bilgileri (frontmatter) altı anahtarla sınırlar. Bu spesifikasyona göre yazılan bir yetenek, onu yazdığınız araç dışında başka araçlarda da çalışır; eklediğiniz her harness'a özgü anahtar ise tek bir tedarikçiye yapılan bir bahistir. Model değişimlerine dayanabilen yetenekler yazmak başlı başına bir disiplindir ve bir yeteneği her modelde çalışır hale getirme konusunda ele alınmıştır.
FAQ
Bir agent yeteneğini birden fazla depo arasında nasıl paylaşabilirim?
Yeteneği özel bir git deposuna yerleştirin, sürümleri etiketleyin (tag) ve her bir tüketici projenin dosyayı kopyalamak yerine bir etikete referans vermesini sağlayın. İki yöntem işe yarar. Bir git submodule tam bir commit kaydını tutar ve .claude/skills/<name> içinden submodule'a verilen bir sembolik bağ (symlink), yeteneğin normal bir proje yeteneği gibi yüklenmesini sağlar. Bir eklenti marketi, /plugin aracılığıyla aynı işi yapar ve sabitleme işlemi tüketici deponun .claude/settings.json dosyasında tanımlanır. Her iki yöntem de sürümü git geçmişine işler, böylece belirli bir agent çalışmasının hangi talimatlarla üretildiğini doğrulayabilirsiniz.
Bir agent yeteneğini belirli bir sürüme sabitleyebilir miyim?
SKILL.md içinden bu mümkün değildir, çünkü bu önbilgi (frontmatter) herhangi bir version anahtarına sahip değildir. Sabitleme işlemi, dosyanın bulunduğu katmandan yapılmalıdır. Bir git submodule, tasarımı gereği tam bir commit'i sabitler. Claude Code eklenti marketinde, bir eklenti kaynağı dal veya etiket için ref, tam bir commit için ise sha kabul eder; her ikisi de mevcut olduğunda sha önceliklidir. Market kaynağının kendisi yalnızca ref kabul eder. Commit sabitlemesini tercih edin, çünkü bir etiket siz inceledikten sonra değiştirilebilir.
Bir yetenek duman testi (smoke test) neleri doğrulamalıdır?
Kararlı bir durum üzerinde doğrulama yapın. Yeteneği, bilinen bir hata içeren bir fikstür üzerinde etkileşimsiz olarak çalıştırın ve ardından çıktıda belirli bir tanımlayıcının (örneğin yeteneğin raporlaması gereken bir kural kimliği) görünüp görünmediğini kontrol edin. --output-format json ve --json-schema ile yapılandırılmış çıktı talep etmek kontrolü kesinleştirir ve jq -e değer eksik olduğunda betiği başarısız kılar. Asla tam bir cümle üzerinde doğrulama yapmayın, çünkü bir model cevaplarını her çalıştırmada yeniden ifade edebilir.
Başka bir ekibin deposundan paylaşılan bir yeteneği yüklemek güvenli midir?
Bunu bir kod bağımlılığı olarak değerlendirin, çünkü bu yürütülebilir bir talimattır. Bir SKILL.md, yükleme sırasında ! komut ikamesi biçimiyle shell komutları çalıştırabilir ve önbilgi allowed-tools alanı, araçları onay istemeden önceden onaylayabilir. Her sürüm yükseltmesinde farkları (diff) inceleyin, bir dala değil tam bir commit'e sabitleyin ve kendi ekibinizin kontrol ettiği bir kaynağı tercih edin. Yönetilen makinelerde, ayarlardaki "disableSkillShellExecution": true komut ikamelerinin çalışmasını tamamen durdurur.
Paylaşılan bir yetenek Claude Code dışındaki agent'larda çalışır mı?
Bu, hangi önbilgiyi kullandığınıza bağlıdır. Agent Skills spesifikasyonu altı anahtar tanımlar: name, description, license, compatibility, metadata ve allowed-tools. Sadece bu anahtarlarla sınırlı bir yetenek, spesifikasyonu uygulayan araçlarda yüklenir ve Claude Code'da da değişiklik yapılmadan çalışır. Belirli bir altyapıya özgü anahtarlar ve spesifikasyon dışındaki gövde özellikleri başka yerlerde göz ardı edilir veya reddedilir; bu nedenle geniş çapta paylaşmayı planladığınız yeteneklerde bu tür özelliklerden kaçının.