SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor

Ajan yeteneklerini depolar arasında paylaşma yöntemleri

Ajan yeteneklerini kopyalamak yerine bağımlılık yönetimi kullanın. Tek bir depo üzerinden sürüm sabitleme ve duman testi ile kod tutarlılığını nasıl koruyacağınızı öğrenin.

Ajan yeteneklerini depolar arasında paylaşma

Ajan yeteneklerini depolar arasında paylaşmak için dosyaları kopyalamayı bırakın ve bağımlılık yönetimine geçin. Tek bir yetenek deposu tutun, etiketleyin ve her projenin belirli bir etiketi sabitlemesini sağlayın. 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 gözden geçirin.

Bu süreç dört bölümden oluşur: paylaşılan bir doğruluk kaynağı, her depo için sabitlenmiş bir sürüm, her yetenek için bir duman testi ve bir gözden geçirme yolu. Aşağıdaki bölümler, her bir parçanın neden var olduğunu, 2026 yılında sunulan araçların bu konuda neler yaptığını ve tüm bu yapının, harici bir git barındırma hizmeti veya paket kayıt defteri olmadan, kendi kendine barındırılan bir git uzak sunucusu üzerinde nasıl kurulacağını açıklar. Duman testleri bu durumun tek istisnasıdır. Bu testler, her isteği bir model API'sine gönderen Claude Code'u çalıştırır; dolayısıyla bu adım sunucunuzun dışına çıkar.

Bir 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 konumu ve paylaşmanın zorlukları

Claude Code, yetenekleri diğer konumların yanı sıra aşağıdaki dizinlerden yükler ve yetenek dokümantasyonu her bir yolu belirtir.

  • .claude/skills/<skill-name>/SKILL.md, yönetilen ayarlar dizini içindeki kurumsal konumdur. Bir organizasyonun dağıtım yaptığı makinelerde her kullanıcı için yüklenir.
  • ~/.claude/skills/<skill-name>/SKILL.md kişiseldir. Tüm projelerinizde yüklenir, başka kimsenin projesinde yüklenmez.
  • .claude/skills/<skill-name>/SKILL.md proje düzeyindedir. Depoyu (repository) kim klonlarsa onun için yüklenir.
  • <plugin>/skills/<skill-name>/SKILL.md bir eklenti içinde gelir. Eklentinin etkin olduğu her yerde yüklenir.

Claude Code ayrıca iç içe geçmiş proje dizinlerinden, --add-dir ile sağlanan dizinlerden ve claude.ai hesabınız için etkinleştirilmiş yeteneklerden de yükleme yapar.

Proje düzeyi, bir ekip için en kullanışlı olanıdır; çünkü commit edilir ve depoyu klonlayan herkes bu yeteneğe sahip olur. Sorun da tam burada başlar. .claude/skills/ içindeki bir yetenek tek bir depoya aittir. Sekiz deponuz varsa, yetenek sekiz kez kopyalanmış olur.

Ön metin (frontmatter) 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 listeyi yazdırarak bunu zorunlu kılar:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Neyin eksik olduğuna dikkat edin: version anahtarı yoktur. Bir sürüm metadata altında kaydedilebilir ancak spesifikasyon herhangi bir bağımlılık sabitleme veya güncelleme mekanizması tanımlamaz. Bu makuldür, çünkü bir yetenek paket değil, bir belgedir. Ancak bu, sürüm yönetiminin dosyanın etrafı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 neyi çözüyor?

Şu anda birçok yanıt gündemde ve sürüm bilgisinin nerede tutulması gerektiği konusunda fikir ayrılıkları mevcut.

