Ajan yeteneklerini depolar arası paylaşma rehberi

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 incelediğiniz gibi inceleyin.

Bu 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 ne yaptığını ve tüm bu yapının dışarıdan hiçbir servis kullanılmadan, kendi kendine barındırılan bir git uzak sunucusu üzerinde nasıl kurulacağını açıklar.

Ajan yeteneği, bir SKILL.md dosyası ile 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.md kişiseldir. Sadece sizin projelerinizde yüklenir, başkalarında 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 eklentinin içinde gelir. Eklentinin etkin olduğu her yerde yüklenir.

Ekip için en kullanışlı olan ortadaki yöntemdir; çünkü bu yöntemle yetenek commit edilir ve depoyu klonlayan herkes 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 kopyalanır.

Ön bilgi (frontmatter) kısmı 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, name

Neyin eksik olduğuna dikkat edin: version anahtarı yoktur. Dosyanın içinde, hangi kopyanın daha yeni olduğunu kaydeden hiçbir veri bulunmaz. Bu durum, bir yeteneğin paket değil bir doküman olması nedeniyle makuldür. Ancak bu, sürüm yönetiminin dosyanın dışındaki katmandan gelmesi gerektiği anlamına gelir ve o katmanı yönetmek sizin sorumluluğunuzdadır.

Sorun bir: sessizce farklılaşan sekiz kopya

Kopyala-yapıştır yöntemi ilk gün çalışır. Altmışıncı günde ise başarısız olur. Birisi 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ı beceri 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 beceri düz metinden ibarettir. Güncelliğini yitirmiş bir talimat, emin ama yanlış bir yanıt üretir; bu da en maliyetli hata türüdür. Ajan içerisinde kopyanızı diğerleriyle karşılaştıran hiçbir mekanizma yoktur, bu nedenle tek belirti bir kişinin iki deponun birbiriyle uyuşmadığını fark etmesidir.

Sorun iki: sürüm sabitleme eksikliği

Bir ekip becerileri 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 an dalın en ucunda ne varsa onu kurar.

Bu durum, aynı uygulamanın aynı commit'i üzerinde çalışan iki geliştiricinin, eşitlemeyi farklı günlerde yaptıkları için farklı yönergelerle çalışabileceği anlamına gelir. Ayrıca, hatalı bir aracı çalışmasından sonra önemli olan şu soruyu yanıtlayamazsınız: bu becerinin hangi sürümü bunu üretti? Kaydedilmiş bir revizyon olmadan çalışma tekrarlanamaz, bu nedenle hata raporu üzerinde işlem yapılamaz.

Sorun üç: yeteneğin hala çalıştığını kimse bilmiyor

Bir yeteneğin derleyicisi yoktur. Bu, bir modele yönelik talimatlar bütünüdür; dolayısıyla dosya bayt düzeyinde aynı kalsa bile yetenek çalışmayı durdurabilir. Model yükseltmeleri, uzun bir talimatın ne kadar hassasiyetle takip edileceğini değiştirir. Yeteneğin çağırdığı 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 işlem yapmaya devam eder.

Bu durumların hiçbirinde sistem gürültülü bir şekilde hata vermez. Aracı hala yanıt verir. Yanıtın kalitesi geçen aya göre düşmüştür; bu durum, her bir pull request özelinde fark edilmesi zor bir sorundur.

2026 yılında 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ı yaşanmaktadı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 talep (issue 283), lock dosyasındaki tüm takip edilen yetenekleri yeniden kuran bir skills install komutu istemektedir; böylece ikinci bir makine aynı setle yapılandırılabilir. Bu talebi bir durum raporu olarak okuyun. Lockfile fikri kesinleşmiştir. Bunun proje bazlı kısmı ise hala geliştirilmektedir.

Spesifikasyonlar ve testler. SkillSpec konuya farklı bir açıdan yaklaşır. Bir SKILL.md dosyasını güvenilecek bir metin yerine kontrol edilecek 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ı nerede bırakabileceğini raporlar. skillspec boundary map <path> yeteneğin nelere erişebileceğini bildirir ve skillspec boundary assess <path> bu bulguları risk düzeyine göre sıralar. Bu, 29 Temmuz 2026 itibarıyla 0.2.2 sürümünde olan, MIT veya Apache 2.0 ile çift lisanslı bir Rust paketidir. En yeni sürüm yerine sabitlenmiş sürümü kurun:

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

