Agent Skills Açık Standardı Rehberi: Tek SKILL.md ile Claude Code, Cursor, Gemini CLI ve Claude API

Q: Skill klasörünü hangi dizine koymalıyım ki birden fazla araç görsün?

Claude Code proje skill'lerini .claude/skills/ altında arar. Cursor .agents/skills/ ve .cursor/skills/ yanında uyumluluk için .claude/skills/ dizinini de okur. Gemini CLI ise .gemini/skills/ veya .agents/skills/ altında arar. Yani .claude/skills/ Claude Code ve Cursor'u, .agents/skills/ Cursor ve Gemini CLI'ı kapsar; üç aracı birlikte hedefliyorsanız iki dizini de beslemeniz gerekir.

Q: Skill adında claude kelimesini kullanabilir miyim?

Claude API ve claude.ai tarafında hayır: name alanı en fazla 64 karakter olabilir, yalnızca küçük harf, rakam ve tire içerebilir, XML etiketi ve anthropic ile claude ayrılmış kelimelerini içeremez. Taşınabilir bir skill için bu kuralları baştan uygulamak en güvenli yoldur.

Anthropic, 22 Ekim 2026'da Agent Skills standardını Agentic AI Foundation'a (AAIF) devrettiğini duyurdu. Bir yıl önce Claude Code için tasarlanan ve kökünde basit bir SKILL.md dosyası olan bu biçim, artık tek bir şirketin değil, Linux Foundation çatısındaki tarafsız bir vakfın yönetiminde. Duyuruya göre standart 70'ten fazla ajan platformuna entegre edilmiş durumda; aralarında ChatGPT, Cursor, GitHub Copilot ve VS Code var. Yayımlanmış skill sayısı 1 milyonu, kurulum sayısı ise yaklaşık 280 milyonu bulmuş.

Bu haber bir geliştirici için tek bir pratik soruya indirgeniyor: Bir kez yazdığım skill'i, ekibimin kullandığı farklı araçlarda gerçekten çalıştırabilir miyim? Cevap "evet, ama kurallara uyarsanız". Bu yazıda devrin ne anlama geldiğini, standardın çekirdeğini, Claude Code'a özgü uzantıların nerede taşınabilirliği bozduğunu, Claude Code, Cursor, Gemini CLI ve Claude API'nin skill'leri hangi dizinlerden okuduğunu ve sıfırdan taşınabilir bir skill'i nasıl yazıp dört ortama dağıtacağınızı adım adım anlatacağım. Claude Code'daki skill özelliklerinin tamamını (slash komutlarla birleşme, argümanlar, alt ajan içinde çalıştırma) merak ediyorsanız önce Claude Code'da Agent Skills ve slash komutları rehberine göz atabilirsiniz; bu yazı onun "araçlar arası" devamıdır.

Agent Skills AAIF'e Devredildi: Ne Değişti, Ne Değişmedi?

Duyurudaki kronoloji şöyle:

Ekim 2025: Skills, Claude Code ile birlikte çıktı. Anthropic'e göre geliştiriciler kısa sürede GitHub'da binlerce skill yayımladı ve Codex, Cursor ve OpenCode için yükleyiciler yazdı.
Aralık 2025: Anthropic, Agent Skills'i kendi GitHub organizasyonu ve alan adı altında açık standart olarak yayımladı. Anthropic Engineering blogundaki orijinal skill yazısına da 18 Aralık 2025 tarihli bir not düşülerek standardın platformlar arası taşınabilirlik için açıldığı belirtildi.
22 Ekim 2026: Standart AAIF'e devredildi.

Devredilenler

Devir paketinde dört şey var: standardın kendisi, Agent Skills adı ve logosu, GitHub organizasyonu ve agentskills.io alan adı. AAIF, Anthropic'in 2025'te Block ve OpenAI ile birlikte kurduğu bir Linux Foundation projesi; Anthropic, Model Context Protocol'ü (MCP) de daha önce aynı vakfa devretmişti. Yani MCP ve Agent Skills artık aynı tarafsız çatı altında duruyor.

Yönetim modeli

Standart, Anthropic, Google, OpenAI ve diğer şirketlerden mühendisler tarafından bireysel olarak bakımı yapılacak. Lider bakımcılar David Soria Parra ve Mahesh Murag.
Anthropic, standardın açık, topluluk odaklı ve satıcıdan bağımsız kalacağını söylüyor.
Standardı kullanmak ya da katkı vermek için AAIF'e üye olmanız gerekmiyor.

Geliştirici için değişen bir şey var mı?

Kısa cevap: bugün için hayır. Duyuru, mevcut skill biçiminde veya araçlarda bir değişiklik tarif etmiyor. Yalnızca bir yol haritası öneriyor: sürümlü yayınlar, değişiklikler için resmi bir öneri süreci ve skill yazanlar ile kuranlar için güvenlik rehberi. Bu üçü, kurumsal ekipler için önemli: standardın hangi sürümüne uyduğunuzu belirtebilmek ve skill tedarik zinciri riskine karşı ortak bir kılavuz, şu ana kadar her aracın kendi başına çözdüğü sorunlardı.

