Skills: Ajanınıza hazır bir yetenek nasıl takılır

Tekrar ettiğiniz bir istek vardır: değişiklikleri gözden geçir, bu dosyaları kontrol et, şöyle biçimlendir, buraya dokunma. Her seferinde prosedürü baştan ve biraz farklı anlatıyorsunuz.

Sonuç da ifadeyle birlikte değişip durur. Bugün harika çıktı, yarın koşulların yarısını unuttunuz ve ajan dürüstçe duyduğunu yaptı.

Bunun çaresi ajanın hafızası değil, talimat içeren bir klasördür. Skill, bir kez yazılmış ve Claude Code'un kendiliğinden ya da sizin komutunuzla devreye alabildiği bir prosedürdür. Bu klasörün nerede durduğunu, skill'in yerine oturduğundan nasıl emin olacağınızı ve ilk çalıştırmadan önce neyi kontrol etmeniz gerektiğini görelim.

Skill nedir

Dosyalara ve alanlara geçmeden önce konuyu sezgiyle yakalayalım.

Bir marangoz hayal edin. Alışık olduğu çalışma düzenini bir kez yazıya dökmüş, notlar, şablonlar ve tezgâh için bir program hazırlamış. Artık kısaca söylemesi yeterli: "her yeri topla, matkap ucunu bile, sonra kedi sandalyesi - CNC şablonunu çalıştır". Çalıştırdı - ve iş başladı.

Yazıya dökülmüş prosedür bütün işi bir arada tutar:

• Sizin kurallarınıza göre düzen kurar. Tezgâhı toplar, aletleri yerleştirir - her seferinde aynı şekilde, tam alıştığınız gibi.
• Yazılı sınırlara uyar. Testere hâlâ dönüyorsa elini uzatmaz. İşin güvenli kısmını hemen, gereksiz soru sormadan yapar.
• Gerektiğinde notlara bakar. Matkap ucunu bilemek mi gerekiyor - bileme kuralını açar. Onu önceden aklında tutmaz, ihtiyaç anında çıkarır.
• Farklı işler için şablon saklar. Masadan sandalyeye geçtik - hazır hazırlık şemasını alır.
• Karmaşık işi tek komutla başlatır. Tekrarlanan kesimlerin programı zaten elinin altında. Şunu söylemek yeterli: "Kedi sandalyesi şablonunu bul ve CNC'ye gönder" - tezgâh boşluklara ve işlem sırasına uyar.

Skill da aynı mantıkla kurulur. Ajanın elindeki bir alet daha değil, paketlenmiş bir prosedürdür. Ana talimat sırayı ve sınırları tutar, başvuru dosyaları ihtiyaç anında ayrıntı verir, şablonlar hazır iskeletleri saklar, script'ler de tekrarlanan mekanik işi çalıştırır. Bir kez tarif edersiniz - sonrasında sadece çağırırsınız.

Skill formatı tek başına hiçbir şeyi yalıtmaz. Talimat işi görsel düzenlemeyle sınırlayabilir, ama CSS ile mantık arasında teknik bir duvar yoktur. İyi bir skill çalışma alanını açıkça belirtir; çalıştırdıktan sonra değişen dosyalara bakar, sayfanın davranışını kontrol edersiniz. "Çalışıyor" ile "güzel görünüyor" ayrı katmanlardır; güvenceyi format değil, kontrol verir.

Skill nerede yaşar

Burada buluttaki bir sihir yok. Skill diskteki bir klasördür, hem de doğrudan kendi projenizin içinde:

.claude/skills/web-design/SKILL.md

Yolu parça parça okuyalım: servis klasörü .claude, onun içinde skills, onun içinde skill'in kendi klasörü (adını siz koyarsınız), onun içinde de SKILL.md dosyası. Sıradan bir metin dosyası, herhangi bir editörle açılır.

