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ı.
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.
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.anthropic
ve claude
kelimeleri ayrılmıştır.description
boş olamaz ve en fazla 1024 karakter olabilir.display_name
alanı en fazla 255 karakter olabilir.Beceriler iki kaynaktan gelir:
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.type: "custom"
) sizin tarafınızdan yüklenir, çalışma alanınıza özel olur ve skill_01AbCdEfGhIjKlMnOpQrStUv
gibi oluşturulmuş kimlikler alır.20 Ağustos 2026 itibarıyla öne çıkan değişiklikler şunlardır:
x-api-key
ve anthropic-version: 2023-06-01
başlıklarıyla kullanılabilir.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.
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.
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.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:
Kullanıcıların kullandığı tetikleyici ifadeleri açıklamada listelemek, genel bir tanımdan daha kullanışlıdır.
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:
tools
içinde etkinleştirin."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."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:
file_id
değerini alın.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:
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.
Ö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.
_turn
ve konteyneri yeniden kullanma Beceri yürütmeleri tek bir model turundan uzun sürebilir. Bu durumda iki mekanizma kullanılır.
_turn
Yanıt aşağıdaki durma nedeniyle tamamlanmadığında:
stop_reason: "_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.
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:
Her iki desen de durumlu HTTP dizileri oluşturur. Bu istekleri elle doğrulamak yerine Apidog senaryosuna bağlayabilirsiniz:
stop_reason
değerini doğrulayın.container.id
değerini ortam değişkenine aktarın.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.
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.
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.
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 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.
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.
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:
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.