Kendi Agent Yeteneğinizi Nasıl Oluşturursunuz?

Kendi agent yeteneğinizi gerçek bir hatadan yola çıkarak oluşturun

Kendi agent yeteneğinizi oluşturmanın en iyi yolu, bunu gerçek bir hatadan damıtarak elde etmektir. Kodlama agent'ınızın iki kez yanlış yaptığı bir görev bulun, her iki seferde de yazdığınız düzeltmeyi not edin ve bu düzeltmeyi agent'ın kendi kendine yükleyebileceği bir SKILL.md dosyası olarak kaydedin. Bundan sonraki her şey mekaniktir: dosya düzeni ve yeteneğin tetiklenip tetiklenmeyeceğine karar veren tek satırlık kod.

Bu sıra önemlidir. Hayal gücüne dayalı olarak yazılan bir yetenek, hiç yaşamadığınız bir sorunu belgeler ve her oturumda bağlam (context) tüketmeye devam eder. Gözlemlediğiniz bir hatadan damıtılan yetenek ise beraberinde kendi testini getirir: aynı şeyi tekrar sorun ve agent'ın bu sefer doğru yapıp yapmadığını görün. Eğer formatın kendisi sizin için yeniyse, önce agent yeteneklerinin ne olduğu ve bir agent'ın bunları nasıl yüklediği konusunu okuyun, ardından geri dönüp bir tane oluşturun.

İki kez hatalı gerçekleştirilen bir görevden yola çıkın

Bir kez olması tesadüftür. İki kez olması bir kalıptır ve bir kalıp, bir dosyayı hak eder.

Gerçek sunucularda tekrarlanan bir hata örneği şöyledir. Bir asistandan nginx yapılandırmasına bir reverse proxy bloğu eklemesini istersiniz. Asistan /etc/nginx/conf.d/app.conf dosyasını düzenler ve ardından sudo systemctl restart nginx komutunu çalıştırır. Düzenlemede bir yazım hatası olduğu için nginx başlatılamaz ve siz düzeltene kadar site erişilemez hale gelir:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Sohbet üzerinden hatayı düzeltirsiniz. Servise dokunmadan önce yapılandırmayı sudo nginx -t ile test edin, ardından restart yerine reload komutunu kullanarak uygulayın. Bir hafta sonra, farklı bir görevde aynı hata tekrarlanır. Bu ikinci sefer, bir sinyaldir.

Hata hala önünüzdeyken iki şeyi not edin: yazdığınız talep ve verdiğiniz düzeltme; kendi kullandığınız ifadelerle. Bu iki satır, yeteneği oluşturur. Talep, tetikleyicinin neyle eşleşmesi gerektiğini söyler. Düzeltme ise içeriğin tamamıdır.

Anthropic'in kendi yazım kılavuzu bunu ilk sıraya koyar. Asistanı yetenek tanımlamadan temsili görevlerde çalıştırın, nerede başarısız olduğunu kaydedin ve ardından bu hataları düzelten en kısa talimatları yazın. Hatalar teknik şartnamedir; dolayısıyla bir hataya dayandırılamayan bir yetenek, genellikle kimsenin ihtiyaç duymadığı bir yetenektir.

Aynı damıtma işleminin uygulamalı bir örneği için, Ponytail, istenenden fazlasını yeniden yazan bir asistanın tekrarlanan hatasını nasıl bir yeteneğe dönüştürür başlıklı yazıyı, kendi yeteneğinizi yazmadan önce baştan sona okuyabilirsiniz.

Bir yeteneğin anatomisi

Bir yetenek, içinde bir adet zorunlu dosya bulunan bir dizindir.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md, --- işaretleri arasında YAML (Docker Compose dosyalarının kullandığı yapılandırma formatı ile aynı) ile yazılmış birkaç ayardan oluşan bir ön bilgi bloğu ile açılır ve ardından markdown formatındaki talimatlar gelir. Yukarıdaki hata için hazırlanan yeteneğin tamamı aşağıdadır.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Bu dosya yirmi satırdan kısadır ve eksiksiz bir yetenektir. Bölümleri şunlardır:

