Komut satırı aracını güvenli bir ajan becerisine dönüştürmek

Çoğu ekip, bir ajanın ihtiyaç duyacağı araçlara zaten sahiptir: bir dağıtım betiği, bir veritabanı sorgulama aracı, bulut sağlayıcısının CLI'ı, faturaları çeken şirket içi bir araç. Kabuk erişimi olan bir ajan bunların hepsini çağırabilir; ama çıplak bir kabuk ajana çok fazla güç, çok az yol gösterme verir. Ajan bayrakları tahmin etmek zorunda kalır, insanlar için yazılmış çıktıyı ayrıştırmaya çalışır ve zararsız alt komutun hemen yanında duran yıkıcı olanı çalıştırmasını hiçbir şey engellemez. CLI'ı bir beceri olarak sarmalamak bu sorunu çözer. Bu rehber, tek bir araç üzerinden neyin açılacağına karar vermekten, kimse sonuca güvenmeden önce test etmeye kadar bütün adımları anlatıyor.

Beceri, CLI'ın üstüne ne ekler

Bir komut satırı aracının zaten bir arayüzü vardır. Beceri ise dikkatli bir meslektaşın getireceği bilgiyi ekler: bu araç ne zaman doğru seçimdir, hangi soruyu hangi komut yanıtlar, hangi bayraklar her zaman verilir, çıktı ne anlama gelir ve bir şey ters gittiğinde ne yapılır. Yaygın SKILL.md biçiminde bu bilgi bir klasörde durur: ajanın baştan gördüğü kısa bir açıklama, yalnızca ilgili olduğunda yüklediği talimatlar ve isteğe bağlı yardımcı betikler. Biçimin kendisini ajan becerileri nedir yazısı anlatıyor; bu sayfa sarmalama işine odaklanıyor.

Her CLI iyi bir aday değildir. Başlamadan önce şu özelliklere bakın:

• Etkileşimsiz bir mod; bir tuşa basılmasını bekleyen istemler olmamalı.
• --json ya da --format gibi makinenin okuyabileceği bir çıktı seçeneği.
• Anlamlı çıkış kodları; başarı ile hata, metin okumadan ayırt edilebilmeli.
• Tekrar tekrar çalıştırılması güvenli okuma komutları.

Tam ekran etkileşimli araçlar, düzenleyici açan komutlar ve varsayılan eylemi yıkıcı olan araçlar, önlerine bir sarmalayıcı betik koymadığınız sürece uygun aday değildir.

1. adım: komut yüzeyini çıkarın

Alt komutları listeleyin ve her birini okuma, yazma ya da yıkıcı olarak sınıflandırın. Aşağıda invoicectl adlı varsayımsal bir şirket içi faturalama aracının haritası var:

İlk sürüm yalnızca okuma komutlarını açar. Bu bir çekingenlik değildir: ajanın yaptığı herhangi bir şey bir müşteriye ulaşmadan ya da bir kaydı silmeden önce, aracı gerçekte nasıl kullandığını öğrenmenizi sağlar.

2. adım: önce açıklamayı yazın

Becerinin ne zaman yükleneceğine açıklama karar verir; bu yüzden kısalığının düşündürdüğünden çok daha fazla özeni hak eder. Aracın ne yaptığını, hangi soruları yanıtladığını ve en az bunlar kadar önemli olarak, ne zaman kullanılmaması gerektiğini yazın. İnsanların gerçekten yazdığı sözcükleri kullanın.

---
name: invoice-lookup
description: invoicectl CLI ile şirket içi faturalama sisteminde fatura
  sorgular (salt okunur). Bir faturanın durumu, tutarı, vade tarihi ya da
  müşterisiyle ilgili sorularda veya müşteriye ya da döneme göre fatura
  listelemek için kullan. Fatura göndermek, iptal etmek ya da dışa
  aktarmak için kullanma.
---

# Fatura sorgulama

Her zaman --json ve --no-color ver. send, void ya da export asla çalıştırma.

## Fatura bul
invoicectl list --customer "<ad>" --status open --limit 50 --json

## Tek bir faturayı göster
invoicectl show <fatura-id> --json

## Sonuçları okuma
- "status" şunlardan biridir: draft, open, paid, void
- Boş liste hata değil, eşleşme yok demektir. Bunu açıkça söyle.
- Çıkış kodu 3 kimlik doğrulanmadı demektir: dur ve bildir, yeniden deneme.

Gövdeyi kısa ve somut tutun. Uzun arka plan bilgisi, ajanın yalnızca ihtiyaç duyduğunda açtığı ayrı bir referans dosyasına aittir.

3. adım: girdileri ve çıktıları netleştirin

Talimatlar belirsiz kaldığında ajanlar bayrak uydurur. Buna hiç yer bırakmayın.

• Zorunlu girdileri ve biçimlerini yazın: bir fatura kimliği neye benzer, bir dönem nasıl yazılır.
• Her zaman bulunması gereken bayrakları sabitleyin: yapılandırılmış çıktı, renksiz çıktı, sayfalayıcı yok, etkileşim yok.
• Çıktıyı sınırlayın. Binlerce satır döndürebilen bir komut ajanın bağlamını boğar. Varsayılan bir limit koyun ve geri kalanında nasıl sayfalanacağını açıklayın.
• Hataların nasıl okunacağını anlatın. Çıkış kodlarını ve sık görülen hata mesajlarını bir eyleme bağlayın: yeniden dene, kullanıcıya sor ya da dur.
• Dışarıdan gelen değerleri tırnak içine alın. Bir kişinin verdiği ya da bir dokümanda bulunan her şey bir argümana gider; kabuğun yorumlayacağı bir metnin içine asla girmez.

