Phase 13: Tools & Protocols

مهارات العملاء: العقد المحمول وحدود الوقت

Type: Build

Languages: Python (stdlib)

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

Time: ~90 minutes

أهداف التعلم

• تعريف مهارة العميل دون الخلط بينها مع عرض، أو تعليمات مخزن، أو أداة، أو خطوة، أو سوباجنت، أو مضخة.
• اقرأ الهاتف المحمولSKILL.mdالعقد والفصل عنه من تمديدات محددة للوقت التشغيل.
• شرح اكتشاف، واختيار، تنشيط، تحميل الموارد، استخدام الأدوات، والتحقق كمرحلة دورة الحياة المختلفة.
• تأكيد حزمة مهارات قبل أن يضعها في كتالوج العميل
• اختر بين مهارة، أداة MCP، خطوة، سوباجنت، أو رمز عادي لمهمة محددة.

نجاح أول عشر دقائق

افعل هذا قبل التفسير الطويل. سوف تخلق مهارة صغيرة،

المراجعة الكاملة حزمة في عامل حقيقي مضيف، استدعاء ذلك، التحقق من

هذا يثبت دورة الحياة مع نتيجة قابل للملاحظة.

قبل الرحلة إلى مختبر المضيف الحقيقي

نقطة التفتيش الحقيقية تستلزم Node.js،npx، بايثون 3 ، واحد مختار

المضيف المهني، وكتب الوصول إلى المشروع أو نطاق المستخدم الذي تختاره

التحقق من الأوامر المحلية أولاً:

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

قرر أي مضيف وسطح ستستخدم قبل التثبيت.

لا توجد متطلبات، اقرأ هذا الدروس على الموقع أو استمر في

التمرينات اليدوية تحت. هذا التراجع يعلم العقد، ولكن

لا يثبت اكتشاف المضيف أو الدعوة أو تنفيذ النص المجمّع، أو

إزالة السلوك، إبق تلك الملاحظات علامة في انتظار

1. ابدأ في دليل عمل فارغ

إشغال هذه الأوامر من أي دليل أولي حيث تستمر في تعلم العمل:

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

يجب أن لا تقوم بالطباعة أي شيء إذا كانت تقوم بطبع الملفات، اختر

دليل فارغ حتى المراجعة لديها حدود واضحة.

إعداد دليل لمهاراتك الأولى:

bashCopymkdir -p my-first-skill

إخلقmy-first-skill/SKILL.mdمع هذا المحتوى:

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.

التحقق من إنشاء الملف في المجلد المقصود:

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

لا وجود رمز الخروج والخروج 0 يعني وجود الملف.

2. قم بتثبيت مجموعة المراجعة الكاملة

ابق في الداخلagent-skills-first-runو أطلق:

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

اختر عامل المضيف والطاق الذي تستخدمه. يجب على الجهاز التثبيت إدراج

skill-contract-reviewerوالمكان الذي كتبته--full-depthهو

المطلوبة لأن مهارة هذا الدروس هي حزمة مستوى مع المراجع،

السيناريو، ومتلك.

المجموعةSKILL_ROOTإلى المجلد المطلق الذي أبلغ عنه المثبت.

أن يكون الإرشاد الذي يحتوي على المثبت SKILL.mdليس مصدر الدروس

الإداري وليس مساحة العمل الحالية:

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"

إذا كانت جلسة العميل مفتوحة بالفعل، بدء جلسة جديدة أو استخدام ذلك المضيف

لا تفترض أن كل مضيف يقوم بإعادة تحميل قائمه

3. استدعاءها صراحة

في الوكيل المثبت، مع agent-skills-first-runكعمل

الإرشادات، استخدام النصوص التي يدعمها هذا المضيف:

استخدم القيم المطلقة المطبوعة ل SKILL_ROOTوTARGET_ROOTفي

طلب. اطلب من المضيف لتوسيعها قبل تنفيذها وتظهر بالضبط

أمر حل، وليس أمر يعتمد على دليل العمل العملي:

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.

يجب أن يكون للقيادة المحلّلة هذا الشكل، دون أيّة حجزات متبقية:

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

النتيجة الناجحة لها كل الخصائص الثلاثة:

1. المضيف يجدskill-contract-reviewerباسمها
2. يقرأ المراجع العقد الحزمي ويقوم بتشغيل مؤكدة المجموعة.
3. يحتوي الإجابة على تقرير تأكيد بدون خطأ هيكلي للاتصالات

العينة، بالإضافة إلى اختيار بدائي مبرر.

يجب أن تكون أدلة الإجراء أيضاً اسم مسار النص، مسار الهدف،

وكتور الحجج، و رمز الخروج. تقرير متسريع دون هذه الحقول لا

إثبات أن النص المكون من المرافق المثبت كان يعمل

