Yazma Becerileri

Genel Bakış

Yazma becerisi, Test-Driven Development'ın süreç belgelerine uygulanmasıdır.

Kişisel beceriler, runtime'ınızın skills dizininde yaşar — yolunuzu bulmak için claude-code-tools.md, codex-tools.md, copilot-tools.md veya gemini-tools.md dosyalarına bakın. Codex, Copilot CLI ve Gemini CLI, ~/.agents/skills/ klasörünü çapraz-runtime takma adı olarak da tanıyor.

Test senaryoları yazarsınız (subagentlarla baskı senaryoları), başarısız olmalarını izlersiniz (temel davranış), beceri yazarsınız (belgeleme), testlerin geçmesini izlersiniz (agentlar uyuyor) ve refactor edersiniz (açıkları kapatırsınız).

Temel ilke: Bir agentin beceri olmadan başarısız olmasını izlemediyseniz, becerinin doğru şeyi öğretip öğretmediğini bilemezsiniz.

GEREKLI ARKA PLAN: Bu beceriyi kullanmadan önce superpowers:test-driven-development'ı ANLAMALIsınız. O beceri temel RED-GREEN-REFACTOR döngüsünü tanımlar. Bu beceri TDD'yi belgelemeye uyarlar.

Resmi rehberlik: Anthropic'in resmi beceri yazma en iyi uygulamaları için, anthropic-best-practices.md dosyasına bakın. Bu belge, bu beceriye odaklanan TDD yaklaşımını tamamlayan ek kalıplar ve yönergeler sağlar.

Beceri Nedir?

Beceri, kanıtlanmış teknikler, kalıplar veya araçlar için bir referans kılavuzudur. Beceriler, gelecekteki agentlerin etkili yaklaşımları bulmasına ve uygulamasına yardımcı olur.

Beceriler şunlardır: Yeniden kullanılabilir teknikler, kalıplar, araçlar, referans kılavuzları

Beceriler DEĞILDIR: Bir sorunu bir kez nasıl çözdüğünüze dair anlatılar

TDD Beceriler İçin Haritalama

Tüm beceri oluşturma süreci RED-GREEN-REFACTOR'u takip eder.

Beceri Ne Zaman Oluşturulur

Şu zaman oluşturun:

• Teknik size sezgisel olarak açık değildi
• Bunu projeler arasında tekrar referans alırdınız
• Kalıp geniş ölçüde uygulanır (projeye özgü değil)
• Diğerleri fayda sağlardı

Şu durumlarda oluşturmayın:

• Tek seferlik çözümler
• Başka yerlerde iyi belgelenmiş standart uygulamalar
• Projeye özgü kurallar (bunları talimatlar dosyanıza koyun)
• Mekanik kısıtlamalar (regex/doğrulama ile uygulanabilirse, otomatikleştirin — belgelemeyi yargı çağrıları için saklayın)

Beceri Türleri

Teknik

İzlenecek adımlarla somut yöntem (condition-based-waiting, root-cause-tracing)

Kalıp

Sorunları düşünme şekli (flatten-with-flags, test-invariants)

Referans

API dokümanları, syntax kılavuzları, araç belgeleri (office docs)

Dizin Yapısı

skills/
  skill-name/
    SKILL.md              # Ana referans (gerekli)
    supporting-file.*     # Yalnızca gerekiyorsa

Düz namespace - tüm beceriler bir aranabilir namespace'de

Ayrı dosyalar için:

1. Ağır referans (100+ satır) - API dokümanları, kapsamlı syntax
2. Yeniden kullanılabilir araçlar - Betikler, yardımcı programlar, şablonlar

Satır içinde tutun:

• İlkeler ve konseptler
• Kod kalıpları (< 50 satır)
• Diğer her şey

SKILL.md Yapısı

Frontmatter (YAML):

• İki gerekli alan: name ve description (tüm desteklenen alanlar için agentskills.io/specification bakın)
• Maksimum 1024 karakter toplam
• name: Sadece harfler, rakamlar ve tire kullanın (parantez, özel karakterler yok)
• description: Üçüncü kişi, SADECE ne zaman kullanılacağını açıklar (NE yaptığını değil)
  • Tetikleme koşullarına odaklanmak için "Use when..." ile başlayın
  • Belirli semptomları, durumları ve bağlamları ekleyin
  • BİR ZAMAN becerinin sürecini veya iş akışını özetlemeyin (SDO bölümü nedenini açıklar)
  • Mümkünse 500 karakterin altında tutun

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview
Bu nedir? Temel ilke 1-2 cümlede.

