TypeScript Üretiminde Agent Skills Tasarımı

Merhaba arkadaşlar, AI kodlama araçlarında tek bir modelden daha fazlasını kontrol etmek istiyorsanız doğru yer burası. Agent Skills kodlama aracına yeni bir şey öğretmekten çok hangi iş akışını izleyeceğini ve üretilen kodun hangi kontrollerden geçeceğini tanımlar; bu yazımda TypeScript projesi için skill klasörü hazırlayacak ve kalite kontrolünü yayın kapısına dönüştüreceğiz.

Skill klasörü

En temel skill, içinde SKILL.md bulunan bir klasördür. Bu dosyanın başında YAML frontmatter, devamında ise ajanın uygulayacağı Markdown talimatları yer alır. Frontmatter içinde name ve description alanları zorunludur.

name alanı 1 ile 64 karakter arasında olmalı ve skill klasörünün adıyla eşleşmelidir. Genel Agent Skills spesifikasyonunda yalnızca küçük harf, rakam ve tire kullanılması isteniyor. description alanının uzunluğu ise 1 ile 1024 karakter arasında olmalı ve skill’in ne yaptığını kadar ne zaman kullanılacağını da açıklamalı. Çünkü ajan başlangıçta bütün talimatları okumuyor ve önce skill adlarını ve açıklamalarını görüyor.

Örneğin şu yapıyı oluşturabilirsiniz:

typescript-production/
├── SKILL.md
├── references/
│   ├── testing-patterns.md
│   └── security-checklist.md
├── assets/
│   └── prd-template.md
└── scripts/
    └── check-boundaries.mjs

SKILL.md dosyasında ajanın hangi aşamada hangi dosyayı açacağını ve hangi kontrolleri yapacağını açıklayın. Ayrıntılı test örneklerini references/ altına, PRD için tekrar kullanabileceğiniz şablonu assets/ içine ve kısa deterministik işlemleri scripts/ altında tutabilirsiniz. Agent Skills açıklamasına buraya tıklayarak bakabilirsiniz.

Örnek frontmatter şöyle olabilir:

---
name: typescript-production
description: TypeScript projelerinde hedefleri planlayan, ince dikey dilimlerle kod üreten, test ve güvenlik kontrollerini tamamlamadan yayınlamayan üretim akışını yürütür.
---

# TypeScript Production

## Define

Kod yazmadan önce hedefleri, proje yapısını, kullanılacak komutları,
kod stilini, testleri ve sınırları belirle.

## Plan

Kabul kriterleri ve bağımlılık sırası olan küçük görevler oluştur.

## Build

Her görevi ince dikey dilimler hâlinde uygula.
Önce testi yaz ve testin başarısız olduğunu doğrula.
Ardından uygulamayı yaz ve Red-Green-Refactor döngüsünü tamamla.

## Verify

Projede tanımlı test, lint, typecheck ve build komutlarını çalıştır.
Kontrolü atlamak veya testleri susturmak yasaktır.

## Review

Güvenlik, performans, sürdürülebilirlik, işlevsellik ve kalite eksenlerinde
değişikliği incele.

## Ship

Tüm kontroller geçmeden ve insan incelemesi yapılmadan yayınlama.

Bu dosyayı yazarken uzun vadeli uygulama kodunu skill içine koymayın. Skill ajanın izleyeceği yöntemi ve ihtiyaç duyduğu kaynakları paketler. Projenin kendi kodunu taşımak yerine mevcut araçları kullanması daha doğru olur. Kırılgan veya tekrar eden operasyonları küçük scriptlere dönüştürebilirsiniz fakat scriptler kısa ve deterministik kalmalı.

Bir başka önemli nokta da progressive disclosure yani bilgiyi kademeli açma yaklaşımı. Ajan önce yalnızca name ve description bilgisini görür ve görev skill ile eşleşirse SKILL.md yüklenir. Referans dosyaları talimatlarda gerçekten ihtiyaç duyulduğunda okunur. Scriptler ise doğrudan çalıştırılmaz ve ajan bunalrı talep ettiğinde çalıştırılabilir. Microsoft’un anlatımında bu süreç dört aşamalı olarak gösteriliyor.

Kaliteyi tanımlayan geliştirme akışı

Kalite kontrolünü modele yalnızca “daha dikkatli ol” demekle çözemeyiz. Bunun yerine skill içinde uçtan uca bir akış tanımlayın. Bana kalırsa Addy Osmani’nin paylaştığı skill koleksiyonundaki DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP aşamaları uygun bir çerçeve sunuyor. Bu akışı buraya tıklayarak inceleyebilirsiniz.

Kod yazmadan önce PRD hazırlamamız gerek. Burada yalnızca “bir endpoint ekle” yazmak yeterli değil. Komutları, proje yapısını, kod stilini, testlerin nasıl çalıştırılacağını ve nelerin kapsam dışında olduğunu açıkça belirtin. Planı daha sonra küçük ve doğrulanabilir görevlere bölün. Her görevin kabul kriteri ve bağımlılık sırası belli olduğunda ajan daha küçük değişikliklerle ilerleyebilir.

Uygulamayı ince dikey dilimler halinde yapmak da bana mantıklı geliyor. Önce test görünürlüğünü doğrulayın ve testin gerçekten başarısız olduğunu görün. Ardından kodu yazın. Böylece Red-Green-Refactor döngüsü yalnızca bir slogan olarak kalmaz ve geliştirme sırasında kaliteyi görünür kılar. Test dağılımı için 80/15/5 piramidini de kullanabilirsiniz. Çoğunluğu birim testlerine, ardından integration ve son olarak end-to-end testlerine ayırın.

Projeye özel ve sürekli değişen bilgileri skill yerine Rules veya CLAUDE.md gibi proje dosyalarında tutmak daha sağlıklı. Kod stili, kullanılan kütüphaneler ve sürümler, sorumluluklar ve temel komutlar proje bağlamına gidiyor. Skill ise bu bağlamın nasıl kullanılacağını ve kalite akışını taşıyor. Cursor’ın yaklaşımında da Rules kalıcı proje talimatlarını, Skills ise ilgili olduğunda yüklenen iş akışlarını ve alan bilgisini taşıyor. Rules ve Skills ayrımını burada görebilirsiniz.

Araçları güvenli sınırlandırmak

load_skill, read_skill_resource ve run_skill_script işlemlerini tek bir izin gibi düşünmek riskli. İlki skill talimatlarını yükler. İkincisi referans ya da asset okur ve üçüncüsü kod çalıştırır. Bu nedenle üçünü ayrı ayrı yetkilendirin. Bir skill’i okumak için izin vermek, kod çalıştırmak için izin vermekle aynı şey değil.

Microsoft Agent Framework varsayılanında bu üç işlem onay istiyor. Otomatik onay kurallarını yalnızca güvenilir kaynaklar ve incelenmiş skill’ler için kullanın. Buradaki önemli ayrım şu: bu davranış Microsoft Agent Framework’e özgü. Genel Agent Skills formatı için evrensel bir güvenlik kuralı gibi yorumlanmamalı.

Script çalıştıracaksanız üretim ortamı için sandboxing, CPU ve bellek sınırları, zaman aşımı, girdi doğrulama ve executable allow-list gibi kontrolleri değerlendirin. Structured loglama ile audit trail de olmalı. Script çökerse veya yanlış dosyayı değiştirirse sonradan neler olduğunu görebilmelisiniz.

Aşağıdaki gibi küçük ve anlaşılır hatalar üretmek de önemli:

import fs from "node:fs";

const target = process.argv[2];

if (!target) {
  console.error("Kullanım: node check-boundaries.mjs <klasör>");
  process.exit(1);
}

if (!fs.existsSync(target)) {
  console.error(`Hedef klasör bulunamadı: ${target}`);
  process.exit(1);
}

console.log(`Sınır kontrolü başlatıldı: ${target}`);

Bu kod gerçek bir kalite kontrolü değil fakat scriptlerin nasıl yazılması gerektiğini gösteriyor. Uzun bir iş mantığını agent’a yorumlatmak yerine kısa ve tek amaçlı bir işlemi script’e vermek daha güvenli. Script çıktısını okuyup hatayı düzeltmesi gerekiyor.

Kaynak kodunu, API anahtarlarını, müş müşterilerin verilerini veya fikrî mülkiyeti açık onay olmadan harici agent’larla paylaşmayın. AI tarafından üretilen kodun doğrulanması da geliştiricinin sorumluluğunda kalıyor. Agentic Coding Principles sayfasında bu sorumluluk açıkça vurgulanıyor.

Kaliteyi yayın kapısına dönüştürmek

Kalite eşiklerini skill’in içine gömülü birkaç cümleyle bırakmayın. CONSTRAINTS.md gibi sürüm kontrollü bir dosya oluşturup testlerin, lint, typecheck, güvenlik ve performans kontrollerinin nasıl değerlendirileceğini yazın. Kontrol atlanamaz ve testler yalnızca yeşil görünmesi için susturulamaz.

Güvenlik incelemesi OWASP Top 10, auth kalıpları, secret yönetimi, dependency audit’i ve sınır doğrulamasını kapsayabilir. Performans tarafında ise önce ölçün. Core Web Vitals hedefleri belirleyin, profiling yapın ve bundle analizi çalıştırın. Optimizasyonu hissiyata göre değil ölçüme göre yapmak gerekiyor.

Kod incelemesi için değişiklikleri yaklaşık 100 satır civarında tutmak genellikle daha okunabilir. Beş eksende ve severity etiketleriyle inceleme yapin. AI’ın ürettiği kod anlaşılmadan ve kapsamlı testlerle doğrulanmadan sisteme alınmamalı. Diff’i yalnızca “testler geçti” diye onaylamak yerine güvenlik, hata durumları ve bakım maliyeti açısından da okuyun.

Not: 500 satır sınırı konusunda kaynaklar arasında küçük bir fark var. Microsoft belgesi bunu zorunlu tutarken genel Agent Skills spesifikasyonu ve en iyi uygulamalar bunu öneri olarak ifade ediyor. Benzer şekilde varsayılan onay davranışı da genel formatın zorunlu kuralı değil ve Microsoft Agent Framework uygulamasının davranışı. Skill’i taşınabilir tutmak istiyorsanız bu farkı göz önünde bulundurun.

Pratik olarak önce SKILL.md dosyasını küçük tutun ve akışı uçtan uca tanımlayın. Daha sonra references/ altına yalnızca gerçekten ihtiyaç duyulan belgeleri ekleyin. En sonda ise script çalıştırma ve otomaitk onay yetkilerini ayrı ayrı gözden geçirin. AI’ye daha çok şey yüklemek yerine doğru güvenlik sınırıyla neyi ne zaman yapacağını öğretmek daha sağlıklı bir üretim yaklaşımı.

Kurulum ve yaklaşım bu kadar. Skill’i taşınabilir tutmak için script ve otomatik onay yetkilerini ayrı ayrı gözden geçirmeyi unutmayın. Yardımcı olabildiysem ne mutlu bana :)

Kaynaklar

• addyosmani/agent-skills: Production-grade engineering skills for AI coding agents. (GitHub)

• Agent Skills Overview (Agent Skills)

• Agent Skills (learn.microsoft.com)

• Agent Skills (Claude Platform Docs)

• Specification (Agent Skills)

• GitHub - anthropics/skills: Public repository for Agent Skills (GitHub)

• Best Practices for Creating Agent Skills (GitHub)

• Agentic Coding Principles & Practices (agentic-coding)

• Best practices for coding with agents (Cursor)