Anthropic Resmi Ajan Yetenekleri Eğitimi: 6 Derslik Kursun Tam Notları

Anthropic nihayet resmi bir Agent Skills eğitim videosu yayınladı. Toplam 22 dakika süren 6 dersten oluşan bu video, Skills'in ne olduğundan nasıl oluşturulacağına, çoklu dosya yapılandırmasına, diğer özelliklerden farkına, paylaşımına ve sorun gidermeye kadar tüm yaşam döngüsünü kapsıyor.

Bu eğitimin en büyük değeri, yalnızca nasıl Skill yazılacağını öğretmek değil, Skills'in tasarım felsefesini ve altında yatan mekanizmaları açıklamasıdır. İnsanların Skills kullanırken karşılaştığı birçok sorun, bu mekanizmaların yeterince anlaşılmamasından kaynaklanır.

Skills Hangi Sorunları Çözer?

Ekibinizin kodlama standartlarını Claude'a her açıkladığınızda, kendinizi tekrar ediyorsunuz. Her PR incelemesinde, geri bildirimin nasıl düzenlenmesini istediğinizi yeniden tarif etmek zorunda kalıyorsunuz. Her commit mesajında, Claude'a tercih ettiğiniz formatı hatırlatmanız gerekiyor.

Skills bu tekrarı ortadan kaldırmak için tasarlanmıştır. Bir Skill, Claude'a bir şeyin nasıl yapılacağını bir kez öğreten bir Markdown dosyasıdır ve Claude bu bilgiyi ilgili durumlarda otomatik olarak uygular.

Daha doğrusu, bir Agent Skill, talimatlar, betikler ve kaynaklar içeren bir klasördür. Claude, işi daha doğru ve verimli bir şekilde tamamlamak için bunları otomatik olarak keşfedebilir ve kullanabilir.

Temel mekanizma description alanıdır. Claude başladığında, tüm Skills'in adlarını ve açıklamalarını yükler. Bir istek gönderdiğinizde Claude, isteğinizle mevcut tüm Skills'in açıklamaları arasında anlamsal eşleme yaparak eşleşeni bulur ve etkinleştirir. Skill yalnızca etkinleştirildiğinde tam içeriği bağlam penceresine yüklenir.

Bu, claude.md'den temel olarak farklıdır. claude.md'nin içeriği, ne yaptığınızdan bağımsız olarak her konuşmaya yüklenir. Bir Skill yalnızca ihtiyaç duyulduğunda yüklenir; PR inceleme kontrol listenizin hata ayıklama sırasında bağlamda olması gerekmez, yalnızca gerçekten bir inceleme talep ettiğinizde görünür.

Bir Skill'i ne zaman kullanmalısınız? Kendinizi Claude'a aynı şeyi tekrar tekrar açıklarken buluyorsanız, bu geliştirilmeyi bekleyen bir Skill'dir.

İlk Skill'inizi Sıfırdan Oluşturma

Bir Skill oluşturmak yalnızca iki adım gerektirir: bir dizin oluşturmak ve bir dosya yazmak.

Birinci adım: ~/.claude/skills/ altında Skill'in adını taşıyan bir dizin oluşturun. Buraya yerleştirmek, bunun kişisel düzeyde bir Skill olduğu ve tüm projelerde kullanılabileceği anlamına gelir.

İkinci adım: Dizinde bir SKILL.md dosyası oluşturun. Dosya, üç çizgiyle ayrılmış iki bölümden oluşur. Üst kısım, name ve description içeren YAML meta verileridir. Alt kısım, Claude'un izlemesi için özel talimatları içerir.

Claude Code başladığında, dört konumu tarar: kurumsal yollar, kişisel Skills dizini, proje Skills dizini ve yüklü eklentiler. Her Skill'in yalnızca adını ve açıklamasını yükler, tam içeriğini değil.

Bir istek gönderdiğinizde Claude, isteği tüm Skill açıklamalarıyla karşılaştırır. Amaç eşleşirse, önce Skill'i yüklemek isteyip istemediğinizi onaylamanızı ister. Yalnızca onaydan sonra tam dosyayı okur ve talimatları yürütür. Bu onay adımı, Claude'un hangi bağlamı kullandığının farkında olmanızı sağlar.

Aynı ada sahip Skills varsa, öncelik yüksekten düşüğe şöyledir: Kurumsal düzey (managed-settings.json), Kişisel düzey (~/.claude/skills), Proje düzeyi (project/.claude/skills) ve Eklenti düzeyi (project/.claude-plugins/skills).