--locked, paketin 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 derlediğini ajan yeteneklerinin nasıl derlendiği, test edildiği ve ölçeklendirildiği üzerine bir yazıda açıklamıştır. Ölçeklendirme kısmını çıkardığınızda mekanizma sıradan bir sürekli entegrasyon (CI) sürecidir. Her yetenek; ön metin (frontmatter) meta verileri, satır sayısı, dizin düzeni ve isimlendirme standartları için linter kontrollerinden geçmeden birleştirilmez. Bir bağlantı denetleyicisi, 404 hatası döndüren herhangi bir URL'de derlemeyi durdurur; bu da ajanın uydurduğu olası bağlantıları yakalar. Yazarlar, yeteneğin yanında bir değerlendirme istemi paketi ve puanlama kriteri sunmak zorundadır. Planlanmış değerlendirme işleri, regresyonları yakalamak için tüm kütüphaneye karşı 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 da temelindeki örüntü

Bunlardan birini seçmek zorunda değilsiniz. Hepsini kapsayan tek bir yapı mevcuttur ve standart git komutları size bunun tamamını sunar.

1. Tek bir doğruluk kaynağı. Yeteneğin tam olarak tek bir 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ığı tam revizyonu kaydeder; bu sayede 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 tüketici, 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şı haline geldi; 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, 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 (annotated tags) kullanın; çünkü bu etiketler bir mesaj ve tarih bilgisi taşır. Mesajı, bir kullanıcının neden sürüm yükseltmek isteyeceği gerekçesiyle 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 düzeyindeki 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 olarak yüklenirken, veriler sizin 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)

Satırın başında 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. Satırın başında yer alan bir +, check-out edilen commit'in kayıtlı olandan farklı olduğu anlamına gelir; bu da ilgili geliştiricinin başka kimsede olmayan 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 amacımız 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 eklenti pazarı ile sabitleme

Her geliştiriciden submodule öğrenmesini istemiyorsanız, Claude Code eklenti sistemi dağıtımı sizin yerinize yapar ve self-hosted bir uzak sunucu ile çalışır. Yetenek deposunda .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ı karıştırmak yaygın bir hatadır. Katalogun kendisinin nereden çekildiğini belirten pazar yeri kaynağı, bir dal veya etiket için ref kabul eder ancak sha kabul etmez. Katalog içindeki bir eklenti kaynağı her ikisini de kabul eder; her ikisi de ayarlandığında geçerli olan sabitleme sha değeridir. Dolayısıyla, tam commit sabitlemesi katalog girdisine aittir.

Her bir tüketici depo, daha sonra commit edilmiş .claude/settings.json dosyasında pazar yerini bildirir:

{
  "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 üyesine pazar yerini yüklemesi için bir istem gösterilir ve eklenti, bunu yapmasını söyleyen bir wiki sayfasına ihtiyaç duymadan 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 etiket push ettikten sonra, tüketiciler /plugin marketplace update acme-agents ile yenileme yapar, ardından yükleme ö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 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 cevapları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, 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 onu açıkça yükleyin. "Bare" modu abonelik girişinizi 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 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.

Birincisi, bir SKILL.md, model herhangi bir şeyi okumadan önce shell komutlarını çalıştırabilir. İçerikteki bunun gibi bir satır ön işleme (preprocessing) anlamına gelir:

- 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ı onaylamaz. Paylaşılan bir yeteneği okumak, onun komut değişimlerini (command substitutions) okumak anlamına gelir.

İkincisi, ön metin (frontmatter) araçları önceden onaylayabilir. allowed-tools, yeteneği çağıran tur 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 (workspace trust) 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 inceleyin, çü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. 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] 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ını açan bir yetenek, bulduğu her şeyi modelin bağlamına (context) çeker; bu, sırları ç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 oluşturur; çünkü alınan metin, bağlama sizin yazdığınız talimatlarla tamamen aynı görünümde girer. 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.md gövdesinin farkı (diff); çü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 yetkisi verir.
• Etiketin arkasındaki test çalışması. 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 farkı on dakika içinde okuyamayan bir gözden geçiren, çok fazla büyümüş bir yeteneğe bakıyor demektir. Yeteneği bölün. Aynı argüman, 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 beceriyi bozduğunda

