Skill yapısı: yapay zekâya iş tarifi vermek

Claude'da skill yapısı, klasör ağacı, tetikleyici sözcükler ve tutarlı çıktı için iyi bir iş akışının nasıl yazılacağı. Öğretmenler ve vibe coding yapanlar için bir rehber.

Yapay zekâyla düzenli çalışan herkes aynı şeyle karşılaşır: Her yeni sohbette aynı şeyleri baştan anlatırsın. Hangi formatı istediğini, hangi kurallara uyulacağını, çıktının nasıl görünmesi gerektiğini. Üstelik her seferinde farklı bir sonuç alırsın. Bazı durumlarda çıktı ürünlerinin birbirleriyle tutarlılığı önemlidir. Peki bu tutarlılığı nasıl sağlarız?

Skill bu sorunun çözümü. En kısa tanımıyla: Yapay zekâya her seferinde baştan anlatmak yerine, bir kez yazıp tekrar tekrar kullandığın tarif.

Skill kullanmanın iki temel nedeni var: tutarlılık ve hız. İyi yazılmış bir skill ile haftalık bir ders materyali her hafta aynı yapıda, aynı tipografiyle ve aynı kontrol adımlarından geçerek çıkar. Yapay zekâ neyi nasıl yapması gerektiğini önceden bilir. Bunun için tek cümle yazmak yeterli olur.

Skill nasıl çalışır?

Bir skill, en az bir SKILL.md dosyası içeren bir klasördür. Dosyanın en üstünde iki bilgi bulunur:

---
name: haftalik-materyal
description: Özel ders öğrencileri için haftalık çalışma kâğıdı (PDF) hazırlar.
  "Materyal hazırla", "çalışma kâğıdı", "worksheet", "haftalık ödev"
  gibi isteklerde ya da bir öğrenci adı ile bir konu birlikte geçtiğinde kullan.
---

Claude başlangıçta yalnızca bu adı ve açıklamayı görür. İsteğin açıklamaya uyduğunu anladığında SKILL.md dosyasının tamamını okur. Klasördeki diğer dosyaları da ancak ihtiyaç duyduğunda açar. Böylece onlarca skill yüklü olsa bile Claude’un dikkati dağılmaz.

Claude ile belirli bir iş akışını sohbet sırasında skill olarak kaydettirebilirsin. Eğer manuel olarak oluşturmak istersen, Claude uygulamasında skill’i zip dosyası olarak yükleyebilirsin. Claude Code’da ise klasörü ~/.claude/skills/ altına ya da projenin .claude/skills/ klasörüne koyman yeterli.

Tetikleyici sözcükler

Bir skill’in işe yaraması için önce doğru anda devreye girmesi gerekir. Bunu belirleyen şey description alanıdır. Claude, isteğini bu açıklamayla karşılaştırarak hangi skill’i kullanacağına karar verir. Bu yüzden açıklama, skill’in ne yaptığını anlatmanın yanında hangi sözcüklerle istendiğini de söylemelidir.

İyi bir açıklamada şunlar bulunur:

  • İşin adı ve eş anlamlıları: “çalışma kâğıdı”, “worksheet”, “materyal”, “ödev”. Aynı işi farklı günlerde farklı sözcüklerle isteyebilirsin.
  • İki dil: Hem Türkçe hem İngilizce çalışıyorsan iki dildeki karşılıkları da yaz.
  • Durumlar: Sözcük geçmese bile skill’i gerektiren durumlar. Örneğin “bir öğrenci adı ile bir konu birlikte geçtiğinde”.
  • Dosya türleri: Çıktı ya da girdi belirli bir türse (.pdf, .docx) bunu belirt.
  • Sınırlar: Benzer işler için birden fazla skill’in varsa hangisinin ne zaman kullanılmayacağını da yaz: “Kurum öğrencileri için kullanma; onlar için kurum-materyal skill’i var.”