Ham CLI bunları zorlaştırıyorsa beceri klasörüne ince bir sarmalayıcı betik ekleyin. Sarmalayıcı argümanları doğrular, sabit bayrakları ekler, uzun çıktıyı kırpar ve temiz bir hata döndürür. Beceri de ajana CLI yerine bu sarmalayıcıyı çağırmasını söyler.

4. adım: güvenli yolu varsayılan yapın

Talimatlar yol gösterir, zorlamaz. "void asla çalıştırma" diyen bir cümleye genellikle uyulur; ama genellikle, her zaman demek değildir. Kesin sınırları, ajanın ikna yoluyla aşamayacağı bir yere koyun.

• İlk sürümde salt okunur bir kimlik bilgisi kullanın; böylece ajan denese bile yazma komutu serviste başarısız olur.
• Sarmalayıcıda alt komutlar için bir izin listesi tutun ve geri kalan her şeyi açık bir mesajla reddedin.
• Yazma eklediğinizde kuru çalıştırmayı tercih edin: önce önizleme, ancak bir karardan sonra uygulama.
• Gizli bilgileri becerinin dışında tutun. Kimlik bilgileri SKILL.md'den ya da depoya işlenmiş bir yapılandırma dosyasından değil, ortamdan ya da bir gizli bilgi kasasından gelir.
• Zaman aşımı koyun; takılan bir komut bütün çalıştırmayı kilitlemesin.

Salt okunur sürüm güven kazandığında yazma komutlarını birer birer ve her birini açık bir onay adımının arkasına koyarak ekleyin. Bu ilerleyişi ajanlara salt okumayla başlayın yazısı anlatıyor.

5. adım: yalnızca aracı değil, beceriyi test edin

CLI zaten çalışıyor. Test ettiğiniz şey, ajanın onu doğru kullanıp kullanmadığıdır ve üç küçük test seti çok iş görür.

1. Yükleme testleri. Beceriyi tetiklemesi gereken birkaç istem ("1042 numaralı fatura ödendi mi?") ve tetiklememesi gereken birkaç istem ("bu müşteriye bir hatırlatma e-postası taslağı yaz"). Becerinin yalnızca ilk grupta yüklendiğini kontrol edin.
2. Çağrı testleri. Her okuma sorusu için ajanın çalıştırdığı komutu kaydedin ve beklediğinizle karşılaştırın. Eksik bayraklar, yanlış filtreler ve sınırsız sorgular hemen göze çarpar.
3. Hata testleri. Süresi dolmuş kimlik bilgisi, var olmayan bir kimlik, boş bir sonuç, erişilemeyen bir servis ve becerinin yasakladığı bir şeyi yapma isteği. Doğru sonuç net bir rapor ya da bir rettir; yeniden deneme döngüsü ya da uydurulmuş bir yanıt değil.

Bu istemleri depoda becerinin yanında tutun ve açıklama, sarmalayıcı ya da CLI sürümü her değiştiğinde yeniden çalıştırın. Gerekçesini söyleyen bir ret doğru bir sonuçtur; ret de bir sonuçtur yazısı bunu savunuyor.

İzinler aslında nerede durur

Beceri, ajana bir aracı nasıl kullanacağını söyler. Belirli bir işin o aracı kullanmasına izin verilip verilmediğine ise karar vermez, vermemelidir de. Bu karar ajanın çalıştığı ortama aittir: hangi kimlik bilgilerini taşıdığı, hangi eylemlerin bir insan için durduğu, neyin kayda geçtiği.

GoCux bu ikisini ayrı tutar. Yeniden kullanılabilir bir talimat hiçbir zaman izin yerine geçmez; bir beceri yazmak ya da kurmak hiçbir görevin yapabileceklerini genişletmez. Bir iş emri hedefi, kapsamı ve kabul ölçütlerini belirtir, işin gerektirdiği becerileri GoCux seçer; dışarıya bir şey göndermek, silmek ya da veri dışa aktarmak gibi sonuç doğuran eylemler yine bir ekip arkadaşı karar verene kadar durur. Müşteri CLI'ı kendi yerel araçlarının ve izinlerinin sahibi olarak kalır. Becerilerin bu modele nasıl oturduğunu ajan becerileri belgeleri anlatıyor.

Beceriyi paylaşmadan önce kontrol listesi

• Açıklama aracın ne işe yaradığını, hangi soruları yanıtladığını ve ne zaman kullanılmayacağını söylüyor.
• Açılan her komut sınıflandırılmış; ilk sürüm yalnızca okuma komutlarını açıyor.
• Sabit bayraklar, çıktı limitleri ve hata davranışı yazılı ya da bir sarmalayıcıyla zorunlu kılınmış.
• Kimlik bilgisi salt okunur ve beceri klasörünün hiçbir yerinde gizli bilgi yok.
• İzin listesi dışındaki alt komutlar açık bir mesajla reddediliyor.
• Yükleme, çağrı ve hata testleri var ve geçiyor.
• Yazma komutları eklendiğinde, çalışmadan önce açık bir karar gerektiriyor.
• Ne zaman beceri, ne zaman MCP sunucusu, ne zaman düz bir CLI çağrısı daha uygun, biliyorsunuz; bkz. MCP, beceri mi CLI mı.