Projedeki ve ev klasöründeki skill'lerde klasörün adı, eğik çizgiyle yazılan komutun adı olur; tabii dosyanın kendisi başka bir ad belirlemiyorsa (bunu aşağıda ele alacağız). O yüzden adı en baştan sohbette nasıl görüneceğini düşünerek seçin.

Şimdi akıllardaki en yaygın resme bir düzeltme: skill tek bir dosya değil, bir klasördür. SKILL.md'nin yanında başka her şey durabilir.

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # ana dosya: açıklama ve talimat
        ├── palettes.md   # başvuru dosyası, ajan gerekirse açar
        └── scripts/
            └── check.py  # çalıştırılabilen script

Otomatik seçim sırasında ajanın önünde skill'in tamamı değil, yalnızca adı ve kısa açıklaması vardır. SKILL.md çalıştırma anında yüklenir, yanındaki başvuru dosyaları ise gerektiğinde. Bu yüzden uzun bir not bağlamı önceden doldurmaz.

Günlük yerel çalışmada skill'lerin üç kaynağı önemlidir:

~ işareti kullanıcının ev klasörü anlamına gelir. Komutlarda olduğu gibi bırakılır; klasörü elle açıyorsanız kendi ev dizininize gidin.

İlk iki konum arasındaki fark basit ve bunu baştan netleştirmekte fayda var.

Klasörü projeye koydunuz - skill yalnızca bu projede çalışır. Yandaki projeyi açtınız, orada yok.

Ev klasöründeki skill tüm projelerde kullanılabilir. Ortak bir prosedür için bu kullanışlıdır, ama beklemediğiniz bir yerde de devreye girebilir. Genel olanı eve koyun, projeye özgü olanı projede bırakın.

Claude Code ayrı bir eğitim profiliyle, ~/.claude-codegym/ ile başlatıldıysa, kişisel skill'ler o profilin skills/ klasöründe durur. Projedeki .claude/skills/ yolu profile göre değişmez.

Skill'in ne zaman devreye gireceğine description karar verir

Tanıdık bir durum: klasörü koydunuz, dosya yerinde, ama ajan tıpkı eskisi gibi davranıyor. Hiçbir şey bozuk değil - ajan sadece bu skill'in buraya uyduğunu anlamadı.

Seçim anında ajanın elinde ne olduğuna bakın. Skill'in içeriğini henüz okumadı: yüklenmiş olan yalnızca adlar ve açıklamalar listesi. Demek ki karar açıklamaya göre veriliyor, başka hiçbir şeye göre değil.

Proje için en küçük bir skill'i baştan sona kuralım. Adı web-design - klasörün adı bu, /web-design komutu da buradan gelir. Burada dosyanın içine ad yazmıyoruz, klasör onu zaten belirledi:

.claude/skills/web-design/SKILL.md

İçeriği de şu kadar, başka bir şeye gerek yok:

---
description: Web arayüzünü toparlar - modern CSS, yumuşak geçişler,
  uyumlu bir palet. Güzel ya da şık yapılması istendiğinde kullan.
---

# Web tasarımı

Yumuşak gölgeler, akıcı geçişler ve özenli bir tipografi kullan.
Paleti uyumlu tut, animasyonları üzerine gelme ve öğelerin belirmesi için kullan.

Üstte, üç tireden oluşan iki satırın arasında servis bloğu, altta talimatın düz metni. Zorunlu alan yok, ama description her zaman yazılmalı: o olmadan ajan skill'in amacını içeriğin ilk paragrafından tahmin eder, bu da piyangodur.

İyi bir açıklama iki soruyu yanıtlar: skill ne yapar ve ne zaman kullanılır. Hem de isteklerinizi gerçekten yazdığınız kelimelerle.

# sessiz kalır: ne zaman kullanılacağı belli değil
description: Tasarım konusunda yardımcı olur

# devreye girer: hem ne yaptığı hem de ne zaman kullanılacağı yazılı
description: Arayüzü toparlar - CSS, tipografi, palet.
  Güzel, şık yapılması ya da sayfa düzeninin düzeltilmesi istendiğinde kullan.