Lockfile dosyaları. Vercel Labs tarafından geliştirilen skills komut satırı aracı (vercel-labs/skills, MIT lisanslı, 9 Ekim 2026 itibarıyla v1.7.2), yetenekleri (skills) bir git deposundan ajanınızın beklediği dizine kurar ve yetmişten fazla ajanın dizin yapısını tanır. npx skills add <repo> kurulum yapar, npx skills update yükseltme sağlar ve npx skills list mevcut olanları listeler. İki adet lockfile dosyası tutar. ~/.agents/.skill-lock.json konumundaki global dosya, bir kullanıcının neleri kurduğunu kaydeder. v1.4.1 (20 Şubat 2026) sürümünden itibaren, proje kapsamına kurulum yapmak, proje kök dizininde skills-lock.json dosyasını da oluşturur ve aracın kaynak kodu, bu dosyanın sürüm kontrol sistemine dahil edilmesi gerektiğini belirtir. npx skills experimental_install, bir projenin yeteneklerini bu dosyadan geri yükler. Başka bir makinede global lockfile dosyasını geri yüklemek için bir skills install komutu talep eden 283 numaralı sorun, 5 Kasım 2026 tarihinde planlanmadığı gerekçesiyle kapatılmıştır; sürüm sorumlusu bunu 549 numaralı sorunla aynı talep olarak tanımlamaktadır. Her iki sorunu da bir durum raporu olarak okuyabilirsiniz. Proje bazlı lockfile dosyası mevcuttur. Yayınlanan v1.8.1 sürümünde, geri yükleme komutu yardım menüsünde hala deneysel olarak etiketlenmiştir ancak herhangi bir kaynak belirtilmeden kullanılan npx skills install komutu da proje lockfile dosyasını geri yükler.

Spesifikasyonlar ve testler. SkillSpec, konuya farklı bir açıdan yaklaşır. Bir SKILL.md dosyasını güvenilmesi gereken bir metin yerine, denetlenmesi gereken bir sözleşme olarak ele alır ve yetenekleri "izlenebilir, test edilebilir ve kanıtlanabilir" kılmayı hedefler. skillspec doctor <path>, bir ajanın iş parçacığını (thread) nerede koparma ihtimalinin yüksek olduğunu raporlar. skillspec boundary map <path> yeteneğin içeriğini gösterir, skillspec boundary assess <path> ise risk derecesine göre erişebildiği noktaları raporlar. Bu araç, MIT veya Apache 2.0 lisanslarıyla çift lisanslı bir Rust paketidir. 0.2.2 sürümü 29 Temmuz 2026 tarihinde yayınlanmış olup 10 Ekim 2026 itibarıyla crates.io üzerindeki en güncel sürümdür. En yeni sürüm yerine sabitlenmiş sürümü kurun:

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

12 Kasım 2026 tarihinde yayınlanan Cargo 1.100 sürümünden itibaren, cargo install varsayılan olarak paketlenmiş lockfile dosyasını kullanır ve --locked işlevsiz hale gelmiştir. 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çerisindeki yetenekleri nasıl oluşturduğunu ajan yeteneklerini nasıl oluşturduğu, test ettiği ve ölçeklendirdiği hakkındaki bir yazıda açıklamıştır. Ölçeklendirme mekanizmasını çıkardığınızda geriye kalan, standart bir sürekli entegrasyon (CI) sürecidir. Her yetenek, birleştirilmeden önce ön metin (frontmatter) meta verileri, satır sayısı, dizin düzeni ve isimlendirme standartları için linter denetimlerinden geçer. Bir bağlantı denetleyicisi, 404 hatası döndüren herhangi bir URL'de derlemeyi başarısız kılar; bu da ajanın uydurduğu makul görünen bağlantıları yakalar. Yazarlar, yetenekle birlikte bir değerlendirme istemi paketi ve puanlama kriteri sunmak zorundadır. Planlanmış değerlendirme işleri, gerilemeleri (regression) tespit etmek için haftalık olarak tüm kütüphane üzerinde çalıştırılır ve her yeteneğin, kalite düştüğünde düzeltmesi beklenen atanmış bir sahibi bulunur.

Üç 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.md

Sü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.0

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

Sağ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.

Alternatif olarak eklenti pazaryeri ile sabitleme

