Phase 13: Tools & Protocols

Ajan yetenekleri: Portable sözleşme ve çalışma süresi sınırları

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 13 · 01 (The Tool Interface), Phase 13 · 05 (Tool Schema Design)

Time: ~90 minutes

Öğrenme Hedefleri

• Bir ajan becerisini bir prompt, depot talimatları, bir araç, bir kanca, bir subagent veya bir eklenti ile karıştırmadan tanımlayın.
• Mobil cihazı oku .SKILL.mdSözleşme ve çalıştırma süresi özel uzatmalardan ayırmak.
• Bulma, seçim, etkinleştirme, kaynak yükleme, araç kullanımı ve doğrulama, yaşam döngüsü farklı aşamaları olarak açıklayın.
• Bir yetenek paketi, bir iş zamanının bir ajanın kataloguna yerleştirilmeden önce doğrulanmalıdır.
• Bir iş için bir beceri, MCP aracı, kanca, alt kod veya sıradan kod arasında seçim yapın.

On Dakikalık Başarılılık

Uzun açıklama yapmadan önce bunu yapın.

Tam bir incelemeci paketini gerçek bir ajan ev sahibi haline getirir, onu çağrıştırır,

Bu, yaşam döngüsünü gözlemlenebilir bir sonuçla kanıtlar.

Gerçek ev sahibi laboratuvarına uçuş öncesi.

Gerçek ev sahibi kontrol noktası Node.js'i gerektirir.npxPython 3, seçilmiş bir tane .

yetenekli bir host ve seçtiğiniz projeye veya kullanıcı alanına erişim yazın

Önce yerel komutları kontrol et:

bashCopynode --version
npx --version
python3 --version

Kurulumdan önce hangi host ve kapsamı kullanacağınızı belirleyin.

Bu dersleri web sitesinde okuyun veya devam edin

Bu geri dönüş sözleşmeyi öğretir, ama

host keşifini, çağrıyı, paketli metin uygulanmasını kanıtlamıyor veya

Bu gözlemleri bekleyen olarak işaretle.

1. Boş bir çalışma dizininden başlayın

Çalışmayı öğrenmeye devam ettiğiniz herhangi bir ana dizininden bu komutları çalıştırın:

bashCopymkdir -p agent-skills-first-run
cd agent-skills-first-run
TARGET_ROOT="$(pwd -P)"
printf 'TARGET_ROOT=%s\n' "$TARGET_ROOT"
ls -A

Son komut hiçbir şey yazdırmamalı.

Bu yüzden incelemenin açık bir sınırı var.

İlk yeteneğin için bir dizin oluştur:

bashCopymkdir -p my-first-skill

Yaratmakmy-first-skill/SKILL.mdBu içeriği ile:

markdownCopy---
name: my-first-skill
description: Turn rough meeting notes into a compact decision record when the user asks to capture a technical decision.
---

# Decision record

Extract the decision, context, alternatives, owner, and next review date.
If the notes do not contain a decision, ask one clarifying question instead
of inventing one.

Dosyayı amaçlı dizide oluşturduğunuzdan emin olun:

bashCopytest -f my-first-skill/SKILL.md

Çıkış kodı 0 yok, dosya var demektir.

2. Tam incelemeci paketini yükle

İçeride kalın .agent-skills-first-runve koş:

bashCopynpx skills add rohitg00/ai-engineering-from-scratch --skill skill-contract-reviewer --full-depth

Kullanmakta olduğunuz ajan host ve kapsamını seçin.

skill-contract-reviewerVe yazdığı yer.--full-depth-

Bu ders yeteneği referanslarla bir yuva bir paket,

Senaryo ve bir sermaye.

Yapıştır SKILL_ROOTKurulucu tarafından bildirilen mutlak dizinine.

Kurulmuş olan dizin olması SKILL.md, ders kaynağı değil

Dizin ve mevcut çalışma alanı değil:

bashCopy# Replace the placeholder with the destination printed by the installer.
SKILL_ROOT="$(cd "/absolute/path/to/skill-contract-reviewer" && pwd -P)"
test -f "$SKILL_ROOT/SKILL.md"
printf 'SKILL_ROOT=%s\n' "$SKILL_ROOT"

