cn claudenews Ara /

Lesson 07 · 22 dk okuma

Slash Commands, Skills ve Custom Workflows

Project .claude/commands/ vs user ~/.claude/commands/ ayrımı, SKILL.md frontmatter (context:fork, allowed-tools, argument-hint) ve skill'lerin ne zaman command'dan üstün olduğu.

Öğreneceklerin

  • Slash command dosya yapısını ve frontmatter alanlarını bilmek
  • context: fork'un subagent izolasyonu için nasıl kullanıldığını açıklamak
  • allowed-tools'un güvenlik için neden kritik olduğunu göstermek
  • Skill vs command farkını (prosedürel vs deklaratif) kavramak
  • Personal skill varyantlarını ~/.claude/skills/ altında konumlandırmak

Slash Commands, Skills ve Custom Workflows

Bu derste Claude Code’un “yürütülebilir prosedür” katmanını açıyoruz: slash command’lar ve skill’ler. Sınavda en sık karıştırılan iki şey — biri kısa, doğrudan bir prompt expansion (command), diğeri çok adımlı, izole çalışan, araç kısıtlı bir prosedür (skill). Sınav seni şu soruyla test eder: “Bu iş için command mı skill mı yazarsın?” Doğru cevap “iş birden fazla tool gerektiriyorsa ve output’un ana session’ı kirletmesini istemiyorsan skill” — aşağıda neden.

Neden bu konu sınavda çıkıyor

Domain 3’ün “extend the harness” kısmı. Sınav senaryolarında command ve skill ayrımı en az 1-2 soruda direkt, başka 1-2 soruda da “custom workflow tasarla” çerçevesinde geliyor. Tipik soru: “Bir code review agent’ı kuracaksın. Review sırasında sadece Read, Grep, Glob tool’larına erişim olsun ve bulgular ana session’a dökülmesin. Hangi mekanizma?” → Cevap: skill + context: fork + allowed-tools: [Read, Grep, Glob]. Bu üçlü sınavın temel formüllerinden.

Temel kavramlar

1. Slash command anatomy

Slash command = .claude/commands/ veya ~/.claude/commands/ altında bir markdown dosyası. Dosya adı / ile çağrılır.

# .claude/commands/fix-bug.md
---
description: "Verilen dosyada bug analiz eder ve düzeltme önerir"
argument-hint: "<file-path> [--strict]"
allowed-tools: Read, Grep, Glob, Edit
---

`$ARGUMENTS` dosyasında bug analiz et.

1. Önce dosyayı oku.
2. Hata desenlerini tara (try/catch eksikliği, tip hataları, async/await unutulmuş yerler).
3. Bulguları severity (CRITICAL/HIGH/MEDIUM/LOW) ile listele.
4. Düzeltme önerisi ver.

`--strict` flag'i varsa, sadece CRITICAL ve HIGH bildir.

Kullanım: /fix-bug src/auth/login.ts --strict. Burada $ARGUMENTS = "src/auth/login.ts --strict", komut içinde parse edersin. 📝 Yaygın kalıp; rehber 5.4 argüman mekanizmasını ayrıntılı belgelemez — sınav argüman validation’ı (regex, flag check) sorarsa cevap “argument-hint sadece UI placeholder, gerçek validation prompt içinde yapılır” formülüdür.

Skill frontmatter (rehber 5.5):

Rehber 5.5, SKILL frontmatter için şu üç alanı listeler:

AlanAçıklama
context: forkSkill izole subagent’ta çalışır; verbose output ana session’ı kirletmez
allowed-toolsHangi tool’ların erişilebilir olduğunu sınırlar (güvenlik — listede yoksa dosya silemez)
argument-hintParametre verilmeden çağrıldığında kullanıcıdan argüman isteyen hint

📝 Rehber kapsamı dışında: model alanı (hangi model ile çalışsın) ve command frontmatter (.claude/commands/<name>.md için ayrı bir frontmatter alanları listesi) rehber 5.4’te ayrıntılı tanımlanmaz. Pratikte slash command’lar da description, argument-hint, allowed-tools alanlarını destekler; sınav bu komut/skill ayrımını sorarsa rehber 5.5 formülünü (skill = SKILL.md + bu üç alan) kullan.

2. Skill anatomy — subagent izolasyonu

