Claude Skill Nasıl Yazılır? (SKILL.md Yapısı + Gerçek Örnekler)

Claude Skill'i tek cümleyle nasıl yazacağınızı söyleyelim: bir klasör oluşturun, içine bir SKILL.md dosyası koyun ve Claude'un ne zaman başvuracağını anlayacağı kadar iyi bir description yazın. Mekanizmanın tamamı bu kadar. Skill'inizin çalışıp çalışmayacağına asıl karar veren kısım 1.024 karakter uzunluğunda: Anthropic'in, yüklenmiş 100'den fazla skill arasından sizinkini seçmek için kullandığı description alanı. Techsy community kütüphanesinde üretimde 25 skill çalıştırıyoruz ve başarısız olanlar neredeyse hiçbir zaman talimatlarından dolayı başarısız olmuyor. O tek satırdan başarısız oluyorlar.

Kısa özet

Bir Claude Skill yazmak için: (1) skill'in adını taşıyan bir klasör oluşturun, (2) içine YAML frontmatter'lı (name ve description) ve Markdown talimatlı bir SKILL.md ekleyin, (3) description'ı üçüncü şahıs ağzıyla, net tetikleyici kelimelerle yazın, (4) gövdeyi 500 satırın altında tutup detayları referans dosyalarına itin, (5) güvenmeden önce gerçek görevlerle test edin.

Bir Claude Skill aslında nedir

Bir skill, kökünde bir SKILL.md dosyası bulunan klasördür. Başka hiçbir şeye gerek yok. Bu dosya iki şeyi barındırır: Claude'a skill'i ne zaman kullanacağını söyleyen metadata ve etkinleştirildikten sonra görevi nasıl yapacağını söyleyen talimatlar.

Bunun ucuz kalmasının nedeni, Anthropic'in progressive disclosure (kademeli açığa çıkarma) dediği yükleme modeli. Başlangıçta Claude, yüklü her skill'in yalnızca name ve description alanlarını okur — her biri kabaca 100 token. Description'ınız önündeki görevle eşleştiğinde tam SKILL.md'yi okur, talimatlar işaret ettiğinde de birlikte paketlenmiş referans dosyalarını okur. Yani büyük, detaylı bir skill'i her istekte bunun bedelini ödemeden yayınlayabilirsiniz. Bunların çalışan bir kataloğunu Skills library sayfamızda görebilirsiniz.

Kopyalayabileceğiniz SKILL.md iskeleti

Her skill aynı şekilden başlar. İşte işe yarayan minimal versiyon:

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

İki --- işareti frontmatter'ı sarar. Altında, gövde düz Markdown'dır. 25 skill'imiz boyunca gerçek kullanımda ayakta kalan yapı sıkıcı ve tutarlı: tek satırlık bir başlık, ardından numaralı ya da madde işaretli bir prosedür, ardından varsa şablon ya da örnekler. Nesirle akıllı davranmaya çalıştığımızda Claude onu üstünkörü okudu. Adımlar yazdığımızdaysa onları takip etti. Bitmiş olanları incelemek isterseniz, Techsy community sitesindeki 25 skill açıp kopyalayabileceğiniz, okunabilir SKILL.md dosyalarının hepsi.

Frontmatter kuralları: name ve description

Frontmatter'da tam olarak iki zorunlu alan var ve ikisinin de ezberlemeye değer kesin sınırları var, çünkü Anthropic'in araçları bunları doğruluyor.

Anthropic'in best-practices rehberinden işe yarayan bir kural: skill'leri gerund (-ing) formunda adlandırın, yani processing-pdfs, writing-documentation, analyzing-spreadsheets. Bir listede iyi okunur ve helper ya da utils gibi belirsiz bir isim yerine faaliyeti tarif eder. name alanını klasör adıyla aynı tutun ki ikisi asla birbirinden ayrılmasın. Tüm doğrulama kuralları için Anthropic best-practices dokümanı referans kaynağıdır.

Gerçekten tetikleyen bir description yazmak

Çoğu eğitim içeriğinin atladığı bölüm burası, ama işinizin kullanılıp kullanılmayacağına karar veren de bu. Description sistem promptuna enjekte edilir ve Claude, skill'inizi hiç yükleyip yüklemeyeceğine bunu okuyarak karar verir. Belirsiz bir description'ın arkasındaki kusursuz bir gövde, hiç çalışmayan bir skill demektir.

Farkı yaratan üç kural var:

Üçüncü şahıs ağzıyla yazın. Description, skill'i tarif eder — sizi ya da kullanıcıyı değil. Birinci ya da ikinci şahıs ifadeler seçimi karıştırır.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

Hem neyi hem de ne zamanı belirtin. "Processes data" gibi bir ifade Claude'a hangi görevin eşleştiği konusunda hiçbir şey söylemez. Somut yeteneği ve somut tetikleyicileri adlandırın.

