Ajanınız Her Sabah İşe Yeni Başlıyor: Skill'leri Dokümantasyon Olarak Kullanmanın 5 İlkesi
Kısa özet: Ajan projenizi bilmez, okuduğunu bilir. Skill'leri dokümantasyon olarak kullanmanın 5 ilkesi ve 114 skill'lik kendi sistemimden çıkan dersler.
Yapay zeka ajanı projenizi bilmez. Okuduğunu bilir.
Claude Code ya da Codex'te yeni bir oturum açtığınızda karşınızdaki ajan projeye dışarıdan bakar. Hangi modülü neden öyle yazdığınızı, hangi kuralın hangi hatadan sonra konduğunu bilmez. Elinde kod ve ona bıraktığınız notlar var. Not yoksa tahmin eder. Proje büyüdükçe tahminin faturası da büyür.
Geçenlerde bir geliştiricinin bu soruna verdiği cevabı okudum. Maddelerin çoğu kendi sistemimde uyguladığım düzenle örtüşüyor. Önerisinin özü şu: ciddi bir projede her modülün ve her iş akışının bir skill'i olsun. Ajan göreve başlamadan önce işin kapsamını çıkarsın, yalnız o kapsama giren skill'leri okusun. İş bitip testler geçince skill güncellensin. Büyüyen skill alt dosyalara bölünsün. Her projede gereken skill'lerle tek projeye ait olanlar ayrı dursun.
Benim sistemim Artur. Claude Code üzerine kurduğum kişisel yapay zeka işletim sistemi; 19 Ekim 2026 akşamı yaptığım sadeleştirmeden sonra 114 skill, 61 agent ve 22 MCP sunucusu var, 21'i açık. Gelen mesaj önce bir tetikleyici haritasından geçiyor, eşleşen skill'e yönleniyor. Yani skill'i dokümantasyon olarak kullanmak bende bir öneri değil, her günkü çalışma biçimi. Aşağıdaki ilkelerin her birini bu sistemde ölçerek yönetiyorum.
Tezim şu: Ajan okuduğu kadar bilir. Ajan için yazılmamış dokümantasyon, ajan için yoktur.
1. Her modülün ve iş akışının bir skill'i olsun
README insana yazılır. Projeyi tanıtır, kurulumu anlatır. Ajanın sorduğu sorular başka: bu modül neye dokunuyor, nereden başlıyor, hangi komutla test ediliyor, neyi asla yapmamalı? Skill bu cevapları taşıyan biçim. Adı ve tek cümlelik açıklaması ajanın listesinde durur, gövdesi yalnız iş gelince açılır.
"Bir iş, bir skill" kuralı göründüğünden sıkı. Artur'da bunu düzenli bir sadeleştirme turuyla koruyorum: 19 Ekim turunda, eklentiyle ya da hesaptan eşitlenerek gelen sürümü olan 7 yerel kopyayı arşive aldım. İki kopya ajan için iki ayrı gerçek demek. Hangisini okuyacağını bilemez. Biri güncellenip öteki unutulunca da yanlış olanı izler.
Kural: kopyayı gördüğünüz gün birini silin. Skill'in gerçekten iş yapıp yapmadığı ayrı bir soru; onu AI Skill Dosyaları Gerçekten Çalışıyor mu? yazısında tartıştım.
2. Ajan önce kapsamı çıkarsın, sonra yalnız ilgili skill'i okusun
Bağlam penceresi büyüdü ama bedava olmadı. Her şeyi baştan yüklerseniz ajan daha işe başlamadan bağlamın bir kısmını ilgisiz metinle doldurur ve asıl talimatı o kalabalığın içinde arar. Prompt yazmaktan bağlamı yönetmeye geçişi Context Engineering Nedir? yazısında anlatmıştım. Skill, o yönetimin elle tutulur aracı.
Doğru sıra şöyle: ajan isteği okur, hangi modüllere dokunacağını çıkarır, yalnız o skill'leri açar. Artur'da bu işi tetikleyici haritası yapıyor. Mesaj gelince önce haritaya bakılıyor. Eşleşme varsa yalnız o skill'in dosyası okunuyor, yoksa iş sıradan bir görev gibi yürüyor. 114 skill'in hepsi her mesajda okunmuyor. Okunsaydı her mesaj on binlerce satırlık bir yükle başlardı.
Bunun için açıklamanın da ajana yazılması gerekiyor. "Fatura modülü" yetmez. "Fatura kesme ve iade işlerinde, fatura tablosuna dokunan her değişiklikte kullanılır" cümlesi ajana skill'i ne zaman açacağını söyler.
3. İş bitince skill güncellensin, yeni modül yeni skill istesin
Kod değişir de skill aynı kalırsa dokümantasyon yanlış bilgi vermeye başlar. Ajan da ona güvenir.
Paylaşımdaki öneri burada net: iş bitip testler geçince ajan ilgili skill'i güncellesin; yeni bir modül doğduysa yeni skill açmayı hatırlatsın. Bunu bir kez söylemek yetmez. Kural proje talimatlarında yazılı durmalı ve "bitti" tanımının parçası sayılmalı. Testler geçti ama skill eski mi? İş bitmedi.
Güncelliği yalnız insana bırakmıyorum. Model sağlayıcıları eski modelleri tarih vererek kapatıyor ve bu duyurular kolayca gözden kaçar; kapanan bir modele bağlı komut sessizce bozulur. Artur'da haftalık bir bekçi koddaki kapanan ya da kapanacak model çağrılarını ve Claude Code'un sürüm notlarını tarıyor, bulduğunu bana raporluyor.
Aynı mantıkla bir kanca da kurdum: bir belgeye tanınabilir bir parola, anahtar ya da token yazılmak üzereyse, yazılmadan önce durduruyor. Skill de bir belge ve belge, sırrın en kolay sızdığı yer. Her seferinde uyulması gereken kuralı skill metnine bırakmak yetmiyor. Claude Code'un belgesi de aynı yönü gösteriyor: her seferinde geçerli olması gereken kural bir kancaya taşınmalı.
Kural: skill'ler yaşayan belgelerdir. Güncel kalmaları iyi niyetle değil, kural ve otomasyonla olur.
4. Büyük skill bölünsün, ajan yalnız gereken parçayı okusun
Bir skill açılınca içeriği bağlama girer ve oturum boyunca orada kalır. Her satırın bedeli her turda yeniden ödenir. Claude Code'un belgesi bu yüzden SKILL.md dosyasını 500 satırın altında tutmayı, ayrıntıyı ayrı dosyalara taşımayı öneriyor. Ana dosya içindekiler sayfası gibi çalışır: hangi durumda hangi alt dosyanın açılacağını söyler. API ayrıntısı gerekirse ajan o dosyayı açar, gerekmezse açmaz.
Artur'da bu sınırı düzenli ölçüyorum. 19 Ekim taramasında 500 satırı aşan 7 skill çıktı, en büyüğü 843 satır; Artur'a ait olanlar bölünmeye alındı. Ana dosya yönlendirme tablosuna iner, ayrıntı alt dosyalara gider. Fark büyük: bölünmemiş 843 satırlık bir skill, işin küçük bir parçası gerekse bile her açılışta tamamını bağlama sokar.
Kural: skill 500 satırı geçtiği gün bölünür. Ertelenen her bölme, her oturumda bağlam maliyeti olarak geri döner.
5. Global skill ile projeye özel skill ayrı dursun
Bazı skill'ler her projede lazım: kod inceleme, commit düzeni, yazım kuralları, güvenlik taraması. Bazıları tek bir projeye ait: o projenin ödeme akışı, o müşterinin veri şeması. İkinci gruptakiler global kurulursa her projede ajanın listesine girer.
Bu ayrım düzen meselesi gibi görünür; asıl karşılığı bağlam bütçesidir. Claude Code, skill adlarını ve açıklamalarını taşıyan listeye varsayılan olarak modelin bağlam penceresinin yüzde 1'ini ayırıyor. Liste sığmayınca en az kullanılan skill'lerin açıklamasını düşürüyor; ad kalıyor, açıklama gidiyor. Açıklaması düşen skill'i ajan doğru anda seçemez, çünkü ne işe yaradığını bilmez. 114 skill'lik Artur'da ölçüm bunu net gösteriyor: global kurulan her skill, açılan her projede bu bütçeden pay alıyor. Bu yüzden Artur'a özgü skill'leri proje kapsamına ayırma planı hazır.
Kural: global klasörde yalnız her projede gereken skill'ler kalsın, gerisi projenin kendi klasörüne. Claude Code'da kişisel skill'ler kullanıcı klasöründe, projeye ait olanlar deponun içinde durur. Codex de depo ve kullanıcı düzeyini ayırıyor.
Nereden başlamalı?
Yarın bir projede başlayacaksanız sıra şu:
- Projenin modüllerini ve tekrar eden iş akışlarını listeleyin. Her birine bir skill açın.
- Açıklamayı ajana yazın. Ana kullanım ilk cümlede olsun: hangi istekte, hangi dosyaya dokunulunca devreye girecek.
- Proje talimatlarına (Claude Code'da CLAUDE.md, Codex'te AGENTS.md) kuralı ekleyin: iş bitip testler geçince ilgili skill güncellenir, yeni modülde yeni skill açılır.
- 500 satırı geçen skill'i bölün. Ana dosyada akış ve yönlendirme kalsın, ayrıntı alt dosyaya gitsin.
- Global klasörü ayıklayın. Tek projede kullanılan skill'i o projeye taşıyın.
- Düzenli tarama kurun: yinelenen skill, kapanmış model, eskimiş komut, artık var olmayan dosya. Artur'da bunu haftalık bir bekçi yapıyor.
- Parola, anahtar, müşteri verisi ve kişisel bilgi skill'e girmez. Yazılmadan önce durduran bir kontrol kurun.
Sık sorulan sorular
Skill ile CLAUDE.md ya da AGENTS.md arasındaki fark ne?
Proje talimat dosyası her oturumun başında yüklenir. Skill'in ise yalnız adı ve açıklaması listede durur; gövdesi iş gelince okunur. Her oturumda geçerli kısa kurallar talimat dosyasına, modül ve iş akışı bilgisi skill'e yazılır.
Bir skill kaç satır olmalı?
Claude Code belgesi SKILL.md için 500 satırın altını öneriyor. Örnekler ve API başvurusu alt dosyalara gider; ajan yalnız gerekeni açar.
Bu yöntem Codex'te de işler mi?
İşler. Codex de SKILL.md içeren klasörleri okuyor; işe her skill'in adı ve açıklamasıyla başlıyor, tam metni skill seçilince açıyor. İki araç da açık Agent Skills standardına dayanıyor. Klasör yerleri farklı, biçim aynı.
Kaç skill fazla sayılır?
Sayıya değil bütçeye bakın. Claude Code skill listesine varsayılan olarak bağlamın yüzde 1'ini ayırıyor; oran ayarla yükseltilebiliyor ama liste de o kadar yer kaplıyor. /doctor komutu listenin bağlam maliyetini gösteriyor. Açıklaması düşmüş skill görüyorsanız ayıklama ya da projeye taşıma zamanı gelmiş demektir.
Bir kez anlat, sonra güncelle
Skill yazmayan ekip ajanına projeyi her sabah baştan anlatır. Skill yazan ekip bir kez anlatır, sonra yalnız günceller. Birincisi aynı bedeli her oturumda öder, ikincisi bir kez.
Ajan okuduğu kadar bilir. Neyi ve ne zaman okuyacağına siz karar veriyorsunuz.
Takipte kalın.
Kaynaklar