## When to Use
[Karar belirgin değilse küçük satır içi akış şeması]

Semptomlar ve kullanım durumlarıyla madde listesi
Ne zaman kullanmayın

## Core Pattern (teknikler/kalıplar için)
Önce/sonra kod karşılaştırması

## Quick Reference
Tarama için tablo veya madde işaretleri

## Implementation
Basit kalıplar için satır içi kod
Ağır referans veya yeniden kullanılabilir araçlar için dosyaya bağlantı

## Common Mistakes
Neler yanlış gider + düzeltmeler

## Real-World Impact (isteğe bağlı)
Somut sonuçlar

Beceri Keşif Optimizasyonu (SDO)

Keşif için kritik: Gelecekteki agentlerin becerilerinizi BULMASI gerekir

1. Zengin Tanım Alanı

Amaç: Agentiniz, belirli bir görev için hangi becerileri yükleyeceğine karar vermek üzere tanımı okur. Cevapla: "Bu beceriyi şu anda mı okumalıyım?"

Format: Tetikleme koşullarına odaklanmak için "Use when..." ile başlayın

KRITIK: Tanım = Ne Zaman Kullanılır, Beceri Ne Yapar DEĞİL

Açıklama SADECE tetikleme koşullarını açıklamalıdır. Becerinin sürecini veya iş akışını tanımda ÖZET HALINE GETİRMEYİN.

Neden bu önemli: Testing, bir tanım becerinin iş akışını özetlediğinde, agentın tanımı takip edebileceğini (tam beceri içeriğini okuması yerine) ortaya çıkardı. "Görevler arasında kod gözden geçirmeli görevleri yürütme" diyen bir tanım, akış şemasında açıkça iki gözden geçirme gösterilse de (spec uyumluluğu sonra kod kalitesi), agentın BİR gözden geçirme yapmasına neden oldu.

Tanım sadece "Geçerli oturumda bağımsız görevlerle uygulama planlarını yürütürken kullan" (iş akışı özeti yok) olarak değiştirildiğinde, agent doğru şekilde akış şemasını okudu ve iki aşamalı gözden geçirme sürecini takip etti.

Tuzak: İş akışını özetleyen açıklamalar, agentlerin atacağı kısayollar oluşturur. Beceri gövdesi, agentlerin atladığı belgelendirme haline gelir.

# ❌ KÖTÜ: İş akışını özetler - agentlar bunu okumak yerine takip edebilir
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ KÖTÜ: Çok fazla süreç detayı
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ İYİ: Sadece tetikleme koşulları, iş akışı özeti yok
description: Use when executing implementation plans with independent tasks in the current session

# ✅ İYİ: Sadece tetikleme koşulları
description: Use when implementing any feature or bugfix, before writing implementation code

İçerik:

• Somut tetikleyiciler, semptomlar ve bu becerinin uygulandığını işaret eden durumlar kullanın
• Sorunu açıklayın (yarış koşulları, tutarsız davranış), dile özgü semptomları değil (setTimeout, sleep)
• Tetikleyicileri teknoloji-agnostik tutun, beceri kendisi teknoloji-spesifik olmadıkça
• Beceri teknoloji-spesifikse, bunu tetikleyicide açık hale getirin
• Üçüncü kişi yazın (sistem istemiyine enjekte edilmiş)
• BİR ZAMAN becerinin sürecini veya iş akışını özetlemeyin

# ❌ KÖTÜ: Çok soyut, muğlak, ne zaman kullanılacağını içermiyor
description: For async testing

# ❌ KÖTÜ: Birinci kişi
description: I can help you with async tests when they're flaky

# ❌ KÖTÜ: Teknolojiyi adlandırır ama beceri buna özgü değil
description: Use when tests use setTimeout/sleep and are flaky

# ✅ İYİ: "Use when" ile başlar, sorunu açıklar, iş akışı yok
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ İYİ: Teknoloji-spesifik beceri açık tetikleyiciyle
description: Use when using React Router and handling authentication redirects

