Claude Skills API GA'ya Çıktı: Yenilikler ve Nasıl Kullanılır

Claude Beceriler API'si: Özel becerileri yükleme, sürümleme ve çalıştırma

Claude Beceriler API'si 20 Ağustos 2026 itibarıyla genel kullanıma sunuldu. Artık beta başlığı kullanmadan https://api.anthropic.com/v1/skills üzerinden özel beceriler oluşturabilir, sürümleyebilir ve yönetebilirsiniz. Bu beceriler, kendi altyapınızı barındırmanıza gerek kalmadan Claude'un kod sanal alanında çalışır. Anthropic bu sürümü bilgisayar kullanımı, yeni tarayıcı aracı ve Dosyalar API'siyle birlikte duyurdu ve Claude Platformu'nda aracı oluşturmak için üretim yığını olarak konumlandırdı.

Apidog'u bugün deneyin

Beceriler kavramı sizin için yeniyse, Claude Becerileri Rehberimiz bu fikri baştan sona açıklar. Bu makale ise API katmanına odaklanır: uç noktalar, sürümleme modeli, becerileri bir Mesajlar çağrısına yükleyen istek yapısı ve genel kullanıma sunulmayla giderilmeyen çalışma alanı kapsamı ile anlık görüntü sürümleme gibi konular.

Tüm işlemler düz HTTP üzerinden yapılır. Bu nedenle burada gösterilen istekleri Apidog içinde oluşturabilir, değişkenlerle yönetebilir ve regresyon testlerine bağlayabilirsiniz.

30 saniyelik hızlı tekrar: Beceri nedir?

Bir beceri, belirli bir görevi yerine getirmek için gereken dosyaları içeren bir klasördür. Klasörün kökünde, name ve description alanlarını içeren YAML ön bilgisine sahip bir SKILL.md dosyası bulunur. Komut dosyaları, şablonlar ve referans dosyaları bu dosyanın çevresinde yer alır.

Bir istek beceriyi içerdiğinde Claude, talimatları yalnızca görev gerektirdiğinde yükler ve paketlenmiş komut dosyalarını kod sanal alanında çalıştırır.

SKILL.md ön bilgisinin doğrulama kuralları şunlardır:

• name en fazla 64 karakter olabilir.
• name yalnızca küçük harf, sayı ve kısa çizgi içerebilir.
• XML etiketleri kullanılamaz.
• anthropic ve claude kelimeleri ayrılmıştır.
• description boş olamaz ve en fazla 1024 karakter olabilir.
• İsteğe bağlı display_name alanı en fazla 255 karakter olabilir.
• Yüklenen tüm içerik, sıkıştırılmamış halde 30 MB'nin altında kalmalıdır.

Beceriler iki kaynaktan gelir:

• Anthropic tarafından yönetilen becerilerde (type: "anthropic") pptx, xlsx, docx ve pdf gibi kısa kimlikler kullanılır. Bu beceriler tarih tabanlı sürümlere, örneğin 20251013, sahip olabilir.
• Özel beceriler (type: "custom") sizin tarafınızdan yüklenir, çalışma alanınıza özel olur ve skill_01AbCdEfGhIjKlMnOpQrStUv gibi oluşturulmuş kimlikler alır.

Genel kullanıma sunulmayla ne değişti?

20 Ağustos 2026 itibarıyla öne çıkan değişiklikler şunlardır:

1. Beta başlığı kaldırıldı. Beceriler API'si Claude API üzerinde yalnızca x-api-key ve anthropic-version: 2023-06-01 başlıklarıyla kullanılabilir.
2. Yükleme ve sürümleme akışı basitleştirildi. Özel beceriler için daha basit bir yükleme ve sürümleme API'si sunuldu. Sürümler, kendilerine ait uç noktaları olan birinci sınıf kaynaklardır.
3. Platform desteği genişledi. Beceriler API'si Claude API'sinin yanı sıra Microsoft Foundry üzerinden de kullanılabilir. Beceriler Anthropic'in yönettiği sanal alanda çalıştığı için sizin tarafınızda ek altyapı gerekmez.