إذا أبلغ المضيف أن المهارة غير متوفرة، تحقق من التثبيت

المقصود، إعادة مسح أو إعادة تشغيل مرة واحدة، ومحاولة أخرى الطلب الصريح.

إعادة كتابة وصف المهارات لإخفاء فشل التثبيت.

4. اختيار ضمني للنقش

ابدأ دوراً جديداً من العملاء و أدخل نفس المهمة دون تسمية المهارة:

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

إذا كشف المضيف مهارات مختارة، سجّل ما إذا كان قد اختار

skill-contract-reviewerإذا لم يظهر المضيف التوجيه، قم بتشخيص ضمني

الادعاء الصريح هو الرد الخلفي المحمول

5. نظف

إزالة فقط حزمة المراجعة المثبتة:

bashCopynpx skills remove skill-contract-reviewer

اختر نفس المضيف والطاق المستخدم أثناء التثبيت. بعد إعادة مسح أو إعادة تشغيل

جلسة، طلب صريح لskill-contract-reviewerيجب أن يبلغ عن

لا يمكن الحصول عليهاmy-first-skillفي الدروس اللاحقة، أو إزالة

دليل المختبر بعد أن تنتهي من المسار

المشكلة

لنفترض أن فريقك لديه سير عمل إصدار موثوق به. يجد التغييرات المدمجة، ويتحقق من ملاحظات الهجرة، ويحديث سجل التغييرات، ويقوم بتشغيل أمر التعبئة، ويحقق قائمة مراجعة.

وضع هذا التدفق العمل في عرض واحد يجعل من السهل التلصق وصعوبة التشغيل. لا يوجد في عرض الهوية المستقرة، لا قاعدة اكتشاف، لا حدود الموارد، لا شكل حزمة قابلة للتحقق، ولا يوجد إجابة على الأسئلة الأساسية: من يمكنه استدعائها؟ متى يجب على النموذج اختيارها؟ أي نصوص يمكن تشغيلها؟ أي ملفات يمكن الوثوق بها؟ ما الذي يبقى عندما يتم ضغط السياق؟

الخطأ المعاكس هو التعامل مع كل تعليم قابل لإعادة الاستخدام كمهارة. اتفاقيات مخزن، التلقائية التحكمية، الأدوات الخارجية، خطط الحدث، والوكلاء المفوضين تحل المشاكل المختلفة.SKILL.mdينتج دليل يبدو محمولاً بينما يعتمد على سلوك مضيف واحد غير مُوثق.

أول مهمة هندسية هي التصنيف، تحديد ما هو الفن قبل أن تقرر كيفية إغلاقه.

المفهوم

المهارات التي ترمز المعرفة الإجرائية

مهارة العميل هو دليل نقطة دخولها هيSKILL.md. يحتوي ملف الإدخال على المادة الأمامية YAML تليها تعليمات Markdown. يمكن أن يحتوي الإدراج أيضًا على مرجعيات وسكرتات وأصول.

الإرشادية، وليس ملف ماركداون وحده، هي الوحدة القابلة للتنفيذ.SKILL.mdمع إشارات مفقودة هي حزمة مكسورة حتى لو تم تحليل المواد الأمامية.

الامتزاجات المجاورة

يمكن لمهارة الإفراج أن تخبر العميل كيف يفتش الإفراج. يمكن لمخادم MCP كشف سجل الإفراج. يمكن أن يحظر القفز المباشر. يمكن للقائد التحكم بشكل مستقل في المرشح. هذه الأجزاء تتكون لأنها تحتفظ بمسؤوليات مختلفة.

كلمة "مهارة" تعني أفكار مختلفة

في بعض الأحيان تُطلق أنظمة البحث على برنامج تعلم، أو مسار ناجح، أو قطعة سياسة محددة للبيئة مهارة. يمكن للعميل إنشاء هذه الأثاث أثناء الاستكشاف، واستردادها حسب شبيهة المهام، وتنفيذها، وتحديث المكتبة من المراجعة. مرحلة 14 · 10 تبني هذا النوع من مكتبة التعلم على مدى الحياة.

مهارة العميل في هذه المسار الصغير مختلفة. إنها حزمة مصممة مع عقد نظام الملفات المعلن ، وتفشي البيانات المعدنية ، والكشف التدريجي ، والدعوة المتوسطة في الوقت التشغيلي ، والأدوات التي يتم التحكم بها من قبل المضيف. يمكن إنشاؤها أو تحسينها من قبل العميل ، ولكن لا يتطلب التعلم للصيغة.

كلاهما يحتوي على كفاءة قابلة للاستعمال بشكل متكرر.

النواة المحمولة

تطلب مواصفات مهارات العميل حقلين من المواد الاولى:

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