Hiç kimse düzenleme yapmasa bile bir becerinin arka planında 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 beceri, artık bu adıma ulaşamayabilir. Bir komut satırı aracı bir bayrağı yeniden adlandırır; bu durumda aracı eski bayrağı çalıştırır, hatayı okur ve doğaçlama yapar. Başvurulan bir URL 404 hatası döndürmeye başlar. Bir aracı donanımı (agent harness), becerileri seçme yöntemini değiştirir; böylece eskiden eşleşmeyi kazanan bir description artık kazanamaz hale gelir.

Bu düzenlemede duman testinin (smoke test) ağırlık taşımasının nedeni budur. Her becerinin testini hem push işlemlerinde hem de belirli bir zaman çizelgesinde çalıştırın. Google, bu nedenle değerlendirme işlerini tüm kütüphaneye karşı haftalık olarak çalıştırır; on becerisi olan bir ekip için küçük bir VPS üzerinde haftalık bir cron işi yeterlidir. Kırılmaları bir geliştiriciden önce öğrenmenizin tek yolu budur.

Taşınabilirlik de yardımcı olur. Agent Skills spesifikasyonu, ön bilgileri (frontmatter) altı anahtarla sınırlandırır; bu spesifikasyona göre yazılan bir beceri, onu yazdığınız aracın ötesindeki araçlarda da yüklenir. Eklediğiniz her donanıma özgü anahtar ise tek bir tedarikçiye yapılan bir bahistir. Model değişiminden sağ çıkabilen beceriler yazmak başlı başına bir disiplindir ve bir beceriyi her modelde çalışır hale getirme konusunda ele alınmıştır.

FAQ

How do I share one agent skill across several repositories?

Put the skill in a dedicated git repository, tag releases in it, and have each consuming project reference a tag instead of copying the file. Two mechanisms work. A git submodule records an exact commit, and a symlink from .claude/skills/<name> into the submodule makes it load as a normal project skill. A plugin marketplace does the same job through /plugin, with the pin declared in the consuming repository's .claude/settings.json. Both put the version in git history, so you can answer which instructions produced a given agent run.

Can I pin an agent skill to a specific version?

Not from inside SKILL.md, because that frontmatter has no version key. The pin has to come from the layer around the file. A git submodule pins an exact commit by design. In a Claude Code plugin marketplace, a plugin source accepts ref for a branch or tag and sha for an exact commit, and the sha wins when both are present. The marketplace source itself accepts ref only. Prefer the commit pin, because a tag can be moved after you reviewed it.

What should a skill smoke test assert?

Assert on something stable. Run the skill non-interactively against a fixture that contains a known fault, then check that a specific identifier appears in the output, for example a rule id the skill is supposed to report. Requesting structured output with --output-format json and --json-schema makes the check exact, and jq -e fails the script when the value is missing. Never assert on a full sentence, because a model rewords its answers between runs.

Is it safe to install a shared skill from another team's repository?

Treat it as a code dependency, because it is executable instruction. A SKILL.md can run shell commands at load time through the ! command substitution form, and the frontmatter allowed-tools field can pre-approve tools without a prompt. Read the diff on every bump, pin to an exact commit rather than a branch, and prefer a source your own team controls. On managed machines, "disableSkillShellExecution": true in settings stops command substitutions from running at all.

Will a shared skill work in agents other than Claude Code?

That depends on which frontmatter you use. The Agent Skills spec defines six keys: name, description, license, compatibility, metadata and allowed-tools. A skill limited to those loads across tools that implement the spec, and it also loads in Claude Code without changes. Harness-specific keys and body features beyond the spec are ignored or rejected elsewhere, so keep them out of any skill you intend to share widely.