Kullanıcının gerçekten yazacağı kelimeleri kullanın. İnsanlar "PR", "diff" ve "code review" diyorsa, bu terimleri description'a koyun. Claude eşleştirmeyi bunlar üzerinden yapar. Bir skill üzerinde yapabileceğiniz en yüksek etkili tek düzenleme bu, ve bedeli tek bir satır.

Progressive disclosure ve dosya yapısı

Bir skill bir iki ekranı aştığında yapı önem kazanmaya başlar. Anthropic'in yönlendirmesi net: SKILL.md gövdesini 500 satırın altında tutun, daha uzun olan her şeyi gövdenin bağlantı verdiği ayrı referans dosyalarına taşıyın. Claude bu dosyaları gerçekten okuyana kadar bunların hiçbir token maliyeti yoktur.

Büyümüş bir skill şöyle görünür:

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

Bunun çalışmasını sağlayan iki kural var. Birincisi, referansları tek seviye derinlikte tutun: her dosyaya doğrudan SKILL.md'den bağlantı verin, asla dosyadan-dosyaya-dosyaya gitmeyin, çünkü Claude derinlemesine iç içe geçmiş dosyaları yalnızca kısmi bir okumayla önizleyip içeriği kaçırabilir. İkincisi, 100 satırdan uzun her referans dosyasına en başa bir içindekiler tablosu koyun ki kısmi bir okuma bile kapsamın tamamını göstersin. Daha derin modeli isterseniz, Anthropic'in Agent Skills üzerine mühendislik yazısı bunun arkasındaki mimariyi anlatıyor. Skill'iniz araçları orkestrasyona başladığında, MCP kataloğumuz sunucuları bağlamak için işe yarar bir yol arkadaşı.

Serbestlik dereceleri (ve script eklemenin zamanı)

Her talimat aynı katılıkta olmak zorunda değil. Bir adımı ne kadar sıkı script'lediğinizi, o adımın ne kadar kırılgan olduğuyla eşleştirin.

Bir adım deterministikse, Claude'dan her seferinde kod üretmesini istemek yerine bir script gönderin. Paketlenmiş bir script daha güvenilirdir, token tasarrufu sağlar ve çalıştırmalar arasında tutarlı kalır. Script'leri dürüst tutan iki alışkanlık var: hataları Claude'a bırakmak yerine script'in içinde ele almak, ve her sabiti gerekçelendirip açıklanmamış sihirli sayılar bırakmamak. Skill'lerin subagent'lardan ayrıldığı nokta da burası — subagent'lar kendi tool allowlist'i ve sistem promptunu taşır; automations kütüphanemiz subagent örneklerini bir araya getiriyor, iki yaklaşımı Techsy AI automations sayfasında karşılaştırabilirsiniz.

Test edin: eval odaklı skill geliştirme

En iyi skill yazarları dokümantasyondan önce testleri yazar. Anthropic önce evaluation kurmanızı öneriyor: Claude'u skill olmadan üç temsili görevle çalıştırın, tam olarak nerede başarısız olduğunu not edin, sonra yalnızca o başarısızlıkları düzeltecek kadar talimat yazın. Bu sizi hayali sorunları belgelemek yerine gerçek sorunları çözmekte tutar.

Pratik bir döngü:

1. Skill'in ele alması gereken üç gerçek görev seçin.
2. Bunları skill yüklü değilken çalıştırıp neyin bozulduğunu kaydedin.
3. O bozulmaları düzeltecek minimal SKILL.md'yi yazın.
4. Skill yüklüyken tekrar test edin — ideal olarak Claude Haiku, Sonnet ve Opus'un üçünde birden, çünkü Opus'u iyi yönlendiren bir skill Haiku için eksik kalabilir.
5. Claude'un dosyalarda nasıl gezindiğini izleyin. Bir referansı görmezden geliyorsa, bağlantınız yeterince göz önünde değildir. Aynı dosyayı sürekli yeniden okuyorsa, o içerik SKILL.md'ye ait demektir.

Baştan sona bir skill kuran uygulamalı bir anlatım için kardeş sitemizde eksiksiz bir Claude Skills eğitimi var; buradaki yazım kurallarıyla iyi tamamlanıyor. Yapımınızı kurumsal build checklist'lerimize göre de takip edebilirsiniz.

Bir skill'i öldüren yaygın hatalar

Bozuk skill'lerin çoğu kısa bir nedenler listesinden biri yüzünden başarısız olur:

• İnsanlar için yazılmış bir description. Pazarlama metni güzel okunur ama hiçbir şeyi tetiklemez. Modele göre yazın: yetenekler ve tetikleyiciler.
• Çok fazla seçenek. "pypdf, ya da pdfplumber, ya da PyMuPDF, ya da..." Claude'u tereddüde düşürür. Tek bir varsayılan artı tek bir kaçış yolu verin.
• Derinlemesine iç içe geçmiş referanslar. Dosyaya bağlanan dosyaya bağlanan dosyalar kısmi okunur. Her şeyi SKILL.md'den tek adım uzaklıkta tutun.
• Zamana bağlı talimatlar. "Ağustos'tan önce X yap" çürür. Kullanım dışı kalan yönergeleri bunun yerine katlanmış bir "eski kalıplar" notuna koyun.
• Windows tarzı yollar. Her zaman düz eğik çizgi (/) kullanın; ters eğik çizgi () Unix çalıştırıcılarında bozulur.
• Tutarsız terminoloji. Bir şey için tek bir kelime seçin ("field", "field/box/element/control" değil) ve baştan sona onu kullanın.