Açıklama, skill'in kendiliğinden ne zaman devreye gireceğini belirler. Ama tek giriş bu değil: skill'in bir adı var ve onunla elle çağrılabilir. /web-design yazdınız - açıklamanın artık hiçbir önemi yok, dosya okunur ve uygulanır.

Hazır skill'lerde sık sık name alanına rastlanır. Projedeki ve ev klasöründeki skill'lerde bu alan, / menüsünde görünen komutu belirler: deploy-staging klasöründe duran ve name: deploy içeren bir skill /deploy olarak çağrılır. Klasörün adı da çalışmaya devam eder. Eklentide ise name, komutun eklenti adından sonraki son kısmını belirleyebilir.

Yani çalıştırmanın iki yolu var, sonrası ise aynı.

Sol dal otomatik: istek açıklamayla eşleşti, ajan skill'i aldı. Sağdaki elle: /web-design yazdınız ve skill, açıklamadan bağımsız olarak çalıştı.

Skill'ler, yerleşik komutlarla aynı / menüsüne düşer. .claude/commands/deploy.md dosyası ile .claude/skills/deploy/SKILL.md skill'i aynı /deploy komutunu oluşturur; ikisi birden varsa skill kazanır.

Kurun ve kontrol edin

Klasörü koydunuz. Ajanın onu gerçekten gördüğünü, dosyanın diskte öylece durmadığını nasıl anlarsınız?

/skills

Komut skill listesini açar ve her birinin kaynağını gösterir. Birkaç harf yazın - liste süzülür. Klasörünüzün adını ve on durumunu gördünüz mü - Claude Code skill'i görüyor ve çalıştırılmasına izin veriyor.

Ad, kaynak ve on durumu, skill'in kullanılabilir olduğunu doğrular

Claude Code genellikle yeni ya da değiştirilmiş SKILL.md'yi anında fark eder. Ad listede yoksa sırayla şunları deneyin:

Skill listede var ama kendiliğinden devreye girmiyor mu? Burada yeniden yüklemenin bir faydası yok. description alanını ve disable-model-invocation: true alanını kontrol edin - bu alan yalnızca elle çalıştırmaya izin verir. İsteğinizi farklı ifade edin ya da skill'i adıyla çağırın. Elle çağrı çalışıyorsa kurulum sağlam demektir.

Güvenmeden önce neyi kontrol etmeli

Burada heyecanı biraz frenlemek gerekecek. Skill, takıp çıkarabileceğiniz bir görünüm teması ya da resim değildir. Ajanınızın, sizin projenizde uygulayacağı talimatlardır.

Yalnızca ana dosyayı değil, bütün klasörü kontrol etmek gerekir. Dört şeyle başlayın:

• açıklama - skill'den beklediğinizle örtüşüyor mu, gereğinden geniş durumlarda devreye girmiyor mu;
• içerik ve oradaki bağlantılar - skill ne yapılmasını istiyor, yanındaki hangi dosyaların açılmasını istiyor;
• scripts/ klasörü, varsa - orada hangi komutlar çalışıyor, hangi dosyalara ve ağ adreslerine dokunuyorlar;
• allowed-tools alanı - skill hangi araçların ayrıca sorulmadan kullanılmasına önceden izin veriyor.

---
name: pre-commit-style
description: Commit öncesinde projeyi ortak stile getirir
allowed-tools: Read, Write, Edit, Glob
---

Burada allowed-tools bir iş planı tarif etmez ve ajanın tüm yeteneklerini de sınırlamaz. Alan, listelenen araçları yalnızca skill'in çağrıldığı tur için önceden onaylar. Adların anlamı basit:

• Read - dosyaları okumak;
• Write - yeni dosyalar oluşturmak ve mevcut dosyaların üzerine baştan sona yazmak;
• Edit - mevcut bir dosyanın içinde düzeltme yapmak;
• Glob - dosyaları desene göre aramak, yani projede dolaşıp içinde neler olduğuna bakmak.