• name: en fazla 64 karakter, yalnızca küçük harfler, rakamlar ve tire işaretleri; ayrıca claude veya anthropic kelimelerini içeremez. Kişisel veya proje bazlı bir yetenekte bu sadece görünen etikettir. Yazdığınız komut dizin adından gelir, bu nedenle bu yetenek /nginx-config-changes komutuyla çalışır.
• description: yeteneğin ne yaptığı ve ne zaman kullanılacağı, en fazla 1.024 karakter. Bu satır asıl işi yapar ve sonraki bölüm tamamen bununla ilgilidir.
• Gövde: yalnızca yetenek tetiklendiğinde yüklenen talimatlar.
• reference/: aracın talep üzerine okuduğu ek dosyalar. Bunlara SKILL.md içinden bağlantı verin ve bağlantıları tek seviyeli tutun; çünkü başka bir referanslı dosyadan referans verilen bir dosya genellikle sadece kısmen okunur.
• scripts/: aracın okumak yerine çalıştırdığı dosyalar. Yalnızca bunların çıktıları bağlam maliyeti oluşturur, bu yüzden 300 satırlık bir betik düşük maliyetlidir.

Dizini nereye koyduğunuz, yeteneğe kimin erişebileceğini belirler.

• Depo içindeki .claude/skills/<name>/SKILL.md: yalnızca bu proje için geçerlidir ve depoyu klonlayan herkese aktarılır.
• ~/.claude/skills/<name>/SKILL.md: makinenizdeki her proje için geçerlidir, başkaları erişemez.
• <plugin>/skills/<name>/SKILL.md: bir eklenti içinde sunulur, eklentinin etkin olduğu her yerde kullanılabilir.

mkdir -p .claude/skills/nginx-config-changes ile bir tane oluşturun ve dosyayı yazın. Claude Code bu dizinleri izler, bu nedenle mevcut bir yeteneği düzenlemek çalışan oturum içinde hemen etkili olur. Oturum başladığında mevcut olmayan üst düzey bir skills dizini oluşturmak, oturumun yeniden başlatılmasını gerektirir; çünkü oturum başladığında izlenecek bir dizin yoktu.

Description alanı dosyadaki en yüksek etkiye sahip satırdır

Başlangıçta agent, mevcut her yeteneğin name ve description kısımlarını bağlamına yükler. Gövde kısımlarını yüklemez. İsteğiniz ulaştığında, bu yeteneğin ilgili olup olmadığına karar vermenin tek temeli o tek satırdır; bu nedenle belirsiz bir açıklamanın arkasındaki mükemmel bir gövde asla okunmaz.

Açıklamayı üçüncü tekil şahıs ağzından yazın. "Nginx'i güvenli bir şekilde test eder ve yeniden yükler" ifadesi uygundur. "Size nginx konusunda yardımcı olabilirim" ifadesi uygun değildir, çünkü metin sistem istemine (system prompt) enjekte edilir ve burada birinci tekil şahıs kullanımı, modelin kendisinden bahsettiği şeklinde algılanır.

Açıklamada iki unsura yer verin: yeteneğin ne yaptığı ve hangi koşulda uygulandığı. Önemli kullanım durumunu başa koyun, çünkü Claude Code liste girişini 1.536 karakterde keser. Ek tetikleyici ifadeler ve örnek istekler için isteğe bağlı bir when_to_use alanı mevcuttur ve bu alan, aynı karakter sınırı altında açıklamanın sonuna eklenir.

Ardından, gerçekten yazacağınız kelimeleri kullanın. description: Helps with nginx hiçbir şeyle eşleşmez, çünkü kimse "yardımcı olur" ifadesini yazmaz. Yukarıdaki sürüm; /etc/nginx, server block, reverse proxy ve TLS (transport layer security) certificate path ifadelerini içerir; bu, onu tetiklemesi gereken herhangi bir isteğin yaklaşık kelime dağarcığıdır.

İşte bir açıklama için test yöntemi. O tek satırı, gövdeyi daha önce hiç görmemiş birine, yazmak üzere olduğunuz istekle birlikte verin ve yeteneğin uygulanıp uygulanmayacağını sorun. Eğer onlar anlayamıyorsa, model de anlayamaz.

Gövde kısmını küçük tutun, çünkü bağlam içinde kalır

Bir yetenek çağrıldığında, oluşturulan içerik sohbete tek bir mesaj olarak girer ve oturumun geri kalanında orada kalır. Claude Code, sonraki aşamalarda dosyayı yeniden okumaz. Yazdığınız her satır, tek bir yanıt için değil, tüm oturum için ödediğiniz bir maliyettir.

Anthropic, SKILL.md değerini 500 satırın altında tutmanızı ve ayrıntıları ayrı dosyalara taşımanızı önerir. Sıkıştırma işlemi, bu sayının neden rastgele olmadığını gösterir. Sohbet, bağlamı boşaltmak için özetlendiğinde, Claude Code her yeteneğin en son çağrısını yeniden ekler, her birinin yalnızca ilk 5.000 token'ını tutar ve en son çağrılan yetenekten başlayarak toplam 25.000 token'lık bir bütçeyi doldurur. Uzun bir yetenek yarıda kesilir. Birkaç uzun yetenek ise birbirini tamamen devre dışı bırakır.

Bu nedenle, yalnızca modelin halihazırda bilmediği şeyleri yazın. Model, nginx'in ne olduğunu ve reverse proxy'nin ne işe yaradığını bilir. reload yerine restart kullanımına dair kurum içi kuralınızı bilmez; bu dosyanın var olmasının tek nedeni de bu kuraldır.

Eğer yetenek, aracıya paketlenmiş bir betiği çalıştırmasını söylüyorsa, yolu ${CLAUDE_SKILL_DIR} ile belirtin; böylece yetenek nereye kurulursa kurulsun yol çözümlenir. Ayrıca aynı komutu önceden onaylayın ki çalıştırma işlemi bir izin istemiyle durmasın.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

İzin, yeteneği çağıran turu kapsar ve bir sonraki mesajınızı gönderdiğinizde temizlenir; böylece sessizce kalıcı bir izne dönüşmez.

Beceri tetikleyicilerinin doğrulanması

Bir becerinin yüklendiğini izlemek, aracın onu bulduğunu gösterir. Ancak bu, yanıtın değiştiği anlamına gelmez. Her ikisini de kontrol edin ve bunu yeni bir oturumda yapın; çünkü beceriyi yazdığınız oturum, yazım sürecinde söylediğiniz her şeyi belleğinde tutar. Bu artık bağlam, dosyadaki eksiklikleri gizler.

1. Proje içinde claude ile yeni bir oturum başlatın.
2. İsteği, becerinin adını belirtmeden, normal bir çalışma gününde yapacağınız gibi kendi cümlelerinizle yazın.
3. Tetiklenip tetiklenmediğini izleyin. Beceri devreye girmiyorsa açıklamasını düzeltin. Sorun henüz gövde kısmında değildir.
4. Kontrol amacıyla /nginx-config-changes kullanarak beceriyi manuel olarak çağırın. Manuel çağrıldığında doğru, istek üzerine çağrıldığında yanlış sonuç alıyorsanız, sorun talimatlardan ziyade tetikleyici kaynaklıdır.
5. Aynı isteği beceri kapalıyken çalıştırın ve iki yanıtı karşılaştırın. /skills menüsünde beceriyi vurgulayın, durumunu off konumuna getirmek için Space tuşuna basın ve ardından kaydetmek için Enter tuşunu kullanın. Bu işlem .claude/settings.local.json içine bir skillOverrides girdisi yazar; işiniz bittiğinde Space tuşuna tekrar basarak durumu on konumuna geri döndürebilirsiniz.
6. Beceri tarafından tetiklenmemesi gereken birkaç istek yazın ve becerinin bu durumlarda sessiz kaldığından emin olun.

Bu döngüyü otomatikleştirmek için resmi marketten skill-creator eklentisini yükleyin.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Yükleme çıktısı Run /reload-plugins to activate. hatasını verirse, ilgili komutu çalıştırın. Ardından Claude'dan becerinizi ismen değerlendirmesini isteyin. Eklenti, test senaryolarını beceri dizini içindeki evals/evals.json dosyasında saklar ve her senaryoyu kendi alt aracında çalıştırır; böylece her çalıştırma temiz bir bağlamla başlar. Sonrasında becerili ve becerisiz durumları karşılaştıran bir rapor oluşturur. Bu, becerinin maliyetini (token ve süre) ve başarı oranındaki iyileşmeyi gösteren gerçek veridir.

Hata modu: yetenek hiçbir zaman tetiklenmiyor

İsteği yazarsınız, aracı eski hatalı işlemi yapar ve hiçbir yetenek satırı görünmez. Aşağıdaki maddeleri sırasıyla kontrol edin.

• Açıklama kısmında yeteneğin ne yaptığı yazılıdır ancak ne zaman kullanılacağı belirtilmemiştir; bu nedenle isteğinizdeki hiçbir ifade yetenekle eşleşmiyordur.
• Açıklama, yazdığınız kelimeleri içermiyordur. Eğer "nginx" yazıyorsanız, açıklamada mutlaka nginx ifadesi geçmelidir.
• disable-model-invocation: true önbilgi (frontmatter) kısmında ayarlanmıştır. Bu ayar, açıklamayı modelin bağlamından tamamen çıkarır ve yeteneğin yalnızca /name ile sizin tarafınızdan çağrılabilmesini sağlar.
• Önbilgi kısmındaki bir paths glob ifadesi, etkinleştirmeyi eşleşen dosyalarla sınırlar ve üzerinde çalıştığınız dosya bu kapsamın dışındadır.
• Yetenek, başlangıç dizininizin altındaki iç içe geçmiş bir .claude/skills/ dizininde yer alıyordur. Bu dizinler, aracı alt dizin içindeki bir dosyayı okuyana veya düzenleyene kadar yüklenmez; dolayısıyla o ana kadar yetenek hiçbir şekilde kullanılamaz.

Hata modu: yetenek sürekli tetikleniyor

Tam tersi bir sorun, açıklamanın çok geniş olması nedeniyle yeteneğin alakasız işlerde devreye girmesidir. "Sunucu üzerinde çalışırken kullan" ifadesi, bir sunucu deposundaki neredeyse her istekle eşleşir. Bu durumda yetenek, yardımcı olamayacağı görevlerde yüklenir ve oturumun geri kalanında bağlamda kalmaya devam eder.

Açıklamayı gerçekten önemli olan koşula göre daraltın ve kapsadığı dosyaları veya komutları belirtin. Yetenek yalnızca belirli dosyalar için geçerliyse bir paths glob ekleyin. Deploy veya commit gibi yan etkileri olan işlemler için disable-model-invocation: true ayarını yapın ve bunu /name ile kendiniz çağırın; böylece aracı, deploy zamanının geldiğine kendi başına karar vermez.

Hata modu: beceri, kurallar dosyanıza aittir

CLAUDE.md veya AGENTS.md gibi bir kurallar dosyası, her oturumun başında yüklenir ve her göreve uygulanır. Bir beceri gövdesi ise yalnızca beceri tetiklendiğinde yüklenir. Karar verme sürecindeki temel etken sıklıktır. Kullandığınız paket yöneticisi gibi, depodaki her görev için geçerli olan bir olgu, kurallar dosyasına aittir. Yukarıdaki nginx kuralı gibi, görevlerin küçük bir kısmına uygulanan bir prosedür ise, nginx üzerinde düzenleme yapılmayan günlerde hiçbir maliyeti olmayan bir beceriye aittir.

Asıl hata, bunu her iki yere de koymaktır. İki kopya zamanla birbirinden farklılaşır ve aracı yanlış bir işlem yaptığında, hangi kopyayı takip ettiğini anlayamazsınız. Her talimat için tek bir yer belirleyin. Beceriler, MCP sunucuları ve kurallar dosyaları arasındaki sınır, doğru cevabın yeni bir talimat yerine araca yeni bir araç sunan bir MCP (model context protocol) sunucusu olduğu durumlar da dahil olmak üzere, daha karmaşık vakaları ele alır.

Yerini hak ettiğinde paylaşın

Bir haftalık gerçek iş yükünde hayatta kalan bir yetenek, kalıcı hale getirilmeye değerdir. .claude/skills/ içindeki proje yetenekleri kod gibi gözden geçirilir ve depo ile birlikte gelir; bu sayede depoyu klonlayan bir ekip arkadaşınız, herhangi bir kurulum adımı gerekmeksizin düzeltmenize erişebilir. Bir yeteneği kopyala-yapıştır yapmadan depolar arasında taşımak başlı başına bir sorundur ve temsilci yeteneklerini depolar arasında paylaşma konusunda ele alınmıştır.

Taşınabilirlik ile ilgili bir not: Claude Code uzun bir frontmatter alanı listesini kabul eder, ancak Agent Skills standardı yalnızca altı tanesine izin verir: name, description, license, compatibility, metadata ve allowed-tools. Bir yeteneği claude.ai platformuna yüklerken veya Skills API için paketlerken frontmatter içinde başka bir alan bulundurursanız, sistem bu alanı görmezden gelmek yerine doğrudan hata verir:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Bu altı alanın dışına çıkmadığınız sürece aynı dosya hem Claude Code içinde hem de standardı okuyan diğer tüm araçlarda yüklenecektir. Talimatların kendisini, farklı bir modele taşındığında da çalışacak şekilde yazmak ayrı bir iştir ve her modelle çalışan yetenekler yazma konusu bunu kapsamaktadır.

FAQ

Bir SKILL.md dosyası ne kadar uzun olmalıdır?

Dosyayı 500 satırın altında tutun; çoğu faydalı yetenek bundan çok daha kısa olacaktır. Yetenek çağrıldığında içeriği konuşmaya dahil olur ve oturumun geri kalanında orada kalır; bu nedenle her satır tek seferlik değil, sürekli bir maliyet oluşturur. Uzun referans materyallerini yetenek dizinindeki ayrı dosyalara taşıyın ve bunlara SKILL.md üzerinden, bir seviye derinden bağlantı verin; böylece aracı bunları yalnızca ihtiyaç duyduğunda okur. Paketlenmiş betikler okunmak yerine çalıştırılır, bu yüzden yalnızca çıktıları kadar maliyet oluştururlar.

Yeteneğim neden hiç tetiklenmiyor?

Bunun yaygın nedeni açıklamadır; çünkü model karar verirken bağlamdaki tek kısım budur. Açıklamanın yalnızca ne yaptığını değil, ne zaman kullanılacağını da belirttiğinden ve isteklerinizde gerçekten kullandığınız kelimeleri içerdiğinden emin olun. Açıklama doğru görünüyorsa, yeteneği modelden tamamen gizleyen disable-model-invocation: true için ön bilgileri (frontmatter) ve onu üzerinde çalışmadığınız dosyalarla sınırlayan paths glob ifadesini kontrol edin. Başlangıç dizininizin altındaki iç içe geçmiş bir .claude/skills/ dizininde bulunan bir yetenek de başka bir nedendir; bu yetenekler yalnızca aracı o alt dizindeki bir dosyayı okuduğunda veya düzenlediğinde yüklenir.

Bu bir yetenek mi olmalı yoksa kurallar dosyamdaki bir satır mı?

Görevlerinizin kaçı için geçerli olduğunu sorun. Kurallar dosyası her oturumda yüklenir; bu nedenle paket yöneticisi veya dal adlandırma kuralı gibi her görev için geçerli olan gerçekleri içermelidir. Bir yetenek ise yalnızca tetiklendiğinde yüklenir; bu yüzden görevlerin küçük bir kısmında önemli olan bir prosedür için doğru yerdir. Aynı talimatı asla her iki yere de yazmayın; çünkü iki kopya zamanla birbirinden farklılaşır ve aracın hangisini takip ettiğini anlama yeteneğinizi kaybedersiniz.

Bir yeteneğin gerçekten işe yaradığını nasıl anlarım?

Bir temel değerle (baseline) karşılaştırın. Birkaç gerçek istek toplayın, her birini yeteneğin etkin olduğu yeni bir oturumda çalıştırın, ardından aynı istekleri /skills menüsünden yeteneği kapatarak tekrar çalıştırın ve her iki yanıtı yan yana okuyun. Yeni bir oturum önemlidir çünkü yeteneği yazdığınız konuşma hala açıklamalarınızı içerir ve bu da eksik bir dosyanın tam görünmesine neden olur. skill-creator eklentisi bu karşılaştırmayı sizin yerinize yapar ve başarı oranını token maliyetinin yanında raporlar.

Aynı SKILL.md dosyasını farklı bir aracıyla kullanabilir miyim?

Evet, Agent Skills standardının tanımladığı alanlar içinde kaldığınız sürece: name, description, license, compatibility, metadata ve allowed-tools. Claude Code çok daha fazla alanı kabul eder ve diğer araçların çalıştırmadığı shell komutu enjeksiyonu gibi gövde özelliklerini de destekler. Standart dışı bir alana sahip bir yeteneği yüklemek, izin verilen özellikleri listeleyen açık bir hata ile başarısız olur; bu nedenle bir yeteneğin Claude Code içinde mi kalacağına yoksa taşınabilir mi olacağına erkenden karar verin.