Bu, bir şirketin kurumsal düzeydeki Skills aracılığıyla standartları zorunlu kılabileceği, aynı zamanda bireylerin farklı adlara sahip Skills aracılığıyla özelleştirme yapmasına izin verebileceği anlamına gelir. Şirketinizin kurumsal bir kod inceleme Skill'i varsa, onu geçersiz kılmak yerine tamamlamak için front-end-pr-review adında kişisel bir Skill oluşturabilirsiniz.

Gelişmiş Yapılandırma: Meta Veri Alanları ve Aşamalı Açıklama

Temel Skills yalnızca name ve description gerektirir, ancak birkaç gelişmiş yapılandırma Skills'i daha güçlü hale getirebilir.

allowed-tools alanı, Skill etkinken Claude'un hangi araçları kullanabileceğini sınırlayabilir. Örneğin, salt okunur bir analiz Skill'iniz varsa, düzenleme, yazma ve Bash komutlarını yasaklayabilirsiniz. Bu alan atlanırsa, Skill herhangi bir kısıtlama getirmez ve Claude normal izin modelini kullanır.

model alanı, hangi Claude model sürümünün kullanılacağını belirtebilir.

description'ın yazılma şekli, bir Skill'in doğru şekilde tetkiklenip tetiklenmeyeceğini doğrudan belirler. İyi bir açıklama iki soruyu yanıtlamalıdır: Bu Skill ne işe yarar? Claude bunu ne zaman kullanmalı? Bir Skill tetiklenmezse, isteklerinizin ifadesiyle eşleşen daha fazla anahtar kelime ekleyin.

En önemli gelişmiş kavram aşamalı açıklamadır (progressive disclosure). Skills, konuşmanızla bağlam penceresini paylaşır. Her şeyi 20.000 satırlık bir SKILL.md dosyasına tıkıştırırsanız, büyük miktarda bağlam alanı tüketir.

Doğru yaklaşım şudur: Temel talimatları SKILL.md'ye koyun ve ayrıntılı referans materyallerini, Claude'un yalnızca ihtiyaç duyduğunda okuyacağı ayrı dosyalara koyun. Açık standartlar için önerilen dizin yapısı şöyledir: yürütülebilir kod için scripts klasörü, referans belgeler için references ve resimler ve şablonlar gibi veri dosyaları için resources. Bu dosyalara başvurmak için SKILL.md'de bağlantılar kullanın.

Temel kural: SKILL.md 500 satırı geçmemelidir. Geçerse bölünmelidir. Betikler, içerikleri bağlama yüklenmeden doğrudan yürütülebilir; yalnızca çıktı token tüketir. Bu nedenle, Claude'a betiği okumasını değil, çalıştırmasını söyleyin. Bu, ortam doğrulama ve veri dönüşümü için özellikle kullanışlıdır, çünkü test edilmiş betik kodu, anında oluşturulan koddan daha güvenilirdir.

Skills ve Diğer Claude Code Özellikleri Arasındaki Farklar

Skills vs. claude.md: claude.md, her zaman geçerli olan proje standartları ve kuralları için her konuşmaya yüklenir, örneğin "Bu proje TypeScript strict modunu kullanır." Skills talep üzerine yüklenir, yalnızca Claude bir istekle eşleştirdiğinde etkinleştirilir.

Skills vs. Alt Agent'lar: Skills mevcut konuşmaya bilgi ekler; etkinleştirildiğinde talimatlar mevcut bağlama eklenir. Alt Agent'lar bağımsız bir bağlamda çalışır, görevleri tamamlar ve sonuçları ayrı ayrı gönderir, ana konuşmadan tamamen izole edilir.

Skills vs. Hook'lar: Hook'lar olay odaklıdır, belirli olaylar meydana geldiğinde tetiklenir, örneğin Claude her dosya kaydedildiğinde bir Linter çalıştırır. Skills istek odaklıdır, sorduğunuz sorulara göre etkinleşir.

Skills vs. MCP: MCP, harici araç bağlantıları sağlar ve Claude'un Gmail veya Notion gibi hizmetleri çağırmasına olanak tanır. Skills bilgi ve iş akışları sağlar, Claude'a belirli görevleri tamamlamak için bu araçların nasıl kullanılacağını söyler.

Tek cümleyle özet: claude.md her zaman açık talimatları tutar, Skills otomatik eşleşen uzmanlığı tutar, Alt Agent'lar izole bağlamlarda devredilen görevleri yürütür, Hook'lar olaylara yanıt verir ve MCP harici araçlara bağlanır. Hepsi bir arada kullanılabilir.

Skills Paylaşımı: Bireylerden Ekiplere ve Kuruluşlara

Skills'in değeri paylaşımda yatar. Yalnızca sizin kullandığınız bir PR inceleme Skill'i faydalıdır, ancak ekip tarafından paylaşılan bir Skill, kod incelemelerini standartlaştırabilir ve tutarlı bir deneyim sağlayabilir.