İlki ve sonuncusu yalnızca bakar. Write ve Edit ise dosyaları değiştirebilir: talimat böyle bir işleme götürürse, bu turda ayrıca soru sorulmayabilir. Ama iznin olması, ajanın onu mutlaka kullanacağı anlamına gelmez. Projenin genel erişim kuralları da geçerli olmaya devam eder.

Alan kendi başına kötü bir şey değildir: tam da sizin istediğiniz yerde gereksiz onayları ortadan kaldırır. Ama bu seti skill'in yazarı seçti, bu yüzden ilk çalıştırmadan önce ona göz atmakta fayda var.

Ve son olarak, daha az korkutucu ama çok daha sık karşılaşılan bir nokta. Skill ajanı yönlendirir, sonucu garanti etmez. Çalıştırdıktan sonra değişen dosyalara bakın ve sonucu kontrol edin: tasarım odaklı bir skill sayfayı güzelleştirebilir, ama düğmenin çalıştığını onun yerine kimse doğrulamaz.

Hazır olanlar nereden alınır

Denemek için SKILL.md'yi sıfırdan yazmanız hiç gerekmiyor. Hazır skill'ler çoğunlukla açık depolarda bulunur ya da eklentilerle birlikte gelir.

En kısa yol, ajandan uygun bir seçenek bulmasını istemek, ama onu körü körüne kurdurmamaktır. İstek şöyle olabilir:

Arayüz tasarımı için bir skill bul. Kaynağını, SKILL.md'yi ve script'leri göster,
hangi dosyaları ve araçları kullandığını açıkla. Ben onaylamadan
hiçbir şey kurma.

Kaynağa ve içeriğe baktınız mı - o zaman klasörü projenin .claude/skills/ klasörüne koymasını isteyin ve sonucu /skills ile kontrol edin.

Kendiniz aramak isterseniz Claude skills marketplace sorgusu işinizi görür. Katalog seçenek bulmaya yardım eder, ama bir güvenlik işareti değildir: içerik yine de kurulumdan önce okunur.

SKILL.md açık Agent Skills standardını izler, bu yüzden temel yapı farklı ajanlar arasında taşınabilir. Ama Claude Code kendi alanlarını ve çalıştırma yollarını ekler. Skill'i başka bir araca taşıdıysanız, orada hangi özelliklerin gerçekten desteklendiğini kontrol edin.

Kendi skill'inizi ajanla birlikte oluşturabilirsiniz

Kendi skill'inizi yazma zamanının geldiğini anlamak için teori gerekmez: aynı prosedürü üçüncü kez anlatıyorsunuz. Görevi değil, tam olarak işlem sırasını - şuna bak, bunu kontrol et, şöyle biçimlendir, buraya dokunma. Tekrarlanıyorsa, vakti gelmiş demektir.

Ve işte iyi haber. SKILL.md'yi boş sayfadan yazmanız gerekmiyor. Taslağı ajan hazırlayabilir, sizin işiniz prosedürün ne olduğunu ve ondan ne beklediğinizi anlatmak. Bu da sıradan bir sohbete benziyor:

Commit hazırlamak için bir skill yap. Neyin değiştiğine baksın,
commit'e gereksiz dosyalar girmiş mi kontrol etsin ve mesajı
bizim şablonumuza göre yazsın. Ben istediğimde elle çalıştıracağım.
Gereksinimler yetmiyorsa, önce soru sor.

Dikkat edin, tek bir alanın adını vermediniz ve dosyanın yapısına hiç girmediniz. Gereksinimler kelimelerle söylendi, onları alanlara dönüştürmek ajanın işi.

Bilgi eksikse ajan soru sorar. Böyle bir rica olmadan hemen varsayımlarla ilerleyebilir, bu yüzden gerekli satır örnekte zaten var. Taslağı aldıktan sonra dosyaları kontrol edin, skill'i /skills ile bulun ve bir deneme çalıştırması yapın.