Skill = .claude/skills/<skill-name>/SKILL.md dizini. Komuttan farkı: ayrı bir subagent context’inde çalışır, ana session’ın conversation history’sini görmez.

# .claude/skills/code-review/SKILL.md
---
name: code-review  # (opsiyonel; klasör adından türetilir — rehber örneğinde yok)
description: "Değişen dosyaları review eder, bulguları severity ile listeler"
context: fork
allowed-tools: Read, Grep, Glob, Bash
argument-hint: "[--base=main]"
---

Aşağıdaki diff'i review et:

!`git diff $ARGUMENTS`

Bulgu varsa CRITICAL/HIGH/MEDIUM/LOW ile sınıflandır. False positive'den kaçın.

Burada kritik farklar:

  • context: fork: Skill kendi subagent’ında çalışır. Ana session’ın context’i bu skill’e aktarılmaz, sadece argument-hint ve SKILL.md body’si. Skill’in output’u (uzun log, test çıktısı, kapsamlı review) ana session’ı kirletmez.
  • allowed-tools: Read, Grep, Glob, Bash: Skill sadece bu tool’lara erişir. Edit ve Write yoksa skill dosya değiştiremez — sadece gözlem yapar, kullanıcı karar verir. Bu sınav için kritik güvenlik prensibi.
  • **!git diff $ARGUMENTS**: 📝 *Rehber kapsamı dışında (Claude Code pratik özelliği):* Backtick içinde !` ile başlayan satırın shell command olarak çalışıp output’unu prompt’a inline gömmesi, rehber 5.4’te tanımlı bir skill/command davranışı değildir. Pratikte sık karşılaşılan bir kalıp olduğu için örneklerde yer alır.

3. context: fork ne zaman şart?

Skill iki modda çalışabilir (rehber 5.5):

  • context: fork yazarsan: Skill izole subagent’ta çalışır. Ana session’ın context’i bu skill’e aktarılmaz; verbose output (uzun log, test çıktısı, kapsamlı review) ana session’ı kirletmez. Sınav tuzağı: “skill her zaman ayrı subagent’ta çalışır” → yanlış; bu davranış context: fork yazıldığında geçerlidir.
  • Yazmazsan (default): Skill ana session’da çalışır, history’yi görür. Bulgu sonraki adımı yönlendirecekse (örn. “şu hatayı buldu, düzelt”) veya output çok kısaysa bu mod tercih edilir.

4. allowed-tools neden kritik

Skill/command yazarken en önemli güvenlik prensibi “minimum necessary access”. Sınavda göreceğin klasik senaryo:

“Bir skill sadece dosya okuyup arama yapacak, ama yanlışlıkla Edit tool’una erişti ve kullanıcının bilgisi olmadan 12 dosyayı değiştirdi.”

Çözüm: allowed-tools ile sınırla. Claude sadece listelenen tool’ları çağırabilir; Edit listede yoksa dosya değiştiremez. Bu sınavda hem “neden” hem “nasıl” soruluyor.

Örnek set’ler:

  • Read-only review: Read, Grep, Glob (dosya değiştiremez)
  • Code edit: Read, Grep, Edit, Write (ama Bash yok, komut çalıştıramaz)
  • CI runner: Bash, Read (ama Edit/Write yok, dosya değiştiremez)
  • Test runner: Bash, Read, Grep (test çalıştırır ama kaynak değiştiremez)

5. Karar matrisi: command mı skill mı?

DurumSeçimNeden
Tek prompt expansion, 1-2 tool callcommandSkill overhead’i gereksiz
5+ tool call, verbose outputskill + forkAna session’ı kirletmesin
User-level kişisel komut~/.claude/commands/Repo’ya yazılmaz
Repo’ya commit edilen takım komutu.claude/commands/Paylaşılır
Çok adımlı, araç kısıtlı işlemskillSubagent izolasyonu
Output kısa, ana session’a akacakcommand (veya skill fork’suz)Context paylaşımı gerekli

6. Paylaşım kuralı — VCS

  • Project commands/skills: .claude/commands/, .claude/skills/ → git’e commit edilir, ekibin tamamı kullanır
  • User commands/skills: ~/.claude/commands/, ~/.claude/skills/ → kişisel, hiçbir repo’ya yazılmaz

Sınav tuzağı: “Kişisel alias’ları repo’nun .claude/commands/ altına koy” → yanlış, takım üyesi görecek ve kirletecek. Doğrusu: ~/.claude/commands/.

Sınav tuzakları

  1. “Skill her zaman ayrı subagent’ta çalışır” — Yanlış. context: fork yazmazsan ana session’da çalışır. Default davranış fork değil.
  2. “Slash command’da allowed-tools yazmazsan tüm tool’lar erişilebilir” — Doğru, bu sınavda “en güvenli” cevabı. Allowed-tools yazmamak maksimum yetki demek, yazmak sınır.
  3. “allowed-tools sadece performans optimizasyonu içindir” — Yanlış. Birincil amacı güvenlik ve scope sınırı. Performans yan etki.
  4. “Skill output’u her zaman ana session’a döner” — Yanlış. Fork yapıldıysa sadece SKILL.md’de tanımlı ## Output (veya son mesaj) döner; ara tool call’lar görünmez.
  5. “argument-hint gerçek input validation yapar” — Yanlış. Sadece UI placeholder. $ARGUMENTS içinde kendi parse’ını yaparsın (regex, flag check).
  6. “Bir skill diğer skill’leri çağırabilir / skill’ler iç içe çağrılamaz” — 📝 Rehber kapsamı dışında. Rehber 5.5 skill’ler arası çağrı ilişkisini tanımlamaz. Sınav “nested skill” veya “skill invokes skill” gibi bir senaryo sorarsa “rehber bu detayı vermez” de.

Hands-on

Senaryo: Ekip için bir “test-coverage” skill’i kuracaksın. Bu skill:

  • Sadece *.test.ts ve *.tsx dosyalarını okusun
  • Bash ile vitest çalıştırsın
  • Hiçbir dosya değiştirmesin
  • Çıktısı ana session’ı kirletmesin
# Dizin yapısı
mkdir -p .claude/skills/test-coverage

cat > .claude/skills/test-coverage/SKILL.md <<'EOF'
---
name: test-coverage
description: "Test coverage raporunu çıkarır, eşik altındaki dosyaları listeler"
context: fork
allowed-tools: Read, Grep, Glob, Bash
argument-hint: "[--threshold=80]"
---

Vitest coverage çalıştır:

!`pnpm test --coverage --reporter=json 2>/dev/null | tail -100`

Eğer `--threshold` verilmişse, threshold altındaki dosyaları listele. Yoksa default 80% kullan.
Bulguları tablo olarak döndür: dosya, line%, branch%, func%.
EOF

Doğrulama:

# Skill çağır
claude
> /test-coverage --threshold=75
# → Skill ayrı subagent'ta çalışır, vitest çıktısı ana session'a dökülmez,
#   sadece tablo döner. Edit/Write tool'u erişilemez olduğu için
#   hiçbir dosya değişmez.

Karşı senaryo (command versiyonu — fork istemiyoruz, kısa çıktı):

cat > .claude/commands/coverage-quick.md <<'EOF'
---
description: "Coverage özetini hızlıca basar"
allowed-tools: Bash
---

!`pnpm test --coverage 2>&1 | grep -E "(All files|Statements|Branches)" | head -10`
EOF

/coverage-quick ana session’da çalışır, output conversation’a yazılır, sonraki sorular bu datayı kullanabilir. Skill yerine command seçtik çünkü kısa.

Özet

  • Command: .claude/commands/<name>.md veya ~/.claude/commands/<name>.md. Tek prompt expansion.
  • Skill: .claude/skills/<name>/SKILL.md. Çok adımlı, izole çalışır.
  • context: fork: Skill ayrı subagent’ta çalışır, ana session temiz kalır. Verbose output için şart. Yazmazsan default = ana session’da çalışır.
  • allowed-tools: Minimum yetki prensibi. Listede yoksa tool çağrılamaz — güvenlik için kritik.
  • argument-hint: UI placeholder. Gerçek validation’ı prompt içinde yap.
  • Paylaşım: Project commands/skills commit edilir, user commands/skills kişiseldir.
  • Sınav formülü: “Çok tool + verbose + izole = skill + fork. Kısa + ana session’da görünsün = command.”

Kaynaklar