nameهو المعرف المستقر. يجب أن يلبي قواعد الإسم المحدد ويتطابق مع دليل الأم. descriptionهو كل من الوثائق والبيانات المتحولية. يجب أن يقول ما تقوم به المهارة ومتى تطبق.

الحقول الاختيارية الحقول هي:

يحتوي جهاز ماركداون على تعليمات التشغيل. يجب أن يحدد تدفق العمل، نقاط القرار، سلوك الفشل، والطرق المباشرة إلى الموارد الداعمة.

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.

تمديدات الوقت التشغيلي هي طبقة ثانية

بعض المضيفين يقبلون إضافية المواد الأمامية أو تكوين المرفق. يمكن أن تكون هذه الحقول مفيدة، لكنها ليست محمولة تلقائيًا.

تعامل كل امتداد كإعداد. حافظ على سير العمل الأساسي صالحًا دون ذلك ، وثيقة الخلف ، واختبار المضيف الذي يستهلكه. قد يتجاهل وقت تشغيل حقلًا مجهولًا ، أو يرفضه ، أو يحفظه دون تنفيذ السلوك.

المادة الأمامية هي البيانات المعدنية القابلة للتنفيذ

البيانات المعدنية تغير سلوك النظام قبل قراءة جسم المهارات.

• -أصيب بالشكل الخطأnameيمكن أن تجعل الاكتشاف يفشل
• غامضdescriptionيمكن أن يتوجه طلبات خاطئة.
• علم بشري فقط يمكن أن يزيل المهارة من كتالوج النموذج.
• إمكانية استخدام الأدوات تغير ما إذا كان المضيف يطلب الإذن.
• إعداد السياق يمكن أن تحرك التنفيذ إلى جلسة عامل منفصلة.

مراجعة المادة الأمامية مثل رمز التكوين. تأكيدها، نسخها، وإدراج سلوكها في تقييمات.

دورة حياة المهارات

كل سهم هو حدود مع وضع الفشل الخاص به.

1. Discoveryيجد حزم محتملة في مواقع محددة.
2. Validationيرفض الحزم المعاصرة أو غير الآمنة قبل نشر الكتالوج.
3. Catalogingيظهر الوصفnameوdescriptionليس الحزمة الكاملة
4. Selectionيقرر ما إذا كانت المهارة ذات صلة.
5. Activationيضع الجسم في سياق مرئي للنموذج.
6. Disclosureيقرأ الإشارات أو الأصول فقط عندما يطلبها فرع.
7. Executionيستخدم أدوات المضيف بموجب قواعد الإذن والعزل من المضيف.
8. Verificationيختبر الفن المنتج بشكل مستقل عن ادعاء النموذج.

إن انهيار هذه المراحل يسبب نماذج عقلية سيئة. المهارة المكتشفة غير نشطة. المهارة النشطة غير مصرح بها للقيام بكل ما وصفه. دعوة أداة مسموح بها ليست دليلا على صحة النتيجة.

المهارات والأدوات متناغمة

يجيب MCP: "ما هي القدرات التي يمكن لهذا التطبيق أن يستدعيها، وما هي مخططاتها؟" يجيب المهارة، "كيف ينبغي على وكيل التوجه إلى هذه الفئة من المهام؟"

قد تسمي المهارة أداة، ولكن المضيف يمتلك سجل القدرات الفعلية. إذا كانت الأداة غائبة، يجب أن تشير المهارة إلى عكس أو فشل بوضوح. يجب ألا يعني ذلك أبداً أن تسمية القدرة تخلقها.

المهارات و تعليمات المخبز هي نطاق مختلف

تعليمات مخزن تصف البيئة التي تكون فيها بالفعل: الأوامر والاتفاقيات والملفات المولدة والحدود. تمنح مهارة إجراءات قابلة للاستعمال مرة أخرى لمهمة قد تحدث عبر العديد من مخزنات.

عندما ينطبق كلا الأمرين، فإن طلب المستخدم النشط وقواعد المخبز يحد من المهارة. لا يجب أن تتجاوز مهارة إعادة التصنيف العامة قاعدة المخبز التي تحظر تحرير الملفات المولدة.

المهارات لا تستورد بعضها البعض

يمكن أن تُوجّه مهارة واحدة العميل إلى استدعاء أخرى، ولكن هذه ليست استيراد على مستوى اللغة. المهارة الثانية لا تزال تمر عبر اكتشاف الوقت التشغيلي، والإجابة، والتنشيط، والإذن، ومعالجة السياق.

اكتب الاعتمادات المتعددة المهارات على حواف سير العمل الملاحظ:

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.

هذا يجعل الاعتماد قابلاً للتحقق منه ويمنح المضيف فرصة لتنفيذ السياسة.

بناءها

