Claude Code skill'imi 5 kez yok saydı. 1 satır düzeltti

Bir Claude Code skill'i adıyla çağırdığında kusursuz çalışıp yine de kendi kendine hiç yüklenmeyebilir. Bizimki adını yazdığımız her seferinde çalıştı, aynı işi sade sözlerle istediğimiz her seferinde atlandı. Atlanışını izledik, nedenini okuduk ve sorunu çözen tek satırı yeniden yazdık.

Skill, isteğin uyduğunda Claude Code'un kendiliğinden aldığı kayıtlı bir talimat kümesidir. Eşleşmeyi belirleyen talimatların değil, Claude'un seçim yapmadan önce okuduğu tek bir satırdır. Aşağıdaki altı adım seni sürekli yeniden yazdığın prompt'tan kendi kendine yüklenen bir skill'e götürür; üstüne, atlanan bir skill'i ekibin fark etmesinden önce yakalayan yirmi istekli bir test de var.

Test (aynı istek, yeni oturumlar)	Skill yüklendi
Adıyla çağrıldı (/release-notes)	2 / 2
Sade sözler, özgün açıklama	0 / 5
Sade sözler, yeniden yazılmış açıklama	5 / 5

Skill, içinde tek dosya olan bir klasördür: SKILL.md. Dosya kısa bir başlıkla (bir ad ve tek cümlelik bir açıklama) başlar, ardından talimatlar gelir. Bir fonksiyon gibi çalışır: çağıran imzayı ve docstring'i okur, gövde yalnızca çağrıldığında çalışır. Her projede olsun diye ana klasörüne ya da orada çalışan herkes alsın diye depoya koy.

Dosyadan değil, görevden başla. Sürekli yeniden yazdığın prompt'u seç ve istediğin çıktıyı tam olarak yaz. Bizimki haftalık release notes'tu: Pazartesi'den beri commit'ler, alana göre gruplanmış, rutin işler atılmış, her değişiklik için pull request numarasıyla tek satır. Açık kaynaklı Hono deposunda bu uzun prompt o hafta sekiz hata düzeltmesi için temiz notlar üretti ve bu çıktı skill'in tutturması gereken hedef oldu.

Her prompt skill'i hak etmez. Tek seferlik bir soru etmez, bir daha kullanmadığın skill ise Claude'un okuması gereken bir satır daha demektir. Her hafta yazdığın prompt'ların kısa bir listesini tut; en üstteki ilk skill'in olsun.

Projende .claude/skills/release-notes/SKILL.md oluştur: gizli .claude klasörünün içinde bir skills klasörü, skill'in adını taşıyan bir klasör ve onun içinde skill dosyası. Klasör önemlidir. Ortada duran bir release-notes.md hiç yüklenmez ve belgeler bunu kontrol edilecek ilk şey olarak sayar.

Başlık, iki tire sırası arasındaki birkaç etiketli satırdır ve dosyanın ilk satırında başlamalıdır, yoksa Claude Code onu yok sayar. Bizimkinde release-notes adı ve çoğu kişinin yazacağı açıklama vardı:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Başlığın altına talimatlar numaralı adımlar olarak gelir, yeni bir ekip arkadaşına vereceğin türden. Bizimkinde beş tane var: Pazartesi'den beri commit'leri bul, chore ve docs commit'lerini at, conventional commit scope'una göre grupla, her değişiklik için sade tek satır yaz ve üstte kısa bir özet olan başlıklı bir blok çıkar. Anthropic bu kısmı kısa tutmayı öneriyor. Yeniden başlatmana gerek yok: Claude Code yeni ya da düzenlenmiş bir skill'i zaten açık olan oturumda alır.

Adıyla dene: bir eğik çizgi yaz, menüden skill'i seç, enter'a bas. Yeni oturumlarda bizimki her seferinde commit günlüğünü okudu, düzeltmeleri alana göre grupladı ve notları tam istediğimiz gibi yazdı. Tuzak şu ki, sen ve ekibindeki herkes adını hatırlamak zorunda.

Bir ekip arkadaşı skill'in adını yazmaz. Yeni bir oturum açar ve sana soracağı gibi sorar. O yüzden bunu sına: yeni bir oturum aç (hiçbir şey yüklenmemiş yeni bir konuşma) ve görevi kendi sözlerinle iste. Oturum yeni olmak zorunda, çünkü kullanılmış bir skill konuşmada kalır ve o oturumdaki bir test hiçbir şey kanıtlamaz.

"what did we ship this week?" yazdık. Claude commit günlüğünü kendi çalıştırdı ve skill'den iz olmadan özetini kendi yöntemiyle yazdı. Cevaplar kötü değildi ama çalıştırmadan çalıştırmaya kayıyordu: biri Pazartesi'den saydı, diğeri son sürüm etiketinden saydı ve skill'in atacağı bir dokümantasyon değişikliğini de içine aldı. Beş yeni oturumda skill beşinde de atlandı.

Beş çalıştırma bir demodur, istatistik değil. Ama adıyla çalışan ve sade sözlerle her seferinde atlanan bir skill işini yapmıyordur; ikinci adımdaki adıyla test geçtiği için de bakmak aklına bile gelmezdi.

Tek bir kelimeyi değiştirmeden önce üç kontrol yap:

1. /skills oturumun görebildiği her skill'i listeler. Seninkini ara. Bizimki listedeydi ve açıktı, ama kurulumda 277 skill vardı ve birkaç eklenti skill'i "release" kelimesiyle bizimkinden önce eşleşiyordu.
2. claude --debug Claude Code'un neyi yüklediğine dair ayrıntılı bir günlük yazar. Skill satırlarına bak. Bizimkinde proje skill'i yüklenmişti ve ayrıca skill listesinin bütçeyi aştığına dair bir uyarı vardı, yani bazı açıklamalar kesiliyor.
3. claude plugin validate .claude/skills başlığın düzgün biçimlendirildiğini kontrol eder. Bu önemli: bozuk bir başlık skill'in adıyla çalışmasına yine izin verir, ama Claude artık onu kendi başına eşleştiremez. Bizimki geçti.