Bu sürümle birlikte genel kullanıma sunulan Dosyalar API'si de beceriler için önemlidir. Çünkü beceriler çoğu zaman bir sunum dosyası veya doldurulmuş elektronik tablo gibi çıktılar üretir. Bu dosyaları Dosyalar API'si üzerinden alabilirsiniz.

Uç noktalar

Beceriler API'sinin uç noktaları /v1/skills altında bulunur:

İşlem	Uç nokta
Beceri oluşturma	POST /v1/skills
Becerileri listeleme	GET /v1/skills
Beceri bilgilerini alma	GET /v1/skills/{skill_id}
Beceri silme	DELETE /v1/skills/{skill_id}
Yeni sürüm oluşturma	POST /v1/skills/{skill_id}/versions
Sürümleri listeleme	GET /v1/skills/{skill_id}/versions

Beceri oluştururken tüm dosya kümesini yüklersiniz. Yeni sürüm oluştururken de mevcut beceri kimliğine karşı dosyaların tamamını yeniden gönderirsiniz.

Apidog'da bu akış, {{skill_id}} ve {{skill_version}} ortam değişkenlerini kullanan altı kayıtlı istekten oluşan tek bir klasör olarak modellenebilir. Böylece bir sürümü geliştirme veya üretim ortamına taşımak için istekleri düzenlemek yerine yalnızca değişkeni değiştirirsiniz.

Özel beceri yükleme

Minimal bir özel beceri için bir klasöre ve yükleme isteğine ihtiyacınız vardır. Örneğin, depoda aşağıdaki marka raporu becerisini tuttuğunuzu varsayalım:

brand-report/
  SKILL.md
  templates/report.html
  scripts/build_report.py

SKILL.md dosyası şu şekilde başlayabilir:

---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---

Dosyaları multipart form verisi olarak yükleyin:

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
  -F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
  -F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'

Yanıt, oluşturulan skill_id ile ilk sürümün skver_* kimliğini döndürür.

Bu iki değeri saklayın:

• skill_id, sonraki Mesajlar isteklerinde kullanılır.
• Sürüm kimliği, belirli bir sürüme geri dönmek için kullanılır.

SDK yardımcıları bu isteği genellikle sarmalar. Kullandığınız SDK sürümüne göre tam multipart alan adlarını Beceriler API referansında doğrulayın.

description alanını yönlendirme kuralı gibi yazın

Claude, bir beceriyi yükleyip yüklemeyeceğine karar verirken description alanını okur. Bu alanı tek satırlık bir etiketten çok yönlendirme kuralı gibi yazın.

Örneğin şu bilgileri açıklamaya ekleyin:

• Beceri hangi görevi yerine getiriyor?
• Kullanıcı hangi ifadeleri kullandığında beceri devreye girmeli?
• Hangi girdi biçimleri destekleniyor?
• Hangi çıktılar üretiliyor?

Kullanıcıların kullandığı tetikleyici ifadeleri açıklamada listelemek, genel bir tanımdan daha kullanışlıdır.

Bir Mesajlar isteğinde beceri kullanma

Beceriler doğrudan mesaja eklenmez. container parametresinde belirtilen kod yürütme aracı üzerinden çalışırlar:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest"
            }
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build the Q3 revenue deck from the attached numbers"
        }
    ],
    tools=[
        {
            "type": "code_execution_20250825",
            "name": "code_execution"
        }
    ],
)

Bu yapıyı kullanırken şu kurallara dikkat edin:

• Kod yürütme aracını tools içinde etkinleştirin. Beceriler bu sanal alan içinde yürütülür. Model desteği için kod yürütme aracı uyumluluk listesini kontrol edin.
• İstek başına en fazla 20 beceri kullanın. Claude, her becerinin açıklamasını okuyarak görev için gereken becerileri belirler.
• Sürümü açıkça yönetin. "latest" en yeni sürümü kullanır. Belirli bir skver_* kimliği veya Anthropic becerileri için tarih sürümü kullanarak davranışı sabitleyebilirsiniz.
• Üretimde sürümü sabitleyin. Geliştirme ortamında "latest" kullanmak daha akıcı bir iterasyon sağlar; üretimde sabit bir sürüm, beklenmeyen davranış değişikliklerini önler.