Eğer ajan seansı zaten açılmışsa, yeni bir seans başlatın veya o ev sahibi'nin

Her ev sahibi katalogunu sıfır yeniden yükler diye düşünmeyin.

3. Açıkça çağırın.

Kurulmuş ajanın içinde, agent-skills-first-runişçi olarak

Dizin, host tarafından desteklenen sentaks kullanın:

için yazdırılan mutlak değerleri kullanınSKILL_ROOTve TARGET_ROOT- ...

Uygulama işleminden önce ev sahibi tarafından genişletilmesini ve tam olarak

çözülmüş komut, işlem çalışma dizine bağlı olmayan bir komut değil:

textCopyUse skill-contract-reviewer to review <TARGET_ROOT>/my-first-skill. The installed bundle root is <SKILL_ROOT>. Run python3 <SKILL_ROOT>/scripts/check_skill.py <TARGET_ROOT>/my-first-skill. Before running it, show the fully resolved argv. Return the validation report, selected primitives, and one sentence for each selection. Include the resolved script path, resolved target path, cwd, argv, and exit code as execution evidence.

Çözümlü komut, yer tutmayan şekilinde olmalıdır:

bashCopypython3 "/absolute/install/path/skill-contract-reviewer/scripts/check_skill.py" \
  "/absolute/workspace/path/agent-skills-first-run/my-first-skill"

Başarılı bir sonuç üç özellikten de oluşur:

1. Ev sahibi buldu .skill-contract-reviewerAdıyla.
2. Değerlendirici paket sözleşmesini okuyor ve paket onaylayıcıyı çalıştırıyor.
3. Cevap, yapısal hata olmadan onay raporu içerir.

Örnek, ek olarak haklı bir ilkel seçim.

Yaptıkları kanıtlarda senaryo yolu, hedef yolu, cwd, tam adı da bulunmalıdır.

Bu alanlar olmadan akıcı bir rapor

Kurulan eş metni çalıştırdığını kanıtlayın.

Ev sahibi yeteneğin bulunmadığını bildirirse, kurulumunu doğrulayın

hedef, bir kez yeniden tarayın veya yeniden başlatın ve açıkça yapılan talebi tekrar deneyin.

Kurulum başarısızlığını gizlemek için beceri tanımını yeniden yazmak.

4. Sönem içeren seçim

Yeni bir ajan dönüşü başlatın ve yeteneği isimlendirmeden aynı görevi girin:

textCopyReview <TARGET_ROOT>/my-first-skill as a reusable agent package and tell me whether its package contract is valid.

Ev sahibi seçilen becerileri ortaya çıkarırsa, seçtiğini kaydet

skill-contract-reviewerEv sahibi yönlendirmeyi açığa çıkarmazsa,

Açıkça çağrıda taşınabilir geri dönüş bulunmaktadır.

5. Temizle.

Sadece yüklenen incelemeci paketini kaldır:

bashCopynpx skills remove skill-contract-reviewer

Kurulum sırasında kullanılan aynı host ve kapsamı seçin.

Sessiyon, açık bir şekilde istekskill-contract-reviewerrapor etmelidir.

• Bu kullanılamıyor.my-first-skillSonraki dersler için veya

Yolu bitirdikten sonra laboratuvar dizinine.

Sorun

Ekibinizin güvenilir bir yayın iş akışı olduğunu varsayalım. Birleştirilmiş değişiklikleri bulur, göç notlarını kontrol eder, değişim kaydı güncelleyir, bir paket komutu çalışır ve bir inceleme kontrol listesini oluşturur.

Bu iş akışını bir istekle koymanın yapıştırması kolay ve çalıştırılması zor hale getirir. istekle sabit bir kimliğe, keşif kuralına, kaynak sınırına, test edilebilir paket şekline ve temel soruların cevabına sahip değildir: Kim çağırabilir? Modelin ne zaman seçmesi gerekir? Hangi senaryoları çalıştırabilir? Hangi dosyalara güvenilir?