code/main.pyيطبق مؤكداً صغيراً موجهاً نحو المعايير ومختار الأدوات. يبقى stdlib فقط حتى تكون كل قاعدة مرئية.

المحقق يظهر:

• parse_frontmatter(text)لفرق البيانات المعدنية عن الجسم.
• validate_skill_text(text, directory_name, allowed_runtime_extensions=())للتحقق من الحقول المطلوبة، والإسم، والإمدادات غير المعروفة، وموجودة الجسم، والحدود المحمولة.
• ValidationIssueوSkillReportلإرجاع الأدلة المهيكلة بدلاً من البولية غير الشفافة.
• FrontmatterSyntaxErrorللمدخول الذي لا يمكن تفسيره بأمان.

الاختيار يُكشفTaskShapeوselect_primitives(task). يخطط احتياجات المهمة إلى الرمز العادي، أو تعليمات مخزن، أو مهارة، أو خطوة، أو جهاز تحكم، أو أداة MCP.

إدير المختبر

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

هذا الحظر يتطلب نسخة محلية ويجب أن تبدأ من أي مكان في الداخل

ذلك النموذج كذلكgit rev-parse --show-toplevelيمكن أن تحل جذور المخبأ

يقوم المشاهد الطباعة JSON لمهارة محمولة واحدة صالحة، مهارة مضيفة واحدة مُوسعة، حزمة واحدة غير صالحة، وعدة قرارات شكل المهام. تحقق من رموز المسألة. يجب أن يشرح مؤكد الحزمة كيفية إصلاح عنصر أثري دون تخمين نيابة عن المؤلف.

أمر التحقق من المصادقة

تأكيد الحقائق الهيكلية الرخيصة قبل قواعد المحتوى العميقة:

هذا النظام يمنع الأخطاء الثانوية من إخفاء أول ناقص محطم.

استخدمها

قبل كتابة مهارة، املأ هذه البطاقة القرارية:

العديد من عمليات الإنتاج تستخدم أكثر من سطر واحد. بطاقة منع أحد الأدوات من التظاهر بتوفير كل خاصية.

أرسله

هذا الدرس يخلقskill-contract-reviewerالحزمة تحت outputs/. يحتوي على:

• محمولSKILL.mdالتي تعيد مراجعة حزمة مهارات المقترحة؛
• قوائم التحقق المرجعية للعقد المحمول والانتخاب الأولي.
• نص التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق من التحقق.
• أجهزة تشكيل المهام تغطي الإشارات والمهارات والأدوات والكوك والرقم العادي والسوابق.

قم بتثبيت الحزمة الكاملة، وليس فقط ملفها:

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

ويقول المثبت عن كل مهارة في المرحلة 13

/tmp/aiefs-skills/manifest.jsonهذه الوجهة النظيفة تحقق من شكل الحزمة

حلقة النجاح الأول أعلاه تحقق اكتشاف ودعوة في مضيف حقيقي.

الدروس التالية تعزز كل مرحلة من مراحل دورة الحياة. الدروس 24 تبني اكتشاف وتفشي تدريجي. الدروس 25 تبني سياسة الدعوة والتوجه. الدروس 26 تفصل الإذنات عن الرمل. الدروس 27 تحويل الحزمة بأكملها إلى عنصر إطلاق تقييم.

التمارين

1. تصنف خمس عمليات عمل من فريقك الخاص باستخدام TaskShapeالدفاع عن كل حالة حيث تختار أكثر من واحد بدائي.
2. إضافة اختبارات الحدود التي تثبت أن 500 حرف compatibilityيمر القيمة ويتعطل قيمة 501 حرفًا كخطأ في التفاصيل.
3. إضافة إضافة إضافة واحدة لفترة تشغيل إلى قائمة السماح. اكتب اختبار يثبت أن نفس الملف لا يزال مميزا عن مهارة المحمول فقط.
4. تقسيم خط 400 إلى SKILL.mdإشارة واحدة، عقد نص واحد، وشكل خروج واحد. إبق كل ملف مسؤولا عن نوع واحد من المعلومات.
5. تصميم استجابة فشل لمهارة تشير إلى أداة MCP غير متوفرة. لا تحل محل أداة بصمت بإذنات أوسع.
6. مراجعة مهارة موجودة وتسمية كل جملة على أنها طريق، الإجراء، السياسة، مؤشر مرجع، أو عقد الخروج.

الشروط الرئيسية

المزيد من القراءة

• Agent Skills specificationللديريكتوريا المحمولة وعقد المادة الأمامية.
• Agent Skills best practicesلقطاع النطاق والإرشادات وتنظيم الموارد.
• OpenAI: Build skillsلسياسة اكتشاف و استدعاء القوانين الحالية.
• Claude Code skillsلفترة تشغيل واحدة من الدعوة والحجة والوسيلة والإضافات الموحدة للسياق.

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.