Bir beceri belge dosyası ürettiğinde yanıt içinde bir file_id alırsınız. Dosyayı şu Dosyalar API uç noktasıyla indirebilirsiniz:

GET /v1/files/{file_id}/content

Temel üretim döngüsü şöyledir:

1. Beceriyi Beceriler API'siyle çalıştırın.
2. Yanıttaki file_id değerini alın.
3. Dosyayı Dosyalar API'sinden indirin.

Sürümleme: Fark değil, anlık görüntü

Sürümleme modelindeki en önemli ayrıntı şudur: Yeni sürüm bir delta değil, becerinin eksiksiz bir anlık görüntüsüdür.

Şu isteği gönderdiğinizde:

POST /v1/skills/{skill_id}/versions

becerinin tüm dosya kümesini yeniden yüklersiniz. İstekten çıkardığınız dosyalar önceki sürümden devralınmaz. Ayrıca yeni sürümdeki SKILL.md dosyasının name alanı, mevcut becerinin adıyla eşleşmelidir.

Becerileri derleme yapıtları gibi yönetin:

1. Doğruluk kaynağını depoda tutun.
2. Beceri klasörünün tamamını CI içinde paketleyin.
3. Her değişikliği yeni bir sürüm olarak yükleyin.
4. Üretimde sabit sürüm kimliği kullanın.
5. Sorun çıktığında çalışan skver_* sürümüne geri dönün.

Eski sürümler erişilebilir kaldığı için geri alma işlemi, üretimde kullanılan tek bir sürüm dizesini değiştirmek kadar basittir.

Çalışma alanı kapsamı: Çok kiracılı sistemlerde dikkat

Özel beceriler tüm çalışma alanına açıktır. Bir son kullanıcıya, konuşmaya veya oturuma özel değildir. Çalışma alanındaki her API anahtarı bu becerilere erişebilir.

Kiracıların kendi becerilerini yüklediği çok kiracılı bir ürün çalıştırıyorsanız, tüm kiracıları tek bir çalışma alanında toplamak veri izolasyonu açısından sorun oluşturabilir.

Çözüm, Dosyalar API'sindeki yaklaşıma benzer: her kiracı için ayrı bir çalışma alanı oluşturun. Çalışma alanı bir izolasyon sınırı görevi görür. Her kuruluş, bir hesap ekibiyle iletişime geçmeden 100'e kadar çalışma alanına sahip olabilir.

Anahtarlar, dosyalar ve beceriler bu sınırı devralır. Bu nedenle çalışma alanı tasarımıyla ilgili tek bir karar, bu üç kaynağın izolasyonunu birlikte belirler.

Uzun süren beceriler: pause_turn ve konteyneri yeniden kullanma

Beceri yürütmeleri tek bir model turundan uzun sürebilir. Bu durumda iki mekanizma kullanılır.

pause_turn

Yanıt aşağıdaki durma nedeniyle tamamlanmadığında:

stop_reason: "pause_turn"

asistan içeriğini mesaj geçmişine ekleyin ve aynı container.id değeriyle isteği yeniden gönderin. Kod sanal alanı kaldığı durumdan devam eder.

Konteyneri yeniden kullanma

container nesnesi önceki yanıttan alınan bir id kabul edebilir. Böylece kurulu dosyalar ve çalışma durumu çok turlu konuşma boyunca korunur.

Örneğin beceri:

1. İlk turda bir elektronik tablo oluşturabilir.
2. Sonraki turda aynı konteyneri kullanarak dosyayı yeniden oluşturmak zorunda kalmadan revize edebilir.

Her iki desen de durumlu HTTP dizileri oluşturur. Bu istekleri elle doğrulamak yerine Apidog senaryosuna bağlayabilirsiniz:

1. İlk istekte stop_reason değerini doğrulayın.
2. Bir betikle container.id değerini ortam değişkenine aktarın.
3. İkinci istekte aynı konteyner kimliğini kullanın.
4. Son adımda oluşturulan file_id içeriğinin indirilebildiğini doğrulayın.