Bu nedenle, her tekrar kullanılabilir talimatı bir beceri olarak değerlendirmek yanlış bir şeydir. deposu konvansiyonları, belirleyici otomasyon, dış araçlar, olay hakları ve delegasyonlu ajanlar farklı sorunları çözüyor.SKILL.mdbir ev sahibi'nin belgelenmemiş davranışına bağlı olarak taşınabilir görünen bir dizin oluşturur.

İlk mühendislik görevi sınıflandırma. Nasıl paketleneceğine karar vermeden önce eserin ne olduğunu belirleyin.

Anlaşım

Yetenekler prosedürel bilgiyi kodlamaktadır

Bir ajan yeteneği , giriş noktası olan bir dizindir .SKILL.md. Giriş dosyası, YAML ön maddesini ve ardından Markdown talimatlarını içerir. Dizin ayrıca referanslar, senaryolar ve varlıkları da içerebilir.

Markdown dosyası değil, dizin, dağıtılabilir birimdir.SKILL.mdKayıp referansları olan bir paket, ön malzemesi analiz edilse bile kırılmış.

Komşu soyutlamalar

Bir serbest bırakma becerisi, ajanın bir serbest bırakmayı nasıl inceleyeceğini söyleyebilir. Bir MCP sunucusu serbest bırakma kayıtlarını ortaya koyabilir. Bir kanca doğrudan itmeyi yasaklayabilir. Bir alt görevli adayı bağımsız olarak denetebilir. Bu parçalar farklı sorumlulukları taşıdığı için oluşturulur.

"İltibat" kelimesi iki farklı fikre atfeder.

Araştırma sistemleri bazen öğrenilmiş bir programa, başarılı bir yoldaki veya çevreye özgü bir politika fragmanı bir beceri olarak adlandırır. Bir ajan, keşif sırasında bu eserleri oluşturabilir, görev benzerliğiyle geri alabilir, uygulayabilir ve kitaptaki geri bildirimleri gözden geçirebilir.

Bu mini-track'deki Agent Yetenek farklıdır. Bu, açıklanan dosya sistem sözleşmesi, katalog metadata, ilerici açıklama, çalıştırma zaman aracılığıyla çağrı ve host kontrolü araçları ile birlikte yazılmış bir paketdir.

Her iki fikir de tekrar kullanılabilir yetkinlik paketini içerir.

Uygulanabilir çekirdek

Agent becerileri özellikleri iki ön madde alanı gerektirir:

yamlCopy---
name: release-readiness
description: Inspect a release candidate when the user asks whether a version is ready to publish.
---

nameBu özelliklerin isimlendirme kurallarına uymalı ve ana dizinle eşleşmelidir. descriptionBu bilgi, yeteneklerin ne yaptığını ve ne zaman uygulanacağını belirtmelidir.

Aktarılabilir seçeneği alanlar:

Markdown organı, iş akışı, karar noktaları, başarısızlık davranışları ve destek kaynaklarına doğrudan yolları tanımlamalıdır.

markdownCopy# Release readiness

Use this workflow for a release candidate, not for ordinary development builds.

1. Read `references/release-policy.md`.
2. Run `python3 scripts/inspect_release.py --format json`.
3. Stop if the report contains a blocking failure.
4. Produce the checklist from `assets/release-checklist.md`.
5. Ask for approval before any publish or tag action.

Çalışma süresi uzantıları ikinci katman

Bazı ev sahipleri ek ön madde veya eş yapılandırmayı kabul eder. Bu alanlar yararlı olabilir, ancak otomatik olarak taşınabilir değildir.

Her uzantıyı bir adaptör olarak değerlendirin. Temel iş akışını geçerli tutun, düşüşü belgeleyin ve onu tüketen barındırmayı test edin. Bir çalıştırma zamanı bilinmeyen bir alanı görmezden gelebilir, reddedebilir veya davranışları uygulamadan koruyabilir.

Ön madde , çalıştırılabilir metadata

Metadata, beceri kurumu okumanın öncesinde sistem davranışını değiştirir.