Her geliştiriciden submodule öğrenmesini istemiyorsanız, Claude Code eklenti sistemi dağıtımı sizin yerinize yapar ve kendi barındırdığınız (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; Claude Code v2.1.324 veya sonraki sürümlerde ise tam bir küçük harfli commit SHA değerini kabul eder; ayrı bir sha alanını kabul etmez. Katalog içindeki bir eklenti kaynağı ise her ikisini de kabul eder ve her ikisi de ayarlandığında sha geçerli sabitleme (pin) olur. Kataloğu, pazaryeri kaynağının ref değeri üzerinden, eklentiyi ise katalog girdisinin sha değeri üzerinden sabitleyin. Tür adları da farklıdır. Katalog içinde url, klonlanacak bir git deposu anlamına gelir. Bir pazaryeri kaynağında url, doğrudan bir marketplace.json dosyasına bağlantı anlamına gelirken, git deposu git olarak belirtilir.

Her bir tüketici depo, pazaryerini kendi commit edilmiş .claude/settings.json dosyasında bildirir:

{
  "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, ekip üyesi proje klasörü için çalışma alanı güven iletişim kutusunu onayladığında, herhangi bir wiki sayfasına gerek kalmadan pazaryerini kaydeder. Katalog girdisi göreli bir yol yerine bir git URL'sine işaret eder, bu nedenle eklenti yalnızca deponun ayarları üzerinden kurulmaz. Her ekip üyesi claude plugin install team-skills@acme-agents --scope project komutunu bir kez çalıştırır; o zamana kadar Claude Code, eklentinin proje ayarlarında etkinleştirildiğini ancak kurulu olmadığını bildirir. 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 gönderip katalogdaki ve tüketici depolardaki sabitlemeleri güncelledikten sonra, tüketiciler /plugin marketplace update acme-agents ile yenileme yapar ve kurulum özeti isterse /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 tek bir doğrulama (assertion) üzerinde çalıştırılan betik tabanlı bir aracı çalıştırması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, çalıştırma başlamadan önce genişletilecektir.

#!/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, tek bir kasıtlı hata içeren 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ıştırma 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 haline getirir.

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 istediğ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. Bu durum, bir ekip arkadaşının kişisel yapılandırmasının sonucu değiştirmesine neden olabilir. "Bare" modu, --add-dir ile açıkça sağlanan bir dizin altındaki .claude/skills/ içinde bulunan yetenekler haricinde otomatik keşfi atlar; burada test ettiğiniz proje yeteneğini atlar, bu yüzden onu açıkça yükleyin. "Bare" modu abonelik girişinizi de okumaz, bu nedenle önce ortamda ANTHROPIC_API_KEY değerini 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

--plugin-dir ile yüklenen bir eklenti, adını .claude-plugin/plugin.json dosyasından alır; bu bildirim dosyası olmadan eklenti, dizininin adını alır. Yetenek deposundaki kataloğun yanına "name": "team-skills" içeren bir plugin.json commit'leyin, aksi takdirde yukarıdaki komut bunun yerine /agent-skills:api-review çağırmak zorundadır.

--output-format stream-json ile system/init olayı, hangi eklentilerin yüklendiğini raporlar ve yüklenmeyenler için bir plugin_errors dizisi taşır. Başlangıç olayları önce gelmediği sürece akışı açar. Boş olmayan bir plugin_errors durumunda CI işini başarısız sayın. Bu, artık var olmayan bir revizyona yönlendirilmiş bir sabitlemeyi yakalar; aksi takdirde bu durum, aracın kurallarınızı sessizce görmezden gelmesi olarak görünür.

Paylaşılan bir yetenek yürütülebilir bir talimattır

İki özellik bunu gerçek kılar ve dosya başka bir ekipten geldiğinde her ikisi de önem taşır.

İlk olarak, bir SKILL.md, model herhangi bir şeyi okumadan önce shell komutlarını çalıştırabilir. Gövde kısmındaki buna benzer 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 kimseye bununla ilgili bir onay sorulmaz. Claude Code, her komutu izin kurallarınıza göre denetler. Otomatik mod dışında, bu kuralların izin vermediği bir komut, yetenek aşağıda belirtilen ikinci özellik aracılığıyla ön onay almadığı sürece yeteneği durdurur. Reddetme ve sorma kuralları, bu ön onayı yine de geçersiz kılar. Paylaşılan bir yeteneği okumak, onun komut değişimlerini okumak anlamına gelir.

İkinci olarak, ön metin (frontmatter) araçlara ön onay verebilir. allowed-tools, yeteneği çağıran tur için bir izin istemi olmaksızın listelenen araçlara erişim sağlar. Çalışma alanı güveni (workspace trust) bu izni engellemez: Claude Code, bir proje yeteneğinin allowed-tools kısmını, kimsenin güvenmediği bir klasörde çalıştırılan bir -p içinde bile uygular. Claude Code belgeleri sonucu açıkça belirtir: bir yetenek kendisine geniş araç erişimi verebilir, bu nedenle Claude Code'u çalıştırmadan önce bir depoya eklenen yeteneklerin allowed-tools kısmını inceleyin. Bir kuruluş, yönetilen ayarlarda allowManagedPermissionRulesOnly değerini ayarlayarak proje ve kişisel yeteneklerden bu alanı kısıtlayabilir; bu işlem Claude Code v2.1.282 veya sonraki bir sürümünü gerektirir.

Bu nedenle, bir yetenek güncellemesini tıpkı bir bağımlılık güncellemesi gibi ele alın. Mekanizmanın izin verdiği her yerde tam commit hash'i ile sabitleyin, çünkü bir etiket (tag) taşınabilir ve bir dal (branch) 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 okuduğu veriler 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 (context) çeker; bu, gizli bilgileri çalıştırdığınız aracıların dışında tutma konusunda ele alınan bir başarısızlıktır. Bir sayfa getiren veya bir sorgu çalıştıran yetenek, dışa dönük aynı maruziyeti yaratır; çünkü alınan metin, bağlama tıpkı sizin yazdığınız talimatlar gibi görünerek yerleşir. Bu sınır, bir aracıyı web araması için kendi SearXNG örneğinize yönlendirmeden önce hakkında bilgi edinmeye değer bir konudur.

Sürüm yükseltmelerinde nelerin incelenmesi gerektiği

  • Her bir SKILL.md gö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 mekanizma işe yarar. Bir git submodule tam bir commit kaydeder ve .claude/skills/<name> içinden submodule'a verilen bir sembolik bağ (symlink), bunun normal bir proje yeteneği gibi yüklenmesini sağlar. Bir eklenti marketi, /plugin aracılığıyla aynı işi yapar; sabitleme işlemi tüketen 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 yanıtlayabilirsiniz.

Bir agent yeteneğini belirli bir sürüme sabitleyebilir miyim?

SKILL.md içinden yapılamaz, çünkü bu ön metnin (frontmatter) version anahtarı yoktur. Sabitleme, dosyanın etrafındaki katmandan gelmelidir. 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 sha kabul eder ve her ikisi de mevcut olduğunda sha önceliklidir. Market kaynağının kendisi dal veya etiket için ref kabul eder; Claude Code v2.1.324 veya sonraki sürümlerde ise tam bir küçük harfli commit SHA 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 şey üzerinde doğrulama yapın. Yeteneği, bilinen bir hata içeren bir fikstüre karşı etkileşimli olmayan bir şekilde çalıştırın, ardından çıktıda belirli bir tanımlayıcının göründüğünü kontrol edin; örneğin yeteneğin raporlaması gereken bir kural kimliği (rule id). --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 yanıtlarını çalıştırmalar arasında yeniden ifade edebilir.

Başka bir ekibin deposundan paylaşılan bir yeteneği yüklemek güvenli mi?

Bunu bir kod bağımlılığı olarak değerlendirin, çünkü çalıştırılabilir talimatlardır. Bir SKILL.md, ! komut ikamesi biçimi aracılığıyla yükleme sırasında kabuk komutları çalıştırabilir ve ön metindeki allowed-tools alanı, araçları bir istem olmadan önceden onaylayabilir. Her sürüm yükseltmesinde farkları (diff) okuyun, 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, kullanıcı, proje, eklenti ve ek dizin yeteneklerindeki komut ikamelerinin çalışmasını durdurur; paketlenmiş ve yönetilen yetenekler bundan muaftır.

Paylaşılan bir yetenek Claude Code dışındaki agent'larda çalışır mı?

Bu, hangi ön metni kullandığınıza bağlıdır. Agent Skills spesifikasyonu altı anahtar tanımlar: name, description, license, compatibility, metadata ve allowed-tools. 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. Spesifikasyon dışındaki araca özel anahtarlar ve gövde özellikleri başka yerlerde göz ardı edilir veya reddedilir, bu nedenle bunları geniş çapta paylaşmayı planladığınız hiçbir yeteneğe dahil etmeyin.

Bu yazı işinize yaradı mı?