SKILL.md, CLAUDE.md ve AGENTS.md farkı nedir?
Bu üç dosya sık sık karıştırılır ama farklı işler çözer. SKILL.md, CLAUDE.md ve AGENTS.md gerçekte nerede ayrılır — ve çoğu proje neden birden fazlasını kullanır?
Bu üçü neden karıştırılıyor
AI kodlama yapılandırmasını araştırınca SKILL.md, CLAUDE.md ve AGENTS.md yan yana karşına çıkar; sanki birini seçmen gerekiyormuş gibi. Gerekmiyor. Bunlar aynı yeri paylaşan üç rakip değil.
Asıl ayrım yükleme biçiminde:
- CLAUDE.md ve AGENTS.md aynı kategoride — her oturumun başında tam olarak yüklenen always-on (her oturumda yüklü) proje talimatları.
- SKILL.md farklı bir mekanizma — yalnızca göreve uyduğunda yüklenen, model tarafından çağrılan on-demand bir yetenek (progressive disclosure / kademeli açığa çıkarma).
Bunu bir kez içselleştirince "vs" büyük ölçüde ortadan kalkar. Her birini tek tek açalım.
Her biri nedir
SKILL.md
SKILL.md, bir Agent Skill'in giriş noktasıdır: içinde bir SKILL.md dosyası (YAML frontmatter'da name + description, ardından Markdown talimatlar) ve isteğe bağlı scripts/, references/, assets/ klasörleri bulunan bir dizin. Anthropic bunu 18 Aralık 2025'te açık, vendor-neutral bir standart olarak yayımladı (agentskills.io).
Progressive disclosure kullanır, üç seviye:
1. Başlangıçta sistem prompt'unda yalnızca skill'in name + description bilgisi durur. 2. Tam SKILL.md gövdesi yalnızca model görevin eşleştiğine karar verince yüklenir. 3. Paketlenmiş dosyalar yalnızca talimatlar onlara uzanırsa açılır.
Yani bir skill tetiklenene kadar neredeyse hiç token harcamaz. Model tarafından çağrılır, always-on değildir — ve diğer ikisinin aksine bir skill çalıştırılabilir script taşıyabilir.
CLAUDE.md
CLAUDE.md, Claude Code'un bellek ve talimat dosyasıdır: Claude'un her oturumun başında okuduğu kalıcı bağlam (build/test komutları, konvansiyonlar, "her zaman/asla" kuralları). cwd'den dizin ağacında yukarı doğru olan dosyalar uzunluktan bağımsız olarak tam yüklenir ve sistem prompt'undan sonra bir kullanıcı mesajı olarak enjekte edilir. Bu bir yönlendirmedir, zorlayıcı bir yapılandırma değil — kesin kurallar için hooks ve permissions kullan.
AGENTS.md
AGENTS.md, araçtan bağımsız açık bir standarttır — repo köküne konan, adeta "AI ajanları için bir README". Uyumlu ajanlar bunu her oturumda otomatik yükler. Ağustos 2025 civarında (OpenAI/Codex öncülüğünde; Google, Cursor ve diğerleriyle) resmileşti ve artık birçok kodlama ajanı ve IDE tarafından okunuyor. CLAUDE.md ile aynı işlevsel kategoridedir; farkı Claude'a özel değil, cross-tool olması.
Karşılaştırma tablosu
| Boyut | SKILL.md | CLAUDE.md | AGENTS.md |
|---|---|---|---|
| Yükleme | On-demand (progressive disclosure) — başta yalnızca name+description | Always-on — her oturumda tam yüklü | Always-on — her oturumda otomatik yüklü |
| Kapsam | Tek, yeniden kullanılabilir skill / yetenek | Tüm proje (Claude Code) | Tüm proje (cross-tool) |
| Araçlar | Açık standart: Claude, Codex, Gemini CLI/Antigravity, Cursor ve daha fazlası | Yalnızca Claude Code (AGENTS.md değil, CLAUDE.md okur) | Cross-tool açık standart: 20+ ajan (Codex, Copilot, Gemini CLI, Cursor, Jules, Aider, Zed, Warp…) |
| Konum | ~/.claude/skills/<ad>/SKILL.md, .agents/skills/, ~/.gemini/skills/ vb. | ./CLAUDE.md veya ./.claude/CLAUDE.md; ~/.claude/CLAUDE.md; kurum politikası yolu | Repo kökünde AGENTS.md (monorepo'da iç içe; en yakın kazanır) |
| Script paketleyebilir mi | Evet (scripts/, references/, assets/) | Hayır | Hayır |
| En uygun kullanım | Ara sıra çağırdığın, göreve özel prosedürler | Her zaman gereken Claude Code repo bilgileri ve kuralları | Her zaman gereken repo bilgileri, birçok ajan arasında taşınabilir |
Hangisi ne zaman
Hızlı bir karar rehberi:
- Her oturumun ihtiyaç duyduğu temel bilgiler (build komutları, konvansiyonlar, mimari, katı kısıtlar)? Bir always-on dosya kullan. Codex, Cursor, Gemini CLI vb. arasında taşınabilir olsun istiyorsan AGENTS.md yaz. Yalnızca Claude Code kullanıyorsan CLAUDE.md yerel yoldur.
- **Yalnızca *bazı* görevlerde gereken çok adımlı bir prosedür ya da özel yetenek (sürüm kontrol listesi, migration runbook'u, yardımcı script'li bir formatter)? Bunu bir SKILL.md** skill'i yap ki on-demand yüklensin ve kalan zamanda token harcamasın.
- Her zaman bellekte durursa bağlamı şişirecek uzun referans materyali? Onu CLAUDE.md/AGENTS.md'ye değil, bir skill'in
references/klasörüne koy. - Önerilmesi değil, zorlanması mı gerekiyor? Bunların hiçbiri zorlamaz — hooks ve permissions'a yönel.
- Elinde AGENTS.md var ve Claude Code mı kullanıyorsun? Claude (2026 ortası itibarıyla) AGENTS.md'yi doğal okumaz;
AGENTS.md'yiCLAUDE.md'ye symlink'le ya da CLAUDE.md içinde@AGENTS.mdile içe aktar.
Resmi Claude Code yönlendirmesi bunu iyi özetler: her zaman gereken bilgileri CLAUDE.md'ye koy; göreve özel prosedürleri skill'lere taşı.
Birlikte kullanımı
Bunlar birbirini tamamlar, ya-o-ya-bu değildir. Sağlıklı bir kurulum şöyle görünür:
- Always-on temel için AGENTS.md (veya CLAUDE.md): nasıl build/test/lint edilir; adlandırma konvansiyonları; "bu dosyalara asla dokunma" kuralları.
- Özel, on-demand işler için SKILL.md skill'leri: changelog üretme, veri migration'ı çalıştırma, bir bileşen iskeleti çıkarma — her biri kendi talimatları ve isteğe bağlı script'leriyle.
SKILL.md her ajanda birebir aynı olan düz bir klasör + Markdown formatı olduğu için, aynı skill'i ~/.claude/skills, ~/.agents/skills ve ~/.gemini/skills arasında kopyalayabilir veya symlink'leyebilirsin; değişmeden çalışır. Böylece repo'n taşınabilir AGENTS.md bağlamını taşır, skill kütüphanen ise taşınabilir yetenekleri — biri temel için, biri on-demand için.
Aracına göre skill oluştur
Agent Skills ana rehberiyle başla, sonra ajanının rehberini izle:
Bir tane oluşturmaya hazır mısın? Çalışan bir SKILL.md üretmek için Skill Builder'ı kullan ya da gerçek örnekler için skill'lere göz at.