Kontrol	Sana ne söyler	Bizim sonucumuz
/skills	Skill görünür ve açık mı?	Listede, açık (277 skill)
--debug	Yüklendi mi? Liste kesildi mi?	Yüklendi; liste bütçeyi aşıyor uyarısı
plugin validate	Başlık ayrıştırılıyor mu?	Geçti

Dosya yüklenmiş ve başlık geçerliyken sebep açıklamadır. Bir skill'i yüklemeye karar verene kadar Claude talimatlarını okumaz. Skill başına tek satır okur, adı ve açıklamayı, ve bunları senin sözlerinle eşleştirir. Bizimki "generates changelog documents from repository history" diyordu; istek "what did we ship this week" diyordu. İki cümlenin ortak tek kelimesi yok. Claude talimatlarımızı hiç okumadı; tek bir satır okudu ve o satır bizim kelimelerimizi kullanmıyordu.

Bütçe uyarısı, Claude Code'un açıklamaları sığdırmak için kestiği anlamına gelir, en az kullanılan skill'lerden başlayarak; yepyeni bir skill ise hepsinin en az kullanılanıdır. Seninkinin hayatta kaldığını kontrol et: bizimki kaldı, çünkü kendi kelimelerini kullanan istekler onu yine yükledi.

Açıklamayı dosya için değil, birinin istediği an için yaz. Skill'in ne yaptığını, ne zaman kullanılacağını ve insanların gerçekten yazdığı kelimeleri söyle. Bizimki şuna dönüştü:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

Anthropic'in yazım rehberi bir kural daha ekliyor: üçüncü tekil kişiyle yaz ("Writes"), "I can help" ya da "You can use this" asla.

Sonra aynı istekle yeni bir oturumda kanıtla. "What did we ship this week?" artık Claude hiçbir şeye dokunmadan skill'i yükledi ve notlar beş yeni oturumun beşinde bizim biçimimizle çıktı.

Bir de temel karşılaştırma yap: skill'i yerel ayar dosyandaki bir skill override ile kapat (silmeden gizler). Kapalıyken Claude kendi özetine döndü; açıkken skill yüklendi. Farkı yaratan şans değil, skill'di.

Sınır: çok fazla şeyle eşleşen bir açıklama skill'in olmaması gereken yerde tetiklenmesine yol açar. Aklına gelen her kelimeyi değil, gerçekten kullandığın kelimeleri ekle.

Tek bir istek düzeltmeyi kanıtladı; ama bir ekibin güvendiği skill pek çok şekilde istenir. Anthropic'in skill-creator'ı testi anlatıyor: yirmi istek, skill'i yüklemesi gerekenler ile yüklememesi gereken yakın ıskalardan oluşan bir karışım. Yakın ıska benzer duyulan ama farklı bir iştir, örneğin "write a commit message for my staged changes". Her isteği kendi yeni oturumunda çalıştır ve skill'in yüklenip yüklenmediğini not et. Skill-creator'ın kendi betiği skill'i bizim Claude Code sürümümüzde görmedi, biz de aynı yirmi isteği kendi kısa betiğimizle çalıştırdık.

Açıklama	Yüklemesi gereken ve yükleyen istekler	Yakın ıskalardan yükleyenler
Özgün	4 / 10	0 / 10
Yeniden yazılmış	10 / 10	0 / 10

Yeniden yazımdan önce skill yalnızca zaten "release notes", "changelog" ya da "release" geçen isteklerde yüklendi: dördüncü adımdaki kelime eşleşmesi, apaçık ortada. Yeniden yazımdan sonra yüklenmesi gereken her istekte yüklendi ve yine de hiçbir yakın ıskaya girmedi.

Asla ıskalamaması gereken bir skill için zorla. Adını yaz ya da bir hook ekle (Claude Code'un belirli bir anda çalıştırdığı küçük bir betik, burada gönderdiğin her mesajda), çıktısı Claude'a o görev için skill'i kullanmasını söylesin. Hook varken özgün açıklama bile sade isteği yükledi. Sınır: her test çalıştırması gerçek kullanım kotası harcar ve hook her mesaja bir satır ekler, o yüzden gerçekten tetiklenmesi şart olan birkaç skill için sakla. Açıklamayı değiştirdiğinde listeni yeniden çalıştır.

Release-notes skill'imiz adıyla her seferinde çalıştı, sade sözlerle her yeni oturumda atlandı ve yeniden yazılan tek satır onu her seferinde yükletti. Sebebi: Claude karar vermeden önce skill başına tek satır okur ve niyetini değil, kelimelerini eşleştirir.

Skill, sabit çıktılı tekrarlanan bir görev için işe yarar: haftalık notlar, bir pull request açıklaması, bir sürüm kontrol listesi. Tek seferlik bir soru için yaramaz ve her zaman geçerli olması gereken bir kural için doğru araç değildir; o bir hook'un işidir. Kullanılmayan skill yığını da maliyetlidir, çünkü çok fazla olunca Claude Code açıklamaları kesmeye başlar, en az kullanılandan başlayarak. İyi bir açıklama şansı artırır ama bir skill'i hiç amacı olmadığı bir iş için tetiklemez ve birkaç çalıştırma bir demodur, yani asıl kontrol test isteği listendir.

Tek kural: açıklamayı, o görevi isterken gerçekten yazdığın kelimelerle yaz.