Beceri yazma

Beceri, asistanın adımları her seferinde baştan çıkarmak yerine çağırabildiği, adı olan bir prosedürdür. Hafıza kayıtları asistana neyin doğru olduğunu söyler. Kurallar neyi yapmaması gerektiğini söyler. Beceriler ise belirli bir işi adım adım nasıl yapacağını anlatır.

Bu sayfada ne zaman beceri yazmanız gerektiği, bir becerinin içinde neler bulunduğu ve becerilerin nasıl saklanıp bağlandığı anlatılıyor.

Ne zaman beceri yazmalı

Aynı kalıbın tekrarlandığını fark ettiğinizde beceriye başvurun. İşaret şudur: "asistan hep aynı adımları tek tek yürütüyor ve bazen birini atlıyor".

• Operasyonel prosedürler. "Bir Stripe webhook'unu yerelde yeniden oynat." "Seed fixture'larını yeniden üret." "Sürüm öncesi kontrol listesini çalıştır."
• Özel iş akışları. "Doğru etiketler ve doğru gözden geçirenlerle taslak bir PR aç." "Sürümü artır, etiketle ve push et."
• Alana özgü yönlendirme. "Yeni bir analitik olayını uçtan uca oluştur: kolon, tip, dashboard."

Kalıp bir iki satırdan ibaretse hafıza kaydı yeterlidir. Prosedür üçten fazla adım içeriyorsa ya da "bunu bu sırayla yap" türünden herhangi bir gereklilik taşıyorsa beceri kullanın.

Kaynaklar

Her beceri kaydı, gövdesinin nerede durduğunu Pathrule'a söyleyen bir kaynak değeri taşır.

• manual. Gövde doğrudan Pathrule'da yazılır ve olduğu gibi saklanır. Varsayılan budur. Prosedürün tamamen çalışma alanına ait olmasını istediğinizde bunu kullanın.
• template. Pathrule'un sağladığı bir başlangıç becerisidir; çalışma alanına kopyalanır ve orada düzenlenebilir.
• github_ref. Beceri harici bir GitHub URL'sine işaret eder. Güvendiğiniz beceri ekosistemlerinin yayımladığı beceriler için bunu kullanın.

github_ref becerilerinde çalışma alanı, o kaynaktan alınan gövdenin bir snapshot'ını tutar ve beceri çalışma alanında salt okunurdur: VS Code bunun yerine kaynağı düzenlemenizi söyler.

SKILL.md yapısı

Beceri, frontmatter ve ardından gelen prosedür gövdesinden oluşan küçük bir Markdown dosyasıdır.

---
name: replay-stripe-webhook
description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling.
---

# Replay a Stripe webhook

Use this when a payment event from production needs to be reproduced locally.

## When to invoke

- A customer reports a missing receipt and you have the event id.
- You are debugging a webhook handler change.

## Procedure