Paylaşmanın üç yolu:

Birincisi proje dizinidir. Skill'i kod deposunun .claude/skills dizinine ekleyin. Depoyu klonlayan herkes, ekstra kurulum gerektirmeden bu Skills'i otomatik olarak alır. Güncellemeler bir sonraki çekme işleminde alınır. Bu, ekip kodlama standartları ve projeye özgü iş akışları için uygundur.

İkincisi eklentilerdir. Eklentileri, Skills'i projeler arasında dağıtmanın bir yolu olarak düşünün. Bir uygulama mağazasına yüklendikten sonra, diğer kullanıcılar bunları indirip kurabilir. Skill'iniz genel amaçlıysa ve projeye özgü değilse, topluluk üyeleri için en iyi seçenek budur.

Üçüncüsü kurumsal dağıtımdır. Yöneticiler, yönetilen ayarlar aracılığıyla Skills'i tüm kuruluşa iletir. Kurumsal düzeydeki Skills en yüksek önceliğe sahiptir ve aynı ada sahip kişisel ve proje Skills'ini geçersiz kılar. Bu, zorunlu standartlar, güvenlik gereksinimleri ve uyumluluk iş akışları için kullanılır.

Önemli bir not: Alt Agent'lar Skills'inizi otomatik olarak devralmaz. Bir alt agent'a bir görev devrettiğinizde, yeni bir bağlamla başlar. Yerleşik agent'lar (Explorer, Plan, Verify) Skills'e hiç erişemez; yalnızca tanımladığınız özel alt agent'lar bunları kullanabilir ve agent.md dosyasında açıkça listelenmeleri gerekir.

Skills ile özel bir alt agent oluşturmak için .claude/agents dizininde bir agent.md dosyası oluşturun ve gerekli Skill adlarını listeleyen bir skills alanı ekleyin. Yalnızca alt agent'ın hedefiyle her zaman ilgili olan Skills'i listeleyin, çünkü bu Skills alt agent başladığında yüklenecektir.

Sorun Giderme Kılavuzu: Skills'in Başarısız Olmasının Altı Nedeni ve Çözümleri

Skill sorunları genellikle altı kategoriye ayrılır:

1. Skill tetiklenmiyor: Nedeni neredeyse her zaman kötü yazılmış bir description'dır. Claude anlamsal eşleme kullanır; isteğinizin açıklamanın anlamıyla uyumlu olması gerekir. Yeterli örtüşme yoksa eşleşmez. Çözüm: Açıklamayı istek ifadenizle karşılaştırın ve kullanıcıların gerçekte söylediği tetikleyici ifadeleri ekleyin, örneğin "analiz etmeme yardım et," "bu neden yavaş," veya "hızlandır."

1. Skill yüklenemiyor: Yolları ve dosya adlarını kontrol edin. SKILL.md, skills kök dizininin içinde değil, adlandırılmış bir dizinin içinde olmalıdır. Dosya adı tam olarak büyük harflerle SKILL.md olmalıdır. Yükleme hatalarını görmek için claude --debug komutunu çalıştırın.

1. Claude yanlış Skill'i kullanıyor: Bu, açıklamaları çok benzer olan birden fazla Skill'iniz olduğu ve Claude'un bunları ayırt edemediği anlamına gelir. Çözüm: Her açıklamayı mümkün olduğunca spesifik hale getirerek Claude'un hangisini ne zaman kullanacağına karar vermesine yardımcı olun.

1. Kişisel Skill yok sayılıyor: Aynı ada sahip daha yüksek öncelikli bir Skill (örneğin kurumsal bir Skill) onu geçersiz kılıyor olabilir. Dört öncelik seviyesini kontrol edin. Çözüm: Skill'inizi daha benzersiz bir adla yeniden adlandırın.

1. Eklenti yüklendi ancak Skill görünmüyor: rm ~/.claude/plugins/cache ile önbelleği temizleyin, Claude Code'u yeniden başlatın ve yeniden yükleyin. Hala çalışmıyorsa, eklentinin dizin yapısı hatalı olabilir; kontrol etmek için skills-ref validate doğrulama aracını kullanın.

1. Skill yüklendi ancak yürütme sırasında başarısız oluyor: Skill harici paketler kullanıyorsa, bunların yüklü olduğundan emin olun. Skill'in açıklamasına bağımlılık bilgilerini ekleyin.

Anthropic ayrıca Skill'in dosya yapısının ve YAML sözdiziminin doğru olup olmadığını kontrol etmek için skills-ref adlı bir doğrulama aracı sağlar. En hızlı yöntem için uv ile kurulması önerilir.