2. Anahtar Kelime Kapsama

Agentın arayabileceği sözcükleri kullanın:

• Hata iletileri: "Hook timed out", "ENOTEMPTY", "race condition"
• Semptomlar: "flaky", "hanging", "zombie", "pollution"
• Eşanlamlar: "timeout/hang/freeze", "cleanup/teardown/afterEach"
• Araçlar: Gerçek komutlar, kütüphane adları, dosya türleri

3. Açıklayıcı Adlandırma

Aktif ses, fiil-önce kullanın:

• ✅ creating-skills değil skill-creation
• ✅ condition-based-waiting değil async-test-helpers

4. Token Verimliliği (Kritik)

Sorun: getting-started ve sık referans alınan beceriler HER konuşmaya yüklenir. Her token sayılır.

Hedef sözcük sayıları:

• getting-started iş akışları: <150 sözcük her biri
• Sık yüklenen beceriler: <200 sözcük toplam
• Diğer beceriler: <500 sözcük (yine de kısa olun)

Teknikler:

Ayrıntıları araç yardımına taşıyın:

# ❌ KÖTÜ: Tüm bayrakları SKILL.md'de belgelendir
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ İYİ: --help'i referans alın
search-conversations supports multiple modes and filters. Run --help for details.

Çapraz referansları kullanın:

# ❌ KÖTÜ: İş akışı detaylarını tekrarla
When searching, dispatch subagent with template...
[20 satır tekrarlanmış talimatlar]

# ✅ İYİ: Diğer beceriyi referans alın
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

Örnekleri sıkıştırın:

# ❌ KÖTÜ: Ayrıntılı örnek (42 sözcük)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ İYİ: Minimal örnek (20 sözcük)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

Fazlalığı ortadan kaldırın:

• Çapraz referans alınan beceriler yapılanları tekrarlamayın
• Komuttan açık olan şeyi açıklamayın
• Aynı kalıptan birden fazla örnek eklemeyin

Doğrulama:

wc -w skills/path/SKILL.md
# getting-started iş akışları: <150 hedefle
# Diğer sık yüklenen: <200 toplam hedefle

Ne yaptığınız veya temel fikir ile adlandırın:

• ✅ condition-based-waiting > async-test-helpers
• ✅ using-skills değil skill-usage
• ✅ flatten-with-flags > data-structure-refactoring
• ✅ root-cause-tracing > debugging-techniques

Gerundler (-ing) süreçler için iyi çalışır:

• creating-skills, testing-skills, debugging-with-logs
• Etkin, aldığınız eylemi tanımlar

5. Diğer Beceriler Arasında Çapraz Referans

Diğer beceriler referans alan belgeleme yazarken:

Beceri adını yalnızca, açık gereklilik işaretçileriyle kullanın:

• ✅ İyi: **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
• ✅ İyi: **REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
• ❌ Kötü: See skills/testing/test-driven-development (gerekli olup olmadığı belirsiz)
• ❌ Kötü: @skills/testing/test-driven-development/SKILL.md (zorla yükler, bağlamı tüketir)

Neden @ bağlantıları yok: @ sözdizimi dosyaları hemen yükler, ihtiyaç duyulmadan önce 200k+ bağlamı tüketir.

Akış Şeması Kullanımı

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

Akış şemaları SADECE şunlar için kullanın:

• Belirgin olmayan karar noktaları
• Erken durdurabildiğiniz süreç döngüleri
• "A vs B'yi ne zaman kullanın" kararları

Akış şemaları ASLA şunlar için kullanmayın:

• Referans malzemesi → Tablolar, listeler
• Kod örnekleri → Markdown blokları
• Doğrusal talimatlar → Numaralı listeler
• Anlamlandırılmış etiketler olmayan etiketler (step1, helper2)

Bu dizindeki graphviz-conventions.dot dosyasına graphviz stil kuralları için bakın.

İnsan ortağınız için görselleştirme: Bir becerinin akış şemalarını SVG'ye işlemek için bu dizindeki render-graphs.js dosyasını kullanın:

./render-graphs.js ../some-skill           # Her diyagram ayrı
./render-graphs.js ../some-skill --combine # Tüm diyagramlar bir SVG'de