Açıklama çok dar olursa skill gerektiği hâlde çalışmaz; çok geniş olursa ilgisiz isteklerde devreye girer. Yazdıktan sonra aynı işi birkaç farklı biçimde isteyerek dene: Skill her seferinde açılıyor mu, ilgisiz bir istekte sessiz kalıyor mu?

Çoğu zaman SKILL.md yetmez

İlk skill’ler genellikle tek bir uzun metin dosyasıdır. Bu, basit işler için işe yarar. Ama gerçek bir iş akışı metinden fazlasına ihtiyaç duyar: şablonlar, fontlar, kontrol listeleri, referans bilgiler. Skill’i zip olarak paketlemenin anlamı da burada ortaya çıkar: Talimat ile birlikte işin bütün malzemesi tek klasörde taşınır.

Örnek skill’in klasör ağacı şöyle olabilir:

haftalik-materyal/
├── SKILL.md                  iş akışı ve kurallar
├── references/
│   ├── tasarim-anayasasi.md  sayfa düzeni ve tipografi
│   ├── konu-plani.md         haftalara göre konu sırası
│   └── seviyeler.md          seviyelere göre içerik ölçütleri
├── scripts/
│   ├── pdf-uret.py           PDF üretim betiği
│   └── yerlesim-kontrol.py   taşma ve boşluk kontrolü
├── assets/
│   └── logo-siyah.svg        materyalde kullanılan logo
├── fonts/
│   └── ...                   materyalde kullanılan fontlar
└── examples/
    └── ornek-materyal.pdf    onaylanmış referans çıktı

SKILL.md burada bir yönetici gibi çalışır: Ne zaman hangi dosyanın okunacağını ve hangi betiğin çalıştırılacağını söyler. Fontlar pakette olduğu için PDF her ortamda aynı görünür. Kontrol betiği sayesinde taşan bir tablo ya da boş kalan bir sayfa, materyal öğretmene ulaşmadan yakalanır.

Her skill bu kadar kalabalık olmak zorunda değil. Örneğin bir ders planı skill’i yalnızca SKILL.md ile iki referans dosyasından (müfredat kazanımları ve plan şablonu) oluşabilir. Ölçüt basit: Yapay zekâ işi yaparken neye ihtiyaç duyacaksa klasörde olmalı.

Referans çıktı: anlatmak yerine göstermek

Bir çıktının nasıl görünmesi gerektiğini kelimelerle tarif etmek zordur. “Başlıklar sade olsun, boşluklar dengeli olsun” gibi bir cümleyi yapay zekâ her seferinde biraz farklı yorumlar. Onaylanmış, bitmiş bir örneği skill’in içine koymak ise bu yorum payını büyük ölçüde ortadan kaldırır.

Referans çıktı, “tam olarak böyle olmalı” dediğin örnektir: daha önce ürettiğin ve beğendiğin bir PDF, bir ders planı ya da bir sayfa. Örnek skill’de bu, examples/ornek-materyal.pdf dosyası.

Referans çıktıyla çalışırken üç noktaya dikkat etmek gerekir:

  • Neyin taklit edileceğini yaz. Yapay zekâ örneği fazla harfiyen kopyalayabilir; konuyu, cümleleri, hatta sayıları da alabilir. SKILL.md içinde açıkça belirt: “Örnekteki yapıyı, tipografiyi ve boşlukları kullan; içeriği her seferinde yeniden üret.”
  • Örnek tek başına yetmez, kontrolle birleştir. Hiçbir yapay zekâ her seferinde kusursuz sonuç garanti etmez. Kusursuza en yakın sonucu üç katman birlikte verir: Referans çıktı hedefi gösterir, kurallar sınırları çizer, kontrol adımı (bir betik ya da bir kontrol listesi) sapmayı yakalar.
  • Örneği güncel tut. Kuralları değiştirdiğinde referans çıktıyı da yenile. Kural bir şey, örnek başka bir şey söylerse yapay zekâ genellikle örneğe uyar.

İyi bir skill nasıl yazılır?

1. İş akışını adım adım yaz