• Bir bozukluk .namekeşif başarısız olabilir.
• - Kısıtlı .descriptionyanlış istekleri yönlendirebilir.
• Sadece insan bayrağı, modelin kataloğundan yeteneği çıkarır.
• Bir araç tahsisinin sahibi izin istemesini değiştirebilir.
• Bir bağlam ayarı, yürütmeyi ayrı bir ajan oturumuna taşıyabilir.

Konfigurasyon kodu gibi ön maddeyi gözden geçirin. Onu doğrulayın, versiyon verin ve davranışlarını değerlendirmelere dahil edin.

Yetenek yaşam döngüsü

Her ok kendi başarısızlık modlarına sahip bir sınırdır.

1. Discoveryyapılandırılmış yerlerde olası paketler bulur.
2. ValidationKatalog yayınlanmadan önce yanlış biçimlendirilmiş veya güvenli olmayan paketleri reddeder.
3. Cataloging- ... bir kompaktı ortaya çıkarır .nameve description- Tam paket değil.
4. Selectionyetkinliğin uygun olup olmadığını belirler.
5. ActivationVücudun model görebilir bir bağlamına yüklenmesi.
6. Disclosurereferansları veya varlıkları yalnızca bir şubenin ihtiyaç duyduğu zaman okuyor.
7. Executionhost araçlarını host'ın izin ve izole kuralları altında kullanır.
8. Verificationüretilen eser, modelin iddialarından bağımsız olarak kontrol edilir.

Bu aşamaların çökmesi kötü zihinsel modellere neden olur. Bulunan bir beceri aktif değildir.

Bilgiler ve araçlar ortogonal

MCP, "Bu uygulama hangi yetenekleri arayabilir ve onların şemaları nelerdir?" diye cevap verir.

Bu özellik bir aracı adlayabilir, ancak ev sahibi gerçek yetenek kayıtlarına sahip. Eğer araç yoksa, yetenek bir düşüş veya başarısızlık belirtmelidir. Bu asla bir yeteneğin adının oluşturulduğunu ima etmelidir.

Bilgiler ve deposu talimatları farklı alanlardır

Depo talimatları zaten bulunduğunuz ortamı tanımlar: komutlar, konvansiyonlar, oluşturulan dosyalar ve sınırlar. Bir beceri birçok depose içinde oluşabilecek bir görev için tekrar kullanılabilir bir prosedür sağlar.

Her ikisi de geçerli olduğunda, aktif kullanıcı talebi ve deposu kuralları beceriyi kısıtlar.

Yetenekler birbirini içeri almaz

Bir beceri ajanı diğerini çağrıştırmaya yönlendirebilir, ancak bu dil düzeyinde bir ithalat değildir. İkinci beceri hala çalıştırma süresi keşfi, uygunluk, etkinleştirme, izinler ve bağlam yönetimi yoluyla geçer.

Gözetilebilir iş akışı kenarları olarak beceri arası bağımlılıkları yazın:

markdownCopyAfter producing the candidate changelog, invoke the `release-risk-review` skill.
Pass the candidate path and require a blocking or non-blocking verdict.
If that skill is unavailable, stop and report the missing dependency.

Bu bağımlılığı test edilebilir hale getirir ve ev sahibi politikaları uygulamaya geçirme şansı verir.

Yapın

code/main.pyBu sistem, standartlara yönelik küçük bir onaylayıcı ve bir eser seçicisi uyguluyor.

Validasyoncu aşağıdakileri ortaya çıkarır:

• parse_frontmatter(text)Metadataları vücuttan ayırmak için.
• validate_skill_text(text, directory_name, allowed_runtime_extensions=())Gerekli alanları, isimlendirme, bilinmeyen uzantıları, vücut varlığı ve taşınabilir sınırları kontrol etmek için.
• ValidationIssueve SkillReportBir çürük boolean yerine yapılandırılmış kanıtları geri göndermek.
• FrontmatterSyntaxErrorGüvenli bir şekilde yorumlanamayacak bir giriş için.

Seçiciler açığa çıkarır TaskShapeve select_primitives(task)Bir görevin ihtiyaçlarını sıradan kod, depot talimatları, bir beceri, bir kanca, bir alt-gen veya bir MCP aracı ile haritasıyor.