Kod Örnekleri

Bir mükemmel örnek, birçok ortadörtü örneğinden daha iyi

En ilgili dili seçin:

• Testing teknikler → TypeScript/JavaScript
• Sistem debugging → Shell/Python
• Veri işleme → Python

İyi örnek:

• Tamamen ve çalıştırılabilir
• Neden açıklayan iyi yorum
• Gerçek senaryodan
• Kalıbı açıkça gösterir
• Uyarlamaya hazır (genel şablon değil)

Şunları yapmayın:

• 5+ dilde uygula
• Doldurmak-kendilik boş şablonlar oluştur
• Uydurma örnekler yaz

Portlama konusunda iyi olduğunuz için - bir harika örnek yeterli.

Dosya Organizasyonu

Bağımsız Beceri

defense-in-depth/
  SKILL.md    # Her şey satır içi

Ne zaman: Tüm içerik uyduğunda, ağır referansa ihtiyaç yokken

Yeniden Kullanılabilir Araçla Beceri

condition-based-waiting/
  SKILL.md    # Genel bakış + kalıplar
  example.ts  # Uyarlanacak çalışan yardımcı programlar

Ne zaman: Araç yeniden kullanılabilir kod olduğunda, sadece anlatı değilken

Ağır Referansla Beceri

pptx/
  SKILL.md       # Genel bakış + iş akışları
  pptxgenjs.md   # 600 satır API referansı
  ooxml.md       # 500 satır XML yapısı
  scripts/       # Çalıştırılabilir araçlar

Ne zaman: Referans malzemesi satır içi için çok büyükken

Demir Kural (TDD ile Aynı)

BAŞARILI BİR TEST OLMADAN BECERİ YOK

Bu YENİ beceriler ve MEVCUT beceriler için DÜZENLEMELERİ için geçerli.

Beceriyi testing olmadan yazın? Silin. Baştan başlayın. Beceriyi test olmadan düzenleyin? Aynı ihlal.

İstisnalar yok:

• "Basit eklemeler" için değil
• "Sadece bir bölüm ekleme" için değil
• "Belgelendirme güncellemeleri" için değil
• Test edilmemiş değişiklikleri "referans" olarak tutmayın
• Testleri çalıştırırken "uyarlamayın"
• Sil, sil demektir

GEREKLI ARKA PLAN: superpowers:test-driven-development becerisi bunun neden önemli olduğunu açıklar. Aynı ilkeler belgelendirmeye de uygulanır.

Tüm Beceri Türlerini Testing

Farklı beceri türleri farklı test yaklaşımları gerektirir:

Disiplin Uygulayan Beceriler (kurallar/gereklilikler)

Örnekler: TDD, verification-before-completion, designing-before-coding

Test edin:

• Akademik sorular: Kuralları anlıyorlar mı?
• Baskı senaryoları: Baskı altında uyuyor mu?
• Birden fazla baskı birleştirilmiş: zaman + batık maliyet + yorgunluk
• Haklı gösterişleri tanımla ve açık karşıtlar ekle

Başarı kriterleri: Agent maksimum baskı altında kural takip eder

Teknik Beceriler (nasıl yapılır rehberleri)

Örnekler: condition-based-waiting, root-cause-tracing, defensive-programming

Test edin:

• Uygulama senaryoları: Tekniği doğru uygulaybilir mi?
• Varyasyon senaryoları: Kenar durumları ele alıyor mu?
• Eksik bilgi testleri: Talimatlar boşluk var mı?

Başarı kriterleri: Agent tekniği başarıyla yeni senaryoya uygular

Kalıp Beceriler (zihinsel modeller)

Örnekler: reducing-complexity, information-hiding konseptleri

Test edin:

• Tanıma senaryoları: Kalıp ne zaman uygulanır tanırlar mı?
• Uygulama senaryoları: Zihinsel modeli kullanabilir mi?
• Karşı-örnekler: Ne zaman KULLANMAYACAKLARını biliyorlar mı?

Başarı kriterleri: Agent doğru şekilde ne zaman/nasıl uygulanacağını tanımlar