Altısının da arkasındaki kalıp aynı: bir skill, belirsizliğe hiç sabrı olmayan çok yetenekli bir okuyucu için yazılmış bir talimat setidir. Somut olanı söyleyin, bir kez.

Yazar hakkında

Mert Batur Gurbuz, Techsy'nin Kurucu Ortağı'dır, University of Birmingham mezunu. Techsy ekibiyle birlikte B2B müşteriler için AI ajanları, otomasyon sistemleri ve voice/SDR pipeline'ları inşa ediyor, bu rehber boyunca referans verilen 25 skill'lik kütüphaneyi de sürdürüyor. LinkedIn üzerinden bağlantı kurabilirsiniz. Daha fazla builder rehberi TECHSY.community blogunda yer alıyor.

Sıkça Sorulan Sorular

Claude skill dosyaları nerede tutulur?

Bir skill, içinde bir SKILL.md dosyası bulunan klasördür. Claude Code'da kişisel skill'ler ~/.claude/skills/{skill-name}/ altında, proje skill'leri ise .claude/skills/{skill-name}/ altında yer alır. API'de ve claude.ai'de skill klasörünü siz yüklersiniz. Klasör adı frontmatter'daki name alanıyla eşleşmelidir.

Skill adı klasör adıyla aynı olmak zorunda mı?

Evet, ikisini aynı tutun. name alanı 64 karakter ya da daha kısa olmalı, yalnızca küçük harf, rakam ve tire içermeli, "anthropic" ve "claude" ayrılmış kelimelerinden kaçınmalıdır. Klasör adıyla eşleşmesi kaymayı önler ve skill'i konuşmada ve dokümantasyonda referans vermeyi kolaylaştırır.

Bir SKILL.md ne kadar uzun olabilir?

Güvenilir performans için SKILL.md gövdesini 500 satırın altında tutun. Kesin bir token sınırı yoktur, çünkü referans dosyaları ve script'ler okunana kadar hiçbir maliyet oluşturmaz, ama şişkin bir ana dosya context penceresindeki her şeyle yarışır. 500 satıra yaklaştığınızda, detayı doğrudan SKILL.md'den bağlantı verilen referans dosyalarına bölün.

Skill'im neden tetiklenmiyor?

Neredeyse her zaman description yüzünden. Claude, görevi description alanıyla eşleştirerek skill seçer; sizinki belirsizse ya da birinci şahısla yazılmışsa hiçbir zaman etkinleşmez. Üçüncü şahısla yeniden yazın, skill'in ne yaptığını ve ne zaman kullanılacağını belirtin, o görev için kullanıcının tam olarak yazacağı kelimeleri ekleyin.

Skill, subagent ve MCP sunucusu arasındaki fark nedir?

Skill, Claude'un ilgili olduğunda yüklediği paketlenmiş talimatlardır. Subagent, devredilen bir görevi ele alan, kendi tool allowlist'i ve sistem promptu olan ayrı bir ajandır. MCP sunucusu, Model Context Protocol üzerinden dış araçları ve verileri açığa çıkarır. Skill'ler işi nasıl yapacağınızı tarif eder; MCP sunucuları ise üzerinde ne işlem yapacağınızı sağlar.

Bir Claude skill kod çalıştırabilir mi?

Evet. Skill'ler, Claude'un context'e okumak yerine tool olarak çalıştırdığı yürütülebilir script'leri paketleyebilir; bu, validation ya da dosya dönüştürme gibi deterministik işler için daha ucuz ve daha güvenilirdir. Niyeti talimatlarınızda açıkça belirtin: yürütme için "bu script'i çalıştır" deyin, referans materyali olduğunda "bu script'e bak" deyin.

Skill'ler hem API'de hem claude.ai'de çalışır mı?

Evet, ama runtime farklıdır. claude.ai'de kod çalıştırma ortamı npm ve PyPI'dan paket kurabilirken, Claude API'nin ne ağ erişimi ne de çalışma zamanında paket kurulumu vardır. Gerekli paketleri SKILL.md'nizde listeleyin ve onlara güvenmeden önce hedef ortamda mevcut olduklarını doğrulayın.

Claude aynı anda kaç skill yükleyebilir?

Çok sayıda, çünkü başlangıçta context'te yalnızca her skill'in name ve description'ı yer alır — her biri kabaca 100 token. Description'ın bu kadar önemli olmasının nedeni de bu: Claude 100'den fazla skill arasından seçim yapıyor olabilir, ve sizinkini doğru seçmesini sağlayan şey kesin bir description'dır. Tam gövde yalnızca skill seçildiğinde yüklenir.