Laboratuvarı çalıştır:

bashCopycd "$(git rev-parse --show-toplevel)"
cd phases/13-tools-and-protocols/22-skills-and-agent-sdks
python3 code/main.py
python3 -m unittest discover -s code/tests -v

Bu komut blokuna yerel bir klon gerek ve içeriden herhangi bir yerden başlamalı .

Bu klon öyle.git rev-parse --show-topleveldeposu kökü çözmek için.

Demo, bir geçerli taşınabilir beceri, bir host genişletilen beceri, bir geçersiz paket ve birkaç görev biçimi kararı için JSON yazdırırır. Sorun kodlarını inceleyin.

Valide etmem için gerekli olan emirler

Daha derin içeriği kurallarından önce ucuz yapısal gerçekleri doğrulayın:

Bu sıralama ikinci hataların ilk kırık değişkenini gizlemesini engeller.

Kullan

Bir beceri yazmadan önce, bu karar kartını doldurun:

Birçok üretim iş akışı birden fazla satır kullanır. Kart bir eser her mülkiyet sağlıyor gibi davranmasını engeller.

Gönder

Bu ders , skill-contract-reviewerAltında bir paketoutputs/İçeriğinde:

• bir taşınabilirSKILL.mdönerilen beceri paketini gözden geçirir;
• taşınabilir sözleşme ve ilkel seçim için referans kontrol listeleri;
• Determinizm doğrulama metni;
• Görev şekli, istekleri, becerileri, araçları, hakları, sıradan kodları ve alt kısımları kapsayan cihazlar.

Sadece giriş dosyası değil, tüm paketleri yükle:

bashCopycd "$(git rev-parse --show-toplevel)"
python3 scripts/install_skills.py /tmp/aiefs-skills --phase 13 --type skill

Kurs yükleyici, her kopyalanan 13. aşama yeteneğini rapor eder ve yazar:

/tmp/aiefs-skills/manifest.jsonBu temiz yer paket şeklini kontrol eder .

Yukarıdaki ilk başarı döngüsü gerçek bir ev sahibi içinde keşif ve çağrı kontrol eder.

Aşağıdaki dersler yaşam döngüsünün her aşamasını derinleştirir. 24 ders keşif ve ilerleyici açıklama oluşturur. 25 ders çağıran politika ve yönlendirme oluşturur. 26 ders, izinleri kum kutularından ayırır. 27 ders tüm paketi değerlendirilmiş bir serbest bırakma eseri haline getirir.

Egzersizler

1. Kendi ekibinizden beş iş akışını sınıflandırın .TaskShapeBirden fazla ilkel seçtiğin her davası savunabilirsin.
2. 500 karakterli bir testin olduğunu kanıtlayan sınırlar testlerini ekleyincompatibilitydeğer geçer ve 501 karakterlik bir değer bir özellik hatası olarak başarısız olur.
3. İzin listesine bir çalıştırma süresi uzantısı ekleyin. Aynı dosyanın sadece taşınabilir bir beceriyle hala ayırt edilebilir olduğunu kanıtlayan bir test yazın.
4. 400 satırlı bir istekle bölün .SKILL.mdBir referans, bir senaryo sözleşmesi ve bir çıkış şablonu.
5. Bir MCP aracı bulunmayan bir beceri için bir başarısızlık tepkisi tasarlayın.
6. Var olan bir beceriyi gözden geçirin ve her cümleyi yönlendirme, prosedür, politika, referans işaretçisi veya çıkış sözleşmesi olarak etiketleyin.

Anahtar Terimler

Daha Fazla Okumak

• Agent Skills specificationtaşınabilir dizin ve ön ürün sözleşmesi için.
• Agent Skills best practiceskapsam, talimatlar ve kaynak örgütlemesi için.
• OpenAI: Build skillsCodex'un mevcut keşif ve çağrı davranışları için.
• Claude Code skillsBir çalıştırma süresi için çağrı, argüman, araç ve delegasyonlu bağlam uzantıları.

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.