Pratik sonuç şu: bugün yazdığınız standart uyumlu bir skill, yarın AAIF yönetimindeki sürümlü spesifikasyonla da uyumlu olma ihtimali en yüksek skill'dir. Bu yüzden asıl yatırımı "standart çekirdeğe sadık kalmak" üzerine yapmak mantıklı.

Agent Skills Nedir? Standardın Çekirdeği

Anthropic'in tanımıyla bir skill, en basit hâliyle "SKILL.md dosyası içeren bir dizin"dir. SKILL.md iki parçadan oluşur: en üstte --- işaretleri arasında YAML frontmatter, altında Markdown talimatlar. Dizin ayrıca betikler, referans dokümanlar ve şablonlar içerebilir.

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start
...

Kademeli açılım (progressive disclosure)

Standardın en önemli tasarım ilkesi, Anthropic'in "Agent Skills'i esnek ve ölçeklenebilir kılan temel tasarım ilkesi" dediği kademeli açılımdır. Claude dokümantasyonu bunu üç seviyede tarif ediyor:

Seviye	Ne zaman yüklenir	Token maliyeti	İçerik
1: Metadata	Her zaman (başlangıçta)	Skill başına ~100 token	Frontmatter'daki `name` ve `description`
2: Talimatlar	Skill tetiklendiğinde	5 bin tokenın altında	`SKILL.md` gövdesi
3+: Kaynaklar	Gerektikçe	Erişilene kadar sıfır	Ek dosyalar; betikler çalıştırılır, yalnızca çıktıları bağlama girer

Bu modelin pratik etkisi büyük: onlarca skill kurabilirsiniz, çünkü tetiklenene kadar her biri yalnızca adı ve açıklaması kadar yer kaplar. Bir skill'in içine kapsamlı API dokümanları veya büyük veri dosyaları koymak da bağlam penceresini şişirmez; ajan yalnızca ihtiyaç duyduğu dosyayı okur. Betik kodu ise hiç bağlama girmez, sadece çıktısı girer.

Gemini CLI dokümantasyonu aynı yaşam döngüsünü kendi terimleriyle anlatıyor: oturum başında etkin skill'lerin adı ve açıklaması sistem istemine eklenir (keşif), görev bir açıklamayla eşleştiğinde model activate_skill aracını çağırır (aktivasyon), arayüz skill'in adını, amacını ve erişeceği dizini gösterip onay ister (rıza), onaydan sonra SKILL.md gövdesi ve klasör yapısı konuşmaya eklenir (enjeksiyon). Yani standart, farklı araçlarda aynı mantıkla çalışıyor; değişen, onay ve arayüz katmanı.

Önerilen klasör yapısı

Standardın zorunlu kıldığı tek dosya SKILL.md'dir. Cursor ve Gemini CLI dokümantasyonları isteğe bağlı üç alt klasörü aynı adlarla öneriyor:

my-skill/
├── SKILL.md          # zorunlu: frontmatter + talimatlar
├── scripts/          # çalıştırılabilir betikler
├── references/       # statik dokümantasyon
└── assets/           # şablonlar ve diğer kaynaklar

Taşınabilir bir skill yazarken bu üç klasör adını kullanmak, hem okunabilirlik hem de araçların kendi skill oluşturucularıyla uyum açısından iyi bir varsayılandır.

Taşınabilir SKILL.md İçin Frontmatter Kuralları

Taşınabilirliği en çok bozan şey frontmatter'dır. Her araç standart çekirdeği tanır, ama kendi uzantılarını da ekler ve bilinmeyen alanlara farklı tepki verir. Kuralları en katı yüzey olan Claude API'den başlayarak toplayalım.

name ve description: en katı kurallar

Claude API ve claude.ai'ye yüklenecek skill'ler için iki alan zorunludur ve şu kurallara tabidir:

name: en fazla 64 karakter; yalnızca küçük harf, rakam ve tire; XML etiketi içeremez; anthropic ve claude ayrılmış kelimelerini içeremez.
description: boş olamaz; en fazla 1.024 karakter; XML etiketi içeremez.

Diğer araçlar da adla klasör arasında eşleşme bekliyor. Cursor'da name yalnızca küçük harf, rakam ve tire içerebilir ve üst klasörün adıyla aynı olmalıdır. Gemini CLI dokümantasyonu da adın dizin adıyla eşleşmesi gerektiğini söylüyor. Claude Code'da ise name isteğe bağlıdır ve verilmezse dizin adı kullanılır. Yani taşınabilir bir skill için kural basit: klasör adı = name = küçük harf, rakam ve tire; içinde "claude" veya "anthropic" geçmesin.

Açıklama tarafında ise iki farklı sınır var: Claude API 1.024 karakterde keser; Claude Code ise skill listesinde description ve when_to_use toplamını 1.536 karakterde kırpar. Taşınabilir skill için 1.024'ün altında kalın ve en önemli kullanım durumunu cümlenin başına yazın.