Apidog CLI aynı senaryoyu CI içinde çalıştırabilir. Böylece bir beceri sürümü güncellemesinin hattı bozup bozmadığını otomatik olarak kontrol edebilirsiniz.

Becerilerin başka bir satıcının ekosisteminde nasıl çalıştığını karşılaştırmak isterseniz, önceki incelememizde Postman'ın Claude becerisini ele almıştık.

Beceriler nerede çalışır?

Genel kullanıma sunulma aşamasında Beceriler API'si Claude API'si ve Microsoft Foundry üzerinden kullanılabilir.

Beceriler Anthropic'in yönettiği sanal alanda yürütülür. Bu nedenle dağıtım süreci sizin tarafınızda konteyner imajı, çalışma zamanı yaması veya ölçeklendirme düğümü yönetmenizi gerektirmez. Dağıtım, beceri dosyalarının yüklenmesiyle sınırlıdır.

Bununla birlikte model uyumluluğunu kontrol etmeniz gerekir. İstek, yukarıdaki örnekteki claude-opus-5 gibi kod yürütme aracının desteklediği bir modeli kullanmalıdır. Yeni başlıyorsanız Claude Opus 5 API rehberimiz temel istek yapısını açıklar.

Sıkça sorulan sorular

Hâlâ beceriler beta başlığına ihtiyacım var mı?

Hayır. 20 Ağustos 2026'dan itibaren /v1/skills ve container.skills parametresi Claude API'sinde standart başlıklarla çalışır. SDK'nızı yükselttikten sonra sabitlenmiş beta bayraklarını kaldırın.

Bir beceri çalışırken harici API'leri çağırabilir mi?

Beceriler Claude'un kod sanal alanında, kod yürütme aracının ağ kısıtlamalarıyla çalışır. Açık ağ erişimini varsaymak yerine, becerinin ihtiyaç duyduğu dosyaları klasörüne paketleyin.

Harici API çağrılarını uygulama katmanınızda tutun. Böylece bu çağrıları doğru şekilde kontrol edebilir ve test edebilirsiniz.

Bir istek kaç beceri yükleyebilir?

Bir istek en fazla 20 beceri yükleyebilir. Claude, hangilerine ihtiyaç duyduğunu belirlemek için becerilerin description ön bilgilerini okur.

Bu nedenle description alanlarını pazarlama metni gibi değil, yönlendirme kuralları gibi yazın.

Beceriler API'si ile Claude Code becerileri arasındaki fark nedir?

Konsept aynıdır, ancak çalışma zamanı farklıdır.

Claude Code, dosya sisteminizdeki beceri klasörlerini keşfeder. Beceriler API'si ise becerileri sunucu tarafında, sürümlenmiş kaynaklar olarak barındırır ve Mesajlar API çağrıları sırasında kullanır.

Her iki yaklaşım da SKILL.md ön bilgisine sahip klasör biçimini paylaşır. Bu nedenle Claude Code için yazdığınız bir beceri genellikle az sayıda değişiklikle Beceriler API'sine taşınabilir.

Sonuç

Beceriler API'sinin genel kullanıma sunulması, becerileri deneysel bir özellikten operasyonel bir API yüzeyine dönüştürüyor. Temel yapı şu bileşenlerden oluşuyor:

• Altı yönetim uç noktası
• Eksiksiz anlık görüntü tabanlı sürümleme
• Çalışma alanı düzeyinde izolasyon
• Üretilen dosyalar için Dosyalar API'si
• Uzun süren işler için konteyner yaşam döngüsü yönetimi

En hızlı değer elde eden ekipler becerileri diğer dağıtılabilir yapıtlar gibi yönetir: CI içinde klasörün tamamını paketler, üretimde sürümleri sabitler ve konteyner yaşam döngüsü için otomatik testler çalıştırır.

Altı uç noktayı Apidog içinde modelleyin, sürüm güncellemesini bir test senaryosuna bağlayın ve hatalı bir beceri sürümünün sunum oluşturucunuzu bozduğunu kullanıcılarınızdan önce tespit edin. Sistemi bir öğleden sonra kurmak için Apidog'u ücretsiz indirin.