“Güzel bir materyal hazırla” bir talimat değildir. Adımları sırayla ve net yaz: önce hangi bilgiyi topla, sonra neyi üret, neyi kontrol et, nereye kaydet. Örnek skill için bu şöyle olabilir:

  1. Öğrencinin seviyesini ve bu haftanın konusunu belirle; bilinmiyorsa sor.
  2. Konu planından bir önceki haftayı kontrol et.
  3. İçeriği yaz.
  4. PDF’i üret.
  5. Yerleşim kontrolünü çalıştır; sorun varsa düzelt ve yeniden üret.
  6. Cevap anahtarını ayrı bir dosya olarak hazırla.

2. İhtiyaç duyacağı her şeyi pakete koy

Üretim betiği, şablonlar, fontlar, örnek dosyalar. Yapay zekânın tahmin etmesi gereken her şey, tutarsızlığın kaynağıdır. Pakette olan bir şeyi tahmin etmesine gerek kalmaz.

3. Uzun kuralları ayrı dosyalara böl

Her seferinde gerekmeyen bilgiyi (müfredat listesi, tasarım kuralları) references/ altına taşı. SKILL.md kısa ve okunur kalsın.

4. Karar noktalarını da yaz

İyi bir iş akışı yalnızca üretimi değil, araya giren kararları da tanımlar. Örneğin materyal bittikten sonra Claude’un öğretmene “Ders sırasında hatırlatma olarak kullanabileceğin bir whiteboard ister misin?” diye sorması gerektiğini skill’e yazabilirsin. Böylece sen hatırlamasan bile iş akışı hatırlar.

5. Belirsizlikte sormasını söyle

“Emin değilsen tahmin etme, sor” kuralı, skill’in en değerli satırlarından biridir. Yanlış bir varsayımla üretilmiş materyali düzeltmek, baştan sormaktan her zaman daha uzun sürer.

6. Yönergeyi kendi içinde tutarlı tut

Skill’in çıktısı, yönergesi kadar tutarlıdır. Bir dosyada “başlıklar kalın”, başka bir dosyada “başlıklar normal” yazıyorsa yapay zekâ her seferinde farklı birini seçer ve çıktı da her seferinde değişir. Tutarsız çıktının en sık nedeni yapay zekâ değil, birbiriyle çelişen talimatlardır.

Bunun için:

  • Her kuralı tek bir yerde yaz; başka dosyalarda tekrarlama, oraya yönlendir.
  • Aynı şey için hep aynı terimi kullan. Bir yerde “etkinlik”, başka yerde “alıştırma” dersen yapay zekâ bunları iki ayrı şey sanabilir.
  • Zorunlu olanı ve tercihi ayır: “her zaman” ile “mümkünse” aynı ağırlıkta değildir.
  • Bir kuralı değiştirdiğinde eski hâlini her yerden temizle ve SKILL.md başına son güncelleme tarihini yaz.

Yalnızca Claude’da mı çalışır?

Hayır. Skill yapısını Anthropic geliştirdi, ama Aralık 2025’te açık standart olarak yayımladı. Bugün OpenAI Codex, Gemini CLI, GitHub Copilot ve Cursor gibi pek çok araç aynı SKILL.md biçimini okuyabiliyor. Araçlar skill’leri farklı klasörlerde arıyor, ama dosyanın içeriği aynı kalıyor. Yani bir kez iyi yazdığın skill, başka bir araca geçtiğinde de büyük ölçüde işe yarar.

Nereden başlamalı?

En sık tekrarladığın işi seç. Son birkaç seferde yapay zekâya ne anlattığını bir dosyada topla, adımları sıraya koy, kullandığın şablonları ve beğendiğin bir çıktıyı klasöre ekle. İlk sürüm kusursuz olmak zorunda değil; her kullanımda neyin eksik kaldığını gördükçe skill de gelişir.

Hızlıca başlamak için teknik bilgiye ihtiyacın yok. Çoğu durumda skill’i oluşturmasını yapay zekâdan direkt olarak da isteyebilirsin.

Kaynaklar

Okumaya devam et