Claude Code dışında izin verilen alanlar

Claude Code dokümantasyonu kritik bir uyarı içeriyor: Claude Code dışında (claude.ai yüklemeleri, Skills API ve package_skill.py) frontmatter'da yalnızca şu altı alana izin veriliyor: name, description, license, compatibility, metadata, allowed-tools. Başka herhangi bir anahtar paketleme ya da yükleme sırasında kesin hataya yol açıyor.

Claude Code ise ters yönde hoşgörülü: tanımadığı alanları sessizce yok sayıyor ve metadata, license, compatibility spesifikasyon alanlarını kabul edip üzerlerinde bir işlem yapmıyor. compatibility alanı en fazla 500 karakter olabiliyor.

Alan uyumluluk tablosu

Aşağıdaki tablo, kaynaklarda açıkça belgelenen davranışları özetliyor. "Belgelenmemiş" yazan hücreler, o aracın dokümantasyonunda bu alanın geçmediği anlamına gelir; davranışı test etmeden varsaymayın.

Alan	Claude Code	Claude API / claude.ai	Cursor	Gemini CLI
`name`	İsteğe bağlı, varsayılan dizin adı	Zorunlu, 64 karakter, ayrılmış kelime yok	Zorunlu, klasör adıyla aynı	Zorunlu, dizin adıyla eşleşmeli
`description`	Önerilir; listede 1.536 karakterde kırpılır	Zorunlu, en fazla 1.024 karakter	Zorunlu	Zorunlu (kritik)
`license`, `compatibility`, `metadata`	Kabul eder, işlem yapmaz	İzinli	`metadata` destekli	Belgelenmemiş
`allowed-tools`	Destekli (çağıran tur için ön onay)	İzinli	Belgelenmemiş	Belgelenmemiş
`disable-model-invocation`	Destekli	Yükleme hatası	Destekli	Belgelenmemiş
`paths`	Destekli (glob)	Yükleme hatası	Destekli (eski `globs` da kabul)	Belgelenmemiş
`context: fork`, `agent`, `model`, `effort`, `hooks`	Destekli	Yükleme hatası	Belgelenmemiş	Belgelenmemiş

Tablodan çıkan strateji: API'ye de yükleyecekseniz frontmatter'ı altı alanla sınırlayın. Yalnızca yerel ajanlar (Claude Code, Cursor, Gemini CLI) hedefteyse, disable-model-invocation ve paths gibi iki aracın ortak desteklediği uzantıları kullanmak makul; Claude Code'a özgü context: fork gibi alanları ise diğer araçlarda etkisiz kalacaklarını bilerek ekleyin.

Hangi Araç Skill'leri Nereden Okur?

Taşınabilirliğin ikinci ayağı dizinler. Aynı skill'i her araç farklı bir klasörde arıyor; bazıları diğerlerinin klasörlerini uyumluluk için de tarıyor.

Claude Code