Referans Beceriler (belgelendirme/API'ler)

Örnekler: API belgelendirmesi, komut referansları, kütüphane kılavuzları

Test edin:

• Alma senaryoları: Doğru bilgiyi bulabilir mi?
• Uygulama senaryoları: Bulduğunu doğru uygulaybilir mi?
• Boşluk testing: Yaygın kullanım durumları kapsanıyor mu?

Başarı kriterleri: Agent referans bilgisini bulur ve doğru uygulanır

Testing'i Atlama İçin Yaygın Haklı Gösterişler

Tüm bunlar şu anlama gelir: Dağıtmadan önce test et. İstisnalar yok.

Hatayı Forma Eşle

Rehberlik yazmadan önce, temel hatayı sınıflandırın. Bir başarısızlık türünü mermilemek olan form, ölçülebilir şekilde başka bir türde geri tepmez.

Yasaklamalar neden şekillendirme sorunlarıyla geri tepmez: rekabet eden bir teşvik altında ("istemi kendine yetecek yap"), agentlar "X yapma" ile görüşür. dispatch-prompt rehberliğine ilişkin head-to-head sözcük testlerinde, yasaklama kolu açıkça istenmemiş içeriğin daha fazlasını üretti (tam ayrılmış dağılımlar) ve hiçbir rehberlik kontrol bile elden daha kötü eğilim gösterdi — kendi durumunuzda mikro-test'i varsaymayın, ama varsayılan olarak yasaklamaya asla uzanmayın. Tarif çıktıyı yapısına göre yapıştırır: belirtilen şekille eşleşir veya eşleşmez.

Seçtiğiniz hangi form olursa olsun kurallar:

• Nüans cümleleri yok. "Önemli olmadıkça X yapma" görüşü yeniden açar — kazanan tarife tek bir nüans cümlesi eklenmesi, tutarlıdan gürültülüye düşürdü aynı sözcük testlerinde. Gerçek istisnayı gözlenebilir bir yüklemeyle şartlı olarak ifade edin.
• İstisna cümleleri kapsam değildir. "Bu sınır kod blokları için geçerli değildir" hala kod bloklarını bastırır. Çıktının bir parçası muaf olmalıysa, kural buna ulaşamayacak şekilde yeniden yapılandırın.

Becerileri Haklı Gösterişlere Karşı Bulletproofing

Disiplini uygulayan beceriler (TDD gibi) haklı gösterilişlere karşı direnç gerektirir. Agentlar zekidir ve baskı altında açıklar bulacaklar.

Kapsam: Bu araç takımı disiplin başarısızlıkları içindir — bir kuralı bilen ve baskı altında atlayan bir agent. Yanlış şekilde çıktı veya atlanmış öğeler için, yasaklama tabanlı bulletproofing geri tepmez; yerine Match the Form to the Failure'daki formları kullanın.

Psikoloji notu: Neden ikna teknikleri çalıştığını anlamak, bunları sistematik olarak uygulamanıza yardımcı olur. İkna ilkeleri hakkında araştırma temeli (Cialdini, 2021; Meincke et al., 2025) için persuasion-principles.md bakın; otorite, bağlılık, kıtlık, sosyal kanıt ve birlik ilkeleri.

Her Açığı Açıkça Kapatın

Kuralı belirtmeyin - belirli workaround'ları yasaklayın:

</Good>

### "Ruh vs Harf" Argümanlarını Ele Alın

Temel ilkeyi erken ekleyin:

```markdown
**Kuralların harfini ihlal etmek, kuralların ruhunu ihlal etmektir.**

| Mazeret | Gerçek |
|--------|--------|
| "Çok basit test etmek için" | Basit kod kırılır. Test 30 saniye alır. |
| "Sonra test ederim" | Sonra testler = "bunu ne yapıyor?" Önce testler = "bunu ne yapmalı?" |
| "Sonra testler aynı hedeflere ulaşır" | Sonra testler = "bu ne yapar?" Önce testler = "ne yapmalı?" |

## Red Flags - STOP and Start Over

- Test önce kod
- "Zaten elle test ettim"
- "Sonra testler aynı amaca ulaşır"
- "Bu ruh hakkında değil ritual"
- "Bu farklı çünkü..."

**Tüm bunlar şu anlama gelir: Kodu sil. TDD ile baştan başla.**

description: use when implementing any feature or bugfix, before writing implementation code

step1 [label="import fs"];
step2 [label="read file"];