Prosedürü elle yürütebiliyorsanız, paketlemeden önce bunu ajanla birlikte bir kez yapın. Adım adım atılan tek bir commit, nerede düzeltme gerektiğini ve anlatımda neyin eksik kaldığını gösterir. Canlı bir denemeden çıkan skill, hafızadan yazılandan daha isabetli olur.

SKILL.md büyüdüğünde

İlk skill'iniz neredeyse her zaman tek bir dosya olur ve bu normaldir. Sıkışma sonra başlar: prosedür ayrıntılarla büyür, içine bir eşleme tablosu, bir kurallar listesi, üç uzun örnek taşınır ve bir gün dört ekranlık bir dosya açtığınızı fark edersiniz.

Her şeyi tek yere yığmaya gerek yok, nedenini de yukarıda söyledik: skill devreye girer girmez içeriği bütünüyle yüklenir. Dört ekranlık başvuru bilgisi, içinden tek bir satır gerektiğinde bile işe dahil olur.

Bu yüzden ayrıntılar yandaki dosyalara taşınır, SKILL.md'de ise bir yönlendirme kalır: şu durumda şu dosyayı aç. palettes.md ve scripts/ içeren klasörü zaten gördünüz, içeriden şöyle görünür:

## Başvuru dosyaları

- Paletler ve renk uyumları - [palettes.md](palettes.md) içinde
- Hazır işaretleme örnekleri - [examples.md](examples.md) içinde
- Kontrastı kontrol et: scripts/check.py dosyasını çalıştır

Ajan başvuru dosyasını gerektiğinde açar. Script, kaynak kodunun tamamı otomatik olarak konuşmaya yüklenmeden çalıştırılabilir, bu yüzden dosyanın boyutu bağlamdan neredeyse hiç yemez. Ama başkasının yazdığı script'i ilk çalıştırmadan önce yine de okuyun: bu çalıştırılabilir koddur ve çıktısı ajanın işine karışır.

Dosyaları amaca göre dağıtmak kullanışlıdır:

• SKILL.md - prosedürün kendisi: ne yapılacak, hangi sırayla, ne yapılmayacak. Çağrılmadan önce ajan yalnızca açıklamasını görür, içeriği çalıştırma anında yükler;
• başvuru dosyaları - tablolar, kurallar, uzun örnekler, yani her çalıştırmada gerekmeyen her şey;
• scripts/ - kelimelerle tarif etmektense çalıştırması daha kolay olan işler. Başkasının skill'inde bu dosyalar çalıştırmadan önce kontrol edilir;
• şablonlar - skill'in temel alıp göreve göre düzenlediği dosyalar.

Buradan ters yönde bir sonuç da çıkar, bu kez başkalarının skill'leri için. Kısa bir SKILL.md, "basit bir skill" anlamına gelmez. Yanında, klasörde neler durduğuna bakın.

Bu, işinizde neyi değiştirir

Hepsini birkaç satırda toplarsak:

• tekrarlanan bir istek bir klasöre dönüşür. Çalışma sırasını bir kez tarif edersiniz - sonra her oturumda ve her gün aynı şekilde tekrarlanır;
• kendi skill'inizi boş sayfadan yazmak zorunda değilsiniz. Prosedürü kelimelerle anlatır, eksikleri sormasını ister ve hazırlanan taslağı kontrol edersiniz;
• otomatik çalıştırmada skill description'a göre, elle çalıştırmada eğik çizgili adıyla seçilir. Sessiz kalıyorsa önce listede görünüp görünmediğini ve otomatik çalışmaya izin verilip verilmediğini öğrenin;
• /skills, "yerine oturdu mu" sorusunu yanıtlar. Yarım dakikalık kontrol, yarım saatlik tahmin yürütmekten kurtarır;
• başkasının skill'i kurulmadan ve çalıştırılmadan önce, ilgili dosyaları ve script'leriyle birlikte okunur;
• skill ajanın işi yapma biçimini değiştirir, ama düzenleme alanını yalıtmaz ve sonucun kontrolünü ortadan kaldırmaz.