Seviye	Yol	Kapsam
Kişisel	`~/.claude/skills/<ad>/SKILL.md`	Tüm projeleriniz
Proje	`.claude/skills/<ad>/SKILL.md`	Bu depo (commit'leyerek paylaşılır)
İç içe	`<altdizin>/.claude/skills/<ad>/SKILL.md`	O alt dizin ve altındaki oturumlar
Plugin	`<plugin>/skills/<ad>/SKILL.md`	Plugin etkinse, `/plugin-adı:skill-adı` olarak
Kurumsal	Yönetilen ayarlar dizinindeki `.claude/skills/`	Yönetilen makinelerdeki tüm kullanıcılar

Ad çakışmasında kurumsal kişiseli, kişisel de projeyi ezer; plugin skill'leri isim alanıyla ayrıldığı için çakışmaz. --add-dir ile eklenen dizinlerdeki .claude/skills/ da o oturum için okunur.

Cursor

Cursor proje düzeyinde .agents/skills/ ve .cursor/skills/, kullanıcı düzeyinde ~/.agents/skills/ ve ~/.cursor/skills/ dizinlerini okuyor. Uyumluluk için ayrıca .claude/skills/, .codex/skills/, ~/.claude/skills/ ve ~/.codex/skills/ dizinlerini de yüklüyor. Skill kökünü özyinelemeli tarıyor; kategori klasörleri yalnızca düzen içindir, skill'in kimliğini SKILL.md'yi içeren klasör belirler. Monorepo'da iç içe bir proje klasöründeki .cursor/skills/ veya .agents/skills/ yalnızca o klasörün altındaki dosyalara uygulanıyor. Bulut ajanlarına yalnızca ~/.cursor/skills/ senkronize oluyor; ~/.agents/skills/ kopyalanmıyor.

Gemini CLI

Gemini CLI dört katmanda arıyor (düşükten yükseğe öncelik): yerleşik skill'ler, eklenti (extension) skill'leri, kullanıcı skill'leri (~/.gemini/skills/ ya da takma adı ~/.agents/skills/) ve çalışma alanı skill'leri (.gemini/skills/ ya da takma adı .agents/skills/). Aynı katmanda .agents/skills/, .gemini/skills/'ten önceliklidir. Dokümantasyon, .agents/skills yolunun Agent Skills standardını izleyen diğer araçlarla uyumluluk için var olduğunu açıkça yazıyor.

Claude API ve claude.ai

API tarafında dizin yok; skill'ler /v1/skills uç noktalarıyla yüklenir ve çalışma alanının (workspace) tamamıyla paylaşılır. claude.ai'de ise özel skill'ler zip dosyası olarak yüklenir (Pro, Max, Ultra, Team ve Enterprise planlarında, kod çalıştırma açıkken). Önemli bir not: özel skill'ler yüzeyler arasında senkronize olmuyor. claude.ai'ye yüklenen skill API'de, API'ye yüklenen claude.ai'de görünmüyor; Claude Code skill'leri ise ikisinden de ayrı, dosya sistemi tabanlı.

Codex ve diğerleri

OpenAI tarafında, artık kullanımdan kaldırıldığı belirtilen openai/skills deposunun README'si, Codex'te skill kurmak için $skill-installer komutunu gösteriyor (örneğin $skill-installer gh-address-comments) ve kurulumdan sonra Codex'in yeniden başlatılması gerektiğini söylüyor. README, güncel örnekler için openai/plugins deposunu işaret ediyor; orada her Codex plugin'i isteğe bağlı bir skills/ klasörü taşıyabiliyor. Codex'in yerel skill dizinleri bu yazının kaynak listesindeki belgelerde yer almadığı için burada yol vermiyorum. Codex CLI'ın genel kullanımı için OpenAI Codex CLI rehberine bakabilirsiniz.

Özet: dizin matrisi

Proje dizini	Claude Code	Cursor	Gemini CLI
`.claude/skills/`	Evet	Evet (uyumluluk)	Belgelenmemiş
`.agents/skills/`	Belgelenmemiş	Evet	Evet
`.cursor/skills/`	Hayır	Evet	Hayır
`.gemini/skills/`	Hayır	Hayır	Evet

Tek bir dizin üçünü birden kapsamıyor. En pratik düzen: skill'in asıl kopyasını .agents/skills/ altında tutmak (Cursor ve Gemini CLI okur) ve Claude Code için .claude/skills/ altına aynı klasörü yerleştirmek. Aynı dosyanın iki kopyasını elle senkronize etmek hataya açık olduğundan, aşağıdaki iş akışında küçük bir senkronizasyon betiği kullanacağız.

Gerçek İş Akışı: Taşınabilir Bir Migration İnceleme Skill'i

Senaryo: ekibinizde bazı geliştiriciler Claude Code, bazıları Cursor, bazıları Gemini CLI kullanıyor. Hepsinin SQL migration dosyalarını aynı kurallarla incelemesini istiyorsunuz: tablo veya sütun silen komutlar açık onay yorumu taşımalı. Ayrıca aynı kuralları CI'da Claude API ile de çalıştırmak istiyorsunuz.

Adım 1: Klasör ve SKILL.md

Ad seçerken kuralları hatırlayalım: küçük harf, rakam, tire; "claude" yok; klasör adıyla aynı. Anthropic'in en iyi pratikler rehberi isimlerde fiil+-ing (gerund) biçimini öneriyor (processing-pdfs, testing-code gibi); reviewing-migrations iyi bir aday.

mkdir -p .agents/skills/reviewing-migrations/scripts

.agents/skills/reviewing-migrations/SKILL.md:

---
name: reviewing-migrations
description: Reviews SQL migration files for destructive statements (DROP TABLE, DROP COLUMN, TRUNCATE) and checks that each one carries an approval comment. Use when the user adds or edits files under migrations/, asks to review a migration, or mentions schema changes.
license: Apache-2.0
metadata:
  owner: platform-team
  version: "1.0"
---

# Reviewing migrations

## Workflow

1. List the changed migration files.
2. Run the checker on each file:
   ```bash
   python3 scripts/check_migration.py path/to/migration.sql
   ```
3. If the checker prints `FAIL`, quote the reported lines and ask the
   author to add an `-- approved: <ticket>` comment on the line above,
   or to rewrite the statement.
4. Only report the review as passed when every file prints `OK`.

## Rules

- Never edit a migration that has already been applied; propose a new one.
- Destructive statements MUST have an approval comment directly above them.
- For column renames, prefer add-copy-drop over in-place rename.

Dikkat edilecek noktalar:

Açıklama üçüncü şahısla yazıldı. En iyi pratikler rehberi bunu açıkça istiyor; açıklama sistem istemine enjekte edildiği için "I can help you..." ya da "You can use this..." gibi tutarsız bakış açıları keşif sorunlarına yol açabiliyor.
Açıklama hem "ne"yi hem "ne zaman"ı söylüyor. Ajan, onlarca skill arasından seçimi yalnızca bu metne bakarak yapıyor.
Frontmatter yalnızca izinli altı alandan oluşuyor (name, description, license, metadata). Bu skill'i API'ye de sorunsuz yükleyebiliriz.
Betik göreli yolla çağrılıyor (scripts/check_migration.py) ve ileri eğik çizgi kullanılıyor. Rehber, Windows tarzı ters eğik çizgilerin Unix sistemlerde hata verdiğini hatırlatıyor.
"MUST" gibi güçlü bir dil kritik kural için kullanıldı; rehber, bir kuralın gözden kaçtığını gördüğünüzde dili güçlendirmeyi öneriyor.

Adım 2: Deterministik işi betiğe bırakın

Anthropic'in rehberi, kırılgan ve tutarlılık gerektiren işler için "düşük serbestlik" önerir: modelin her seferinde kontrol kodu üretmesi yerine hazır bir betik çalıştırması. Betik kodu bağlama girmez, yalnızca çıktısı girer. scripts/check_migration.py:

#!/usr/bin/env python3
"""Flags destructive SQL statements that lack an approval comment."""
import re
import sys

DESTRUCTIVE = re.compile(r"^\s*(DROP\s+TABLE|DROP\s+COLUMN|ALTER\s+TABLE\s+\S+\s+DROP|TRUNCATE)\b", re.I)
APPROVAL = re.compile(r"^\s*--\s*approved:\s*\S+", re.I)


def check(path):
    try:
        with open(path, encoding="utf-8") as f:
            lines = f.readlines()
    except FileNotFoundError:
        print(f"FAIL {path}: file not found")
        return False
    problems = []
    for i, line in enumerate(lines):
        if DESTRUCTIVE.search(line):
            prev = lines[i - 1] if i > 0 else ""
            if not APPROVAL.search(prev):
                problems.append(f"  line {i + 1}: {line.strip()}")
    if problems:
        print(f"FAIL {path}")
        print("\n".join(problems))
        return False
    print(f"OK {path}")
    return True


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("usage: check_migration.py FILE [FILE...]")
        sys.exit(2)
    results = [check(p) for p in sys.argv[1:]]
    sys.exit(0 if all(results) else 1)

Betik, dosya bulunamadığında çökmek yerine anlamlı bir mesaj veriyor. Bu da rehberdeki "çöz, modele bırakma" (solve, don't defer) ilkesinin karşılığı: hata durumlarını betik içinde ele alın, ajanın tahmin yürütmesine bırakmayın. Betik yalnızca standart kütüphane kullanıyor; bu, Claude API'nin ağ erişimi olmayan ve çalışma anında paket kurulamayan kapsayıcısında da çalışabilmesi için önemli.

Adım 3: Claude Code için kopya

Claude Code proje skill'lerini .claude/skills/ altında aradığı için klasörü oraya da yerleştirelim. Basit bir senkronizasyon:

mkdir -p .claude/skills
rsync -a --delete .agents/skills/reviewing-migrations/ .claude/skills/reviewing-migrations/

Bu komutu bir make skills hedefine ya da pre-commit kancasına koyarsanız iki kopya ayrışmaz. Cursor .claude/skills/ ve .agents/skills/ dizinlerinin ikisini de okuduğu için aynı adlı iki kopyayı nasıl ele aldığını kendi kurulumunuzda / menüsünden kontrol edin; çift görünüm can sıkıyorsa Cursor kullanıcılarının yalnızca bir kopyayı görmesini sağlayacak bir düzen seçin.

Adım 4: Her araçta doğrulama

Claude Code: Oturumda /reviewing-migrations yazarak skill'i doğrudan çağırabilir ya da "migrations/ altındaki son dosyayı incele" diyerek açıklamanın otomatik tetiklemeyi sağlayıp sağlamadığını görebilirsiniz.
Cursor: Agent sohbetinde / yazıp skill adını arayın. Bu şekilde çağrılan skill yalnızca o mesaja uygulanır.
Gemini CLI: /skills list ile yüklendiğini kontrol edin; geliştirme sırasında yaptığınız değişiklikleri /skills reload ile yenileyin. Skill aktive olduğunda Gemini CLI onay isteyecektir.

Adım 5: Aynı skill'i Claude API'ye yükleyin

Skills API, SKILL.md'nin yükleme kökünde (ya da tek bir kapsayıcı klasörün tepesinde) olmasını bekliyor. Toplam yükleme boyutu sıkıştırılmamış hâlde 30 MB'ın altında olmalı.

curl -X POST "https://api.anthropic.com/v1/skills" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -F "files[]=@reviewing-migrations/SKILL.md;filename=reviewing-migrations/SKILL.md" \
  -F "files[]=@reviewing-migrations/scripts/check_migration.py;filename=reviewing-migrations/scripts/check_migration.py"

Python SDK ile aynı iş birkaç satır:

import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()
skill = client.skills.create(files=files_from_dir("reviewing-migrations"))
print(skill.id, skill.latest_version_id)

Dokümantasyon, ant CLI'ı kullananlar için ant apply <klasör> komutunu da gösteriyor. Skill'i bir istekte kullanmak için container.skills dizisine ekleyip kod çalıştırma aracını tanımlamanız gerekiyor; skill'ler bu aracın kapsayıcısında çalışıyor:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "custom", "skill_id": skill.id, "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Review this migration: ..."}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Birkaç önemli API ayrıntısı:

Bir istekte en fazla 20 skill kullanabilirsiniz.
version alanına "latest" ya da yeni sürüm oluştururken dönen skver_... kimliğini verebilirsiniz. Anthropic'in hazır skill'leri (pptx, xlsx, docx, pdf) ise 20251013 gibi tarih biçimli sürümler kullanıyor.
Yeni sürüm (POST /v1/skills/<id>/versions) tam bir anlık görüntüdür: dosyaların hepsini yeniden yüklemeniz gerekir, atladığınız dosyalar taşınmaz; yeni sürümdeki name da mevcut adla aynı olmalıdır.
Örneklerde kullanılan anthropic-version: 2026-10-21 başlığı, API'nin en yeni sürümü. Eski bir sürümden geçiyorsanız Claude API 2026-10-21 geçiş rehberi kırılma değişikliklerini listeliyor.

CI'da kullanırken çalışma ortamı farkı

Aynı skill, yüzeye göre çok farklı bir ortamda çalışıyor. Claude dokümantasyonuna göre:

Yüzey	Ağ erişimi	Paket kurulumu
Claude API	Yok	Çalışma anında kurulamaz; yalnızca önceden kurulu paketler
claude.ai	Kullanıcı/yönetici ayarına göre tam, kısmi ya da yok	npm ve PyPI'dan kurabilir
Claude Code	Bilgisayardaki diğer programlarla aynı	Yalnızca yerel kurulum önerilir, global kurulum önerilmez

Migration betiğimizi yalnızca standart kütüphaneyle yazmamızın nedeni buydu. Skill'iniz bir pip paketine ihtiyaç duyuyorsa, gerekli paketleri SKILL.md'de açıkça listeleyin ve API'de hedefliyorsanız kod çalıştırma aracının önceden kurulu paket listesinde olup olmadığını kontrol edin.

Taşınabilir Skill Yazmanın En İyi Pratikleri

Anthropic'in "Skill authoring best practices" sayfası Claude için yazılmış olsa da önerilerin neredeyse tamamı standart düzeyinde; yani hangi ajan çalıştırırsa çalıştırsın işe yarıyor. Taşınabilirlik açısından en kritik olanlar:

Kısa tutun: bağlam ortak bir kaynak

Rehberin varsayımı net: "Model zaten çok akıllı." Yalnızca modelin bilmediği bağlamı ekleyin. Örnekte, PDF'in ne olduğunu anlatan ~150 tokenlık açıklama yerine doğrudan pdfplumber örneği veren ~50 tokenlık sürüm öneriliyor. SKILL.md gövdesini 500 satırın altında tutun; yaklaştığınızda içeriği ayrı dosyalara bölün.

Referansları tek seviye derinlikte tutun

Model, başka bir referans dosyasından işaret edilen dosyaları head -100 gibi komutlarla yalnızca kısmen okuyabiliyor. Bu yüzden tüm referans dosyalarına doğrudan SKILL.md'den bağlantı verin. 100 satırı geçen referans dosyalarının başına bir içindekiler bölümü ekleyin; böylece kısmi okumada bile kapsam görünür.

Serbestlik derecesini işin kırılganlığına göre ayarlayın

Yüksek serbestlik (metin talimatlar): birden fazla geçerli yaklaşım varsa, örneğin kod incelemesi.
Orta serbestlik (parametreli şablon ya da sözde kod): tercih edilen bir kalıp varsa.
Düşük serbestlik (belirli betik, az parametre): veritabanı migration'ı gibi tam sırayla yapılması gereken kırılgan işler.

Zamana bağlı bilgi yazmayın

"Ağustos 2025'ten önceyse eski API'yi kullan" gibi cümleler zamanla yanlış hâle gelir. Rehber, eski kalıpları katlanabilir bir "Old patterns" bölümüne taşımayı öneriyor.

MCP araçlarını tam adla anın

Skill'iniz MCP araçlarına başvuruyorsa SunucuAdı:araç_adı biçimini kullanın (örneğin GitHub:create_issue). Sunucu öneki olmadan, özellikle birden fazla MCP sunucusu varken, ajan aracı bulamayabilir. MCP'yi Claude Code tarafında nasıl yapılandıracağınızı Claude Code MCP rehberinde anlatmıştım; MCP de Agent Skills gibi AAIF bünyesinde.

Değerlendirmeyle başlayın, birden fazla modelle test edin

Rehber, kapsamlı doküman yazmadan önce değerlendirme oluşturmayı öneriyor: modeli skill olmadan temsili görevlerde çalıştırın, başarısızlıkları not edin, en az üç senaryo yazın, temel performansı ölçün ve yalnızca bu açıkları kapatacak kadar talimat yazın. Ayrıca skill'in etkinliği alttaki modele bağlı olduğu için kullanmayı planladığınız tüm modellerle test edin; Opus için kusursuz çalışan bir talimat Haiku için daha fazla ayrıntı isteyebilir. Taşınabilir skill'de bu ilke daha da önemli: aynı SKILL.md, Cursor'da veya Gemini CLI'da tamamen farklı bir modelle çalışacak.

Güvenlik: Skill Kurmak Yazılım Kurmaktır

Standardın yaygınlaşması, skill tedarik zincirini de büyük bir saldırı yüzeyine dönüştürüyor. AAIF yol haritasındaki güvenlik rehberi önerisi de bu yüzden önemli. Bugün için resmi dokümantasyonların söyledikleri:

Yalnızca güvenilir kaynaklar: Claude dokümantasyonu, kendi yazdığınız ya da Anthropic'ten aldığınız skill'leri kullanmayı öneriyor. Kötü niyetli bir skill, araçları belirtilen amacından farklı şekilde çağırabilir veya kod çalıştırabilir; veri sızdırma ya da yetkisiz erişime yol açabilir.
Her dosyayı denetleyin: SKILL.md, betikler, görseller ve diğer kaynaklar dahil. Beklenmeyen ağ çağrıları ya da amaçla uyuşmayan dosya erişimleri arayın.
Dış URL'den veri çeken skill'ler özellikle risklidir: çekilen içerik zararlı talimatlar barındırabilir; güvenilir bir skill bile bağımlılıkları değişirse tehlikeye girebilir.
Gemini CLI'da onay katmanı: skill aktive olmadan önce arayüz ad, amaç ve erişilecek dizini gösterip onay istiyor. gemini skills install <url> --consent bayrağı ise kurulumdaki güvenlik onayını atlıyor; bunu yalnızca denetlediğiniz kaynaklar için kullanın.
Claude Code'da kabuk enjeksiyonu: Claude Code'a özgü !`komut` sözdizimi, skill içeriği modele gitmeden önce kabuk komutu çalıştırır. Yöneticiler bunu "disableSkillShellExecution": true ayarıyla kapatabiliyor.
allowed-tools bir kısıtlama değildir: Claude Code'da bu alan listelenen araçlara yalnızca skill'i çağıran tur için ön onay verir; diğer araçları kısıtlamaz ve bir sonraki mesajınızda izin sıfırlanır.
API'de çalışma alanı kapsamı: özel skill'ler tüm çalışma alanına açıktır; o çalışma alanına erişimi olan her API anahtarı tüm skill'leri okuyabilir, kullanabilir ve silebilir. Çok kiracılı platformlar için dokümantasyon kiracı başına ayrı çalışma alanı öneriyor.
Veri saklama: Agent Skills, sıfır veri saklama (ZDR) kapsamında değil; skill tanımları ve çalıştırma verileri standart saklama politikasına göre tutuluyor.

Claude Code'da plugin ve marketplace üzerinden skill dağıtıyorsanız, güven modelini plugin marketplace rehberinde ayrıntılı ele almıştım. Anthropic'in kendi örnek skill'lerini denemek isterseniz anthropics/skills deposu bir marketplace olarak eklenebiliyor:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

Depo; skill örneklerini, Agent Skills spesifikasyonunu (./spec) ve bir şablonu (./template) içeriyor. README, bu skill'lerin gösterim ve eğitim amaçlı olduğunu, Claude'un gerçek davranışının farklı olabileceğini not ediyor; skill'lerin çoğu Apache 2.0 lisanslı.

Sık Karşılaşılan Sorunlar ve Çözümleri

API'ye yükleme hata veriyor: frontmatter'da izinli altı alan dışında bir anahtar var (örneğin disable-model-invocation ya da context). Bu alanları kaldırın veya Claude Code'a özel ayrı bir kopya tutun. Ayrıca name'de büyük harf, alt çizgi ya da "claude" kelimesi olmadığından emin olun.
Cursor skill'i görmüyor: name alanı üst klasörün adıyla birebir aynı mı? Cursor bunu zorunlu tutuyor.
Gemini CLI skill'i görmüyor: skill .claude/skills/ altındaysa Gemini CLI'ın belgelenmiş dizinleri arasında değil; .agents/skills/ ya da .gemini/skills/ altına taşıyın veya gemini skills link <yol> ile bağlayın, ardından /skills reload çalıştırın.
Claude Code'da frontmatter etkisiz: frontmatter dosyanın ilk satırında başlamalı. YAML ayrıştırılamazsa skill yine yüklenir ama hiçbir alan ayarlanmamış olur; bu sessiz bir hata olduğu için girintileri ve iki nokta üst üsteleri kontrol edin.
Skill hiç tetiklenmiyor: açıklama çok genel olabilir ("Helps with documents" gibi). Rehberdeki örnekler gibi hem yeteneği hem tetikleyici bağlamı (dosya türleri, anahtar kelimeler) yazın.
Uzun oturumda skill talimatları "unutuluyor": Claude Code'da otomatik sıkıştırmadan sonra çağrılmış her skill'in ilk 5.000 tokenı korunuyor, tüm skill'ler için toplam bütçe 25.000 token. Kritik kuralları SKILL.md'nin başına yazın.
claude.ai'ye yüklediğim skill API'de yok: beklenen davranış; yüzeyler senkronize olmuyor, her birine ayrı yüklemeniz gerekiyor.

Sıkça Sorulan Sorular

Agent Skills'in AAIF'e devredilmesi mevcut skill'lerimi bozar mı?

Hayır. Anthropic'in 22 Ekim 2026 duyurusu mevcut skill biçiminde ya da araçlarda bir değişiklik tarif etmiyor. Devredilen şey standardın kendisi, adı ve logosu, GitHub organizasyonu ve agentskills.io alan adı. Yol haritasında sürümlü yayınlar, resmi bir değişiklik önerisi süreci ve skill yazan/kuran kişiler için güvenlik rehberi önerileri var.

Bir SKILL.md'yi hem Claude Code'da hem Claude API'de kullanabilir miyim?

Evet, ama frontmatter'ı ortak alt kümeyle sınırlamanız gerekir. Claude Code dışındaki yüzeylerde (claude.ai yüklemesi, Skills API) yalnızca name, description, license, compatibility, metadata ve allowed-tools alanlarına izin verilir; başka bir anahtar yükleme sırasında kesin hataya yol açar. Ayrıca skill'ler yüzeyler arasında senkronize olmaz, her yüzeye ayrı yüklenir.

Skill klasörünü hangi dizine koymalıyım ki birden fazla araç görsün?

Claude Code proje skill'lerini .claude/skills/ altında arar. Cursor .agents/skills/ ve .cursor/skills/ yanında uyumluluk için .claude/skills/ dizinini de okur. Gemini CLI ise .gemini/skills/ veya .agents/skills/ altında arar. Yani .claude/skills/ Claude Code ve Cursor'u, .agents/skills/ Cursor ve Gemini CLI'ı kapsar; üç aracı birlikte hedefliyorsanız iki dizini de beslemeniz gerekir.

Skill adında claude kelimesini kullanabilir miyim?

Claude API ve claude.ai tarafında hayır: name alanı en fazla 64 karakter olabilir, yalnızca küçük harf, rakam ve tire içerebilir, XML etiketi ve anthropic ile claude ayrılmış kelimelerini içeremez. Taşınabilir bir skill için bu kuralları baştan uygulamak en güvenli yoldur.

İnternetten bulduğum bir skill'i kurmak güvenli mi?

Ancak denetledikten sonra. Anthropic dokümantasyonu skill'leri yazılım kurmak gibi değerlendirmeyi ve yalnızca kendi yazdığınız ya da Anthropic'ten aldığınız skill'leri kullanmayı öneriyor. Kötü niyetli bir skill araçları amacı dışında çağırabilir veya veri sızdırabilir. SKILL.md, betikler ve dış URL'lere yapılan çağrılar dahil tüm dosyaları okuyun.

Özet

Agent Skills'in 22 Ekim 2026'da Agentic AI Foundation'a devredilmesi, Claude Code için doğan bir biçimin MCP gibi sektör ortak standardına dönüştüğünü resmîleştirdi. Bugün için mevcut skill'lerde değişen bir şey yok; ama yol haritasındaki sürümlü yayınlar, öneri süreci ve güvenlik rehberi, standarda sadık skill'lerin gelecekte de sorunsuz çalışacağı anlamına geliyor. Taşınabilir bir skill için kurallar özetle şunlar: klasör adı ile name aynı olsun ve yalnızca küçük harf, rakam ve tire içersin, "claude"/"anthropic" geçmesin; description üçüncü şahısla, 1.024 karakterin altında ve hem "ne"yi hem "ne zaman"ı anlatsın; API'ye de yükleyecekseniz frontmatter'ı altı izinli alanla sınırlayın; deterministik işleri yalnızca standart kütüphaneyle yazılmış betiklere bırakın; asıl kopyayı .agents/skills/ altında tutup Claude Code için .claude/skills/'e senkronize edin. Ve her zaman: başkasının skill'ini kurmadan önce her satırını okuyun.

Devam okumaları için: Claude Code'a özgü skill özelliklerini (argümanlar, context: fork, dinamik bağlam) Agent Skills ve slash komutları rehberinde, Gemini CLI'ın genel kurulumunu ve GEMINI.md'yi Gemini CLI rehberinde, skill'leri ekibinize dağıtmanın yolunu ise plugin marketplace rehberinde bulabilirsiniz.