1. Find the event in Stripe Dashboard. Copy its id.
2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`.
3. Watch the local handler. It must accept and process the event without double charging.
4. If the handler returns 5xx, the customer support page is the next stop, not a retry.

## What NOT to do

- Do not replay against production webhooks.
- Do not skip the idempotency key check.

Frontmatter'da name ve description bulunmak zorundadır. Altındaki her şey asistanın izlediği gövdedir. Gövde gerektiği kadar kısa ya da uzun olabilir.

Bağlama

Beceri, tıpkı bir kural gibi tek bir çalışma alanı yolunda durur. Onu prosedürün en ilgili olduğu yola koyun. Webhook yeniden oynatma becerisi services/billing/webhooks yoluna gider. Sürüm becerisi çalışma alanının köküne gider. Adı çalışma alanındaki mevcut bir beceriyle aynı olan yeni bir beceri reddedilir; bu yüzden ikinci bir kopya eklemek yerine mevcut olanı güncelleyin.

Asistan becerileri, Pathrule'un bir yol için ilettiği bağlam üzerinden (hafıza kayıtlarını ve kuralları keşfettiği şekilde) pathrule_get_context aracılığıyla keşfeder ve birini pathrule_read_skill ile eksiksiz okur. Senkronizasyon sırasında Pathrule becerileri, onları okuyan istemcilerin beceri klasörlerine de yazar; örneğin Claude Code için .claude/skills, Codex için .agents/skills.

::skill-name ile bir beceriyi istediğiniz anda çağırın

Asistan çoğu zaman doğru beceriyi kendisi seçer. Belirli bir beceriyi zorlamak istediğinizde prompt'unuzun herhangi bir yerine :: ve ardından beceri adını yazın; örneğin ::release-check ya da ::replay-stripe-webhook. O tur boyunca asistan, adı verilen beceriyi izlenmesi zorunlu bir iş akışı olarak ele alır; uzun talimatlar yazmanıza gerek kalmaz. Claude Code ve Codex'te ajan işe başlamadan önce prompt hook'u bu işareti yakalar; diğer istemcilerde ise asistan aynı talimatı MCP üzerinden bağlam istediğinde alır.

Hata durumunda güvenli tarafta kalacak şekilde tasarlanmıştır:

• Ad birden fazla beceriyle eşleşirse tahmin yürütülmez, hiçbir beceri çağrılmaz.
• Ad hiçbir beceriyle eşleşmezse asistana durması ve herhangi bir şeyi düzenlemeden önce durumu sizinle birlikte netleştirmesi söylenir. Asistan yayımlanmış adaylar önerebilir ve bunlardan birini çalışma alanına eklemeden önce onayınızı bekler.
• button::before ya da std::vector gibi kod benzeri :: kullanımlarını yok sayar; böylece sıradan prompt'lar yanlış yorumlanmaz.

Bu sayede ::skill-name, bilinen bir ekip prosedürünü yoldan bağımsız olarak o anki tura hızlıca dahil etmenin bir yolu olur.

Yazım akışı

İki akış da aynı yere çıkar.

• Elle yazım. VS Code'da doğru yolda New Skill… seçeneğini kullanın ve SKILL.md gövdesini yazın. Terminalden pathrule skill add --path /services/billing/webhooks --name replay-stripe-webhook --description "Replay a Stripe webhook locally" komutunu çalıştırın; --body verilmezse CLI düzenleyicinizi açar.
• Asistanla yazım. Claude Code'da (ya da herhangi bir MCP istemcisinde) kullanıcı asistandan "bunu bir beceriye dönüştür" ister. Asistan küçük bir beceri oluşturma kalıbı izler: amacı anlar, kullanıcıya sorular sorar, SKILL.md taslağını hazırlar ve ardından tam gövdeyle pathrule_write_skill çağrısını yapar.

Hemen kalıcı bir kayıt istemediğiniz durumlarda asistan beceri taslağını konuşma içinde hazırlar ve pathrule_write_skill çağrısını yapmadan önce onay bekler. Dolayısıyla kalıcı hale gelen kayıt, arka planda sessizce yazılmış bir şey değil, gözden geçirilmiş taslaktır.

Sürümleme ve eşzamanlı düzenlemeler

Beceriler de hafıza kayıtları ve kurallar gibi bir sürüm token'ı taşır. Aynı beceriyi düzenleyen iki ekip arkadaşı birbirinin değişikliğinin üzerine yazmaz, bunun yerine düzgün bir çakışma oluşur; VS Code'da sunulan çakışma seçenekleri bir hafıza kaydındakilerle aynıdır.

Kaçınılması gereken kalıplar

• Aslında hafıza kaydı olan beceriler. Gövde "çalışma şeklimizle ilgili şu doğru" diyorsa onu bir hafıza kaydı yapın.
• Aslında kural olan beceriler. Gövde "asla X yapma" diyorsa onu bir kural yapın.
• Çok fazla iş yapan tek bir beceri. Prosedürün birbirinden ayrı iki giriş noktası varsa onu adı olan iki beceriye bölün.
• Güvenmediğiniz harici becerileri çekmek. Bir github_ref becerisi, asistanınızın talimatları içinde çalışan koddur. Ona bir bağımlılık gibi davranın.

Yerel ve Cloud'da yazım

Bu sayfadaki terminal add örnekleri Cloud çalışma alanı içindir. Yerel modda kayıtları Local Console üzerinden, VS Code'da ya da yerel MCP aracılığıyla oluşturup düzenleyin; CLI bilgi komutları ise bunları listeler, okur ve arar.

Sırada ne okumalı

• Bilgiler ve kararlar için Hafıza kayıtları yazma.
• Kısıtlar için Kural yazma.
• Asistanın beceri yazmak için kullandığı araçlar için MCP araçları referansı.