Skills

Aynı talimatı üçüncü kez sohbete yapıştırıyorsanız, o iş skill olmak istiyordur. Claude Code dokümanı skill'i tam bu durumlar için öneriyor: aynı talimatı, kontrol listesini ya da çok adımlı prosedürü tekrar tekrar yapıştırıyorsanız veya CLAUDE.md'nizdeki bir bölüm olgu olmaktan çıkıp prosedüre dönüştüyse.¹

Skill nedir?

Skill, içinde SKILL.md dosyası olan bir klasördür. Dosyanın başında name ve description, altında ajanın izleyeceği talimatlar bulunur. İsterseniz yanına script ve referans dosyaları koyarsınız. Biçim açık bir standarttır (Agent Skills) ve birden fazla araçta çalışır.¹

Kural dosyasından farkı yüklenme zamanı: AGENTS.md her oturumda bağlamdadır, skill'in ise yalnızca açıklaması bağlamda durur, gövdesi skill kullanıldığında yüklenir.¹ Uzun referans malzeme, kullanılana kadar neredeyse maliyetsizdir.

Tekrar eden işi skill'e dönüştürün

Sıfırdan yazmak yerine önce işi bir kez normal şekilde yaptırın. Anthropic'in önerdiği yöntem bu: görevi ajanla normal istekle bitirin, bu sırada verdiğiniz bağlama (tercihleriniz, kurallarınız, izlediğiniz adımlar) dikkat edin, sonra aynı ajana "bu işte verdiğim bağlamı bir skill'e dönüştür" deyin. Çıkan skill'i yeni bir konuşmada gerçek bir işte deneyin, ajanın takıldığı yeri not edip skill'i düzeltin.²

Örnek bir frontend skill'i (.claude/skills/new-component/SKILL.md):

---
name: new-component
description: Projeye yeni React bileşeni ekler. Kullanıcı "yeni bileşen" veya "component ekle" dediğinde ya da src/components altına yeni dosya gerektiğinde kullan.
---

1. `src/components/<Ad>/` klasörü aç: `<Ad>.tsx`, `<Ad>.test.tsx`, `index.ts`.
2. `src/components/Button/` bileşenini örnek al, aynı yapıyı izle.
3. Props'u `interface` ile yaz, named export kullan.
4. Test dosyasına en az bir render ve bir etkileşim testi ekle.
5. `pnpm lint && pnpm tsc --noEmit && pnpm test:run` çalıştır. Hepsi geçmeden işi bitmiş sayma.

İyi bir skill için beş kural:

• Yalnızca ajanın bilmediğini yazın. Yapay zeka React'i zaten biliyor, projenize özgü olanı yazın. Her paragraf için "bu, token maliyetini hak ediyor mu?" diye sorun. SKILL.md 500 satırın altında kalsın, fazlasını ayrı dosyalara bölüp SKILL.md'den doğrudan bağlayın.²

• description'a hem "ne yapar" hem "ne zaman" yazın. Ajan skill'i yalnızca description'a bakarak seçer. "Belgelerle ilgilenir" gibi muğlak bir ifade işe yaramaz. Metni üçüncü şahıs yazın ("ekler"), "ekleyebilirim" yazmayın.² Claude Code listede description metnini en fazla 1.536 karakter gösterir, önemli kullanım durumunu başa koyun.¹

• Katılığı işe göre seçin. Kod incelemesi gibi bağlama bağlı işlerde genel yönerge yeter. Veritabanı migration'ı gibi kırılgan işlerde tam komutu yazın ve "değiştirme" deyin. Seçenek sıralamayın, tek bir varsayılan verin ("Vitest kullan; E2E gerekiyorsa Playwright").²

• Kontrol döngüsü ekleyin. "Doğrula, hata varsa düzelt, tekrar doğrula" kalıbı çıktı kalitesini artırır. Frontend'de bu lint, tip kontrolü ve testtir.²

• Tarihe bağlı bilgi yazmayın. "Şu tarihten önce eski yöntemi kullan" yerine güncel yöntemi yazın, eskisini ayrı bir "eski kalıplar" bölümüne koyun.²

Nereye konur?

Cursor .claude/skills/ klasörünü de okur, yani iki aracı birlikte kullanıyorsanız skill'i .claude/skills/ altına koymak yeter.³ Proje skill'ini commit edin, ekip de kullanır.¹ Cursor'da name alanı klasör adıyla aynı olmalı (küçük harf, rakam, tire).³ Eskiden .claude/commands/ içine yazdığınız özel komutlar da artık skill ile aynı şeydir.¹ İskeleti elle kurmak zorunda değilsiniz: Cursor'da /create-skill, Claude Code'da skill-creator eklentisi var.¹³

Hazır frontend skill'leri

Neden gerekli? Anthropic'in frontend yazısı sorunu adlandırıyor: talimat vermezseniz model, eğitim verisinin ortasındaki güvenli seçimlere (Inter yazı tipi, beyaz üstüne mor gradyan, az animasyon) yaslanır. Bunu sistem prompt'una yazarsanız her konuşma, alakasız işlerde bile tasarım talimatı taşır. Skill ise yalnızca arayüz işinde yüklenir.⁴

Emil Kowalski aynı sorunu animasyon tarafında çözüyor: ajanlar "iyi hissettiren"in ne olduğunu bilmiyor, o yüzden arayüzün her yönü için bir skill dosyası yazıyor.⁵ Yöntemi kendi skill'iniz için de işe yarar: "güzel animasyon yap" yerine karar kuralları yazın. Örneğin giren eleman ease-out kullanır, UI animasyonları 300 ms altında kalır, bir eleman scale(0) yerine scale(0.95)'ten başlar. Her kuralın nedenini yazın, karar noktalarını tablo ya da akış şemasına çevirin ki ajan tahmin etmesin.⁵

npx skills add komutu Claude Code, Cursor ve diğer araçlara kurulum yapar.⁸ Matt Pocock skill'lerin küçük, uyarlanabilir ve birleştirilebilir olmasını savunuyor, yani süreci sahiplenen büyük çerçeveler yerine kendi hâlinize getirmenizi istiyor.⁹

Skill işe yarıyor mu? Tek denemeyle karar vermeyin. Anthropic'e göre önce ajanın skill'siz nerede takıldığını görün, skill'i yalnızca o boşluğu kapatacak kadar yazın.² Sonra aynı isteği yeni bir konuşmada skill'li ve skill'siz çalıştırıp karşılaştırın.¹ Claude Code'daki skill-creator eklentisi bu karşılaştırmayı otomatikleştiriyor.¹

Kendin dene

1. Son haftada ajana üç kez aynı şekilde anlattığınız bir işi seçin (örneğin yeni bileşen ekleme). Normal istekle yaptırın, bitince "bu işte verdiğim bağlamı bir skill'e dönüştür" deyin.

2. Çıkan SKILL.md'yi kısaltın: Claude'un zaten bildiği her şeyi silin, description'a "ne zaman" cümlesini ekleyin.

3. Yeni bir konuşmada aynı işi skill'li ve skill'siz isteyin, kaç düzeltme turu gerektiğini karşılaştırın.

4. Hazır bir skill kurun (örneğin react-best-practices). Kurmadan önce SKILL.md'sini okuyun, sonra bir bileşene "performans açısından incele" dedirtin.