مهارات الوكيل (Skills): حزم مجموعة خطوات وتعليمها لـ Codex
📚 التنقل في السلسلة: المقال السابق [21 · الوكلاء الفرعيون (Subagents)] شرح كيفية تقسيم مهمة كبيرة وتوزيعها على وكلاء فرعيين مستقلين للتنفيذ بالتوازي وتلخيص النتائج. هذا المقال يناقش فكرة أخرى: بدلاً من تقسيم المهمة، سنقوم بـ حزم وتغليف القدرات - لتجميع خطوات مكررة وصياغتها في مهارات للوكيل (Skills)، ليقوم Codex باستدعائها تلقائياً عند الحاجة. المقال التالي [23 · الإضافات (Plugins)] سيتحدث عن كيفية حزم هذه المهارات ومشاركتها مع بقية المطورين لتثبيتها بضغطة زر.
تصفحت مستودع المهارات الرسمي لـ OpenAI على العنوان github.com/openai/skills.
ووجدت بنية المهارة (Skill) بسيطة للغاية، حيث تتكون بالأساس من ملف واحد هو SKILL.md - يبدأ بقسم إعدادات محدد، ويليه بضعة أسطر تشرح "ما يجب القيام به". ورغم بساطة هذا الملف الصغير، إلا أن المطورين يصفونه بأنه "الصيغة الأساسية لكتابة سير العمل المكرر والقابل للاستخدام" (the authoring format for reusable workflows): حيث تكتب فيه الخطوات لمرة واحدة، ليقوم Codex بتنفيذها تلقائياً لاحقاً، دون حاجة لتكرار كتابتها في كل مرة.
يعتقد البعض في البداية أن المهارات هي مجرد إعادة صياغة للأوامر المائلة - مثل أمر /review الذي نكتبه للتشغيل الفوري. ولكن في الواقع، هناك فارق جوهري. فالأوامر المائلة تتطلب منك كتابتها صراحة ليتم تشغيلها؛ بينما تعمل المهارات تلقائياً - فبمجرد رصد Codex لتوافق المهمة الحالية مع شرح إحدى المهارات، يتولى المساعد استدعاءها تلقائياً، دون أن تملأ المحادثة بسجلات عملها الجانبية.
يشرح هذا المقال مهارات الوكيل بالتفصيل - ما هي، كيف تحمي سياق المحادثة من الامتلاء، أين تحفظ، كيف يتم استدعاؤها وتفعيلها، وكيف تبني مهارة خاصة بك. ونعتمد بالكامل على المستندات الرسمية لـ Codex - وننبه لبعض الأخطاء الشائعة في الشروحات غير المحدثة مثل كتابة مسارات مجلدات أو أسماء حقول خاطئة.
بقراءة هذا المقال، ستحصل على:
- مفهوم المهارة (Skill) - وكيف يتحول ملف
SKILL.mdوالسكربتات والملفات المرفقة معه لمهارة وقدرة جديدة يتعلمها Codex - آلية "الإفصاح التدريجي (progressive disclosure)" الهامة: كيف ينجح النظام في حفظ مئات المهارات دون التأثير على سياق المحادثة
- طريقتان للاستدعاء (الاستدعاء الصريح باستخدام رمز
$vs الاستدعاء الضمني التلقائي بناءً على الشرح) والفروق بينهما، وكيفية صياغة الشرح لزيادة دقة الاستدعاء - المجلد الصحيح لحفظ المهارات (مجلد
.agents/skillsالمحلي والمشترك، وليس مجلد~/.codex/skills)، والتأثير عند تداخل الأسماء - كيفية الاستعانة بأداة
$skill-creatorالمدمجة لإنشاء مهارة ببعض الإجابات، واستخدام$skill-installerلتثبيت مهارات جاهزة، وإيقاف مهارة مؤقتاً
01 مفهوم مهارة الوكيل (Skill)
نبدأ بالخلاصة: تعد المهارة (Skill) مجلداً يحتوي بالأساس على ملف SKILL.md الإلزامي، إلى جانب سكربتات وملفات مرجعية اختيارية، يتم حزمها معاً لتقدم "قدرة متخصصة" يتعلمها Codex. وتصفها الوثائق بـ: "المهارة هي مجلد يضم ملف SKILL.md وسكربتات اختيارية ومواد مرجعية".
لماذا نحتاج للمهارات؟ لأن العمل مع Codex يتضمن مهاماً برمجية تتكرر إرشاداتها بانتظام. فمثلاً عند الطلب منه رفع التعديلات، تضطر لإخباره في كل مرة بـ "تأكد من تشغيل الاختبارات أولاً، واكتب رسالة commit باللغة العربية، وأضف البادئة feat: أو fix:" - وهي إرشادات مكررة. تم تصميم مهارات الوكيل لتتولى إدارة هذه الإرشادات تلقائياً.
تشبيه: "كتيب إرشادات تركيب قطع الليدو". لا يقوم كتيب الإرشادات المرفق بتركيب القطع نيابة عنك، ولكنه يشرح خطوة بخطوة: "ضع القاعدة أولاً، ثم ثبت العجلات الأربع، وأخيراً ركب السقف". وباتباع الكتيب، يتمكن أي شخص من إتمام التركيب والحصول على نفس النتيجة بدقة. المهارة تمثل هذا الكتيب لـ Codex: حيث تكتب الخطوات بالتفصيل (مثل "قراءة التعديلات الحالية وتلخيص المخاطر") في ملف SKILL.md ليتعلمها Codex كخطوات ثابتة، دون حاجة لإعادة شرحها وتوضيحها في كل مرة.
كيف يبدو ملف SKILL.md؟ تتكون بنيته الأساسية من جزأين، وإليك النموذج المقترح رسمياً:
---
name: skill-name
description: اشرح هنا متى يجب استدعاء هذه المهارة ومتى يمنع استخدامها.
---
اكتب هنا الخطوات والإرشادات التي يجب على Codex الالتزام بها عند تنفيذ المهارة.يسمى الجزء العلوي المحصور بين علامتي --- بـ YAML frontmatter (الإعدادات المتقدمة للملف)، وتشترط الوثائق كتابة حقلي name و description بداخله: يمثل name اسم المهارة (والذي تستخدمه لاستدعائها صراحة برمز $)، ويوضح حقل description وظيفة المهارة ومتى يتم استدعاؤها. ويمثل الجزء السفلي المكتوب بتنسيق markdown التعليمات التي يلتزم بها Codex عند تفعيل المهارة.
⚠️ تنبيه هام للمبتدئين لتجنب الأخطاء الشائعة: تكتب بعض الشروحات غير المحدثة حقلاً باسم
trigger(وتدعي أنه لتحديد كلمات الاستدعاء المفتاحية)، وتطلب حفظ المهارات في مجلد~/.codex/skills/. ولا تحتوي الوثائق الرسمية لـ Codex على حقل باسمtrigger، ويعتمد الاستدعاء بالأساس على التحليل الدلالي لحقل الشرحdescription؛ كما يحفظ المجلد في المسار.agents/skills(الموضح في القسم 04). ومخالفة ذلك تمنع Codex من قراءة المهارة. واعتمد على الإرشادات الرسمية دائماً.
لا تقتصر المهارة على ملف SKILL.md فقط، بل تمثل مجلداً متكاملاً. وإلى جانب الملف الإلزامي، يمكن أن يحتوي المجلد على سكربتات ومواد مرجعية كالتالي:
my-skill/
├── SKILL.md # الملف الإلزامي (يحتوي على name و description)
├── scripts/ # اختياري: سكربتات تشغيل (لإجراء مهام حتمية أو ربط أدوات)
└── references/ # اختياري: وثائق مرجعية يقرأها المساعد عند تنفيذ المهارةيعد ملف SKILL.md هو العنصر الإجباري الوحيد، وتعتبر بقية العناصر اختيارية. وتوصي الإرشادات بـ: الاعتماد على التعليمات والنصوص المكتوبة وتجنب كتابة السكربتات إلا عند الحاجة للقيام بمهام حتمية تتطلب دقة متناهية أو ربط أدوات خارجية. فالتعليمات المكتوبة تمنح Codex مرونة أعلى في التنفيذ مقارنة بالسكربتات الجامدة.
إليك ثلاثة أمثلة عملية لاستخدام المهارات:
- عند الرغبة في توحيد أسلوب رفع التعديلات في الفريق (تشغيل الاختبارات أولاً، صياغة الرسائل، وإضافة البادئات) - تكتب مهارة باسم
commitلتنفيذ المهمة بكلمة واحدة. - عند الرغبة في الالتزام بمعايير برمجية معينة للشركة (أسلوب تسمية RESTful، معالجة الأخطاء الموحدة، وفحص المعاملات) - تكتب مهارة باسم
api-conventionsليلتزم بها تلقائياً عند كتابة الواجهات البرمجية. - عند وجود قائمة فحص دورية قبل نشر البرمجيات (تحديث changelog، إضافة الرموز، وتشغيل اختبارات الأمان) - تكتب مهارة لتشغيل هذه القائمة بطلب بسيط.
💡 ملخص في جملة واحدة: تمثل المهارة (Skill) مجلداً يحتوي على ملف
SKILL.md(يضم الاسم والشرح وإرشادات العمل) وسكربتات ومواد مرجعية اختيارية - تكتب مرة واحدة ليستحضرها المساعد تلقائياً مستقبلاً؛ ويفضل الاعتماد على التعليمات المكتوبة وتجنب السكربتات إلا للضرورة.
02 آلية الإفصاح التدريجي (Progressive Disclosure): حماية السياق
نوضح هنا ركيزة تقنية هامة. كيف ينجح Codex في قراءة واستيعاب مئات المهارات دون أن تمتلئ محادثتك البرمجية وتزدحم بها؟ يرجع الفضل لآلية "الإفصاح التدريجي (progressive disclosure)" (التي تعني جلب المعلومات وقراءتها عند الحاجة الفورية فقط).
تحدثنا في المقال 02 عن سياق المحادثة المتاح - حيث يمثل مساحة محدودة تستهلكها النصوص والصور وتؤثر على جودة استجابة النموذج وتفكيره. وإذا قام Codex بقراءة كل المهارات المتاحة وتفاصيلها عند بدء المحادثة، فستزدحم الذاكرة وتتراجع جودة الاستجابات.
تشبيه: قائمة الطعام المعروضة في واجهة المطعم. عند مرورك بجانب المطعم، ترى لوحة صغيرة تعرض أسماء الوجبات بكلمات بسيطة (مثل "شاورما دجاج - مع الثوم"). وتمنحك اللوحة فكرة عامة عن المتاح، ولكن تفاصيل تحضير الوجبة ومكوناتها وسجلاتها تظل داخل المطبخ ولا تقرأها إلا عند طلب الوجبة وتناولها فعلياً. وتعمل المهارات في Codex بنفس الأسلوب، وتوضح الوثائق الآليتين كالتالي:
عند بدء تشغيل Codex، يقتصر تحميل المهارات على قراءة أسماء المهارات وشروحها ومسارات حفظها فقط. ولا يتم فتح وقراءة محتويات ملف
SKILL.mdبالكامل إلا عندما يقرر Codex استدعاء وتفعيل هذه المهارة للمهمة الحالية.
بمعنى بسيط:
- في الحالة العادية: يقتصر استهلاك سياق المحادثة لكل مهارة على سطر واحد يضم الاسم والشرح والمسار.
- عند الاستدعاء: عندما يحدد Codex توافق المهمة الحالية مع إحدى المهارات، يقوم بقراءة وفتح محتويات ملف
SKILL.mdبالكامل للالتزام بالخطوات المكتوبة بداخلها.
هذا التصميم يتيح لك كتابة أدلة استخدام مفصلة وقوائم فحص طويلة داخل ملفات المهارات، دون خوف من إهدار سياق المحادثة العادية.
توضح الرسمة مرحلتي معالجة المهارات: في المرحلة الأولى (على اليسار) عند بدء التشغيل يقتصر التحميل على الاسم والشرح والمسار لتقليل الاستهلاك؛ وفي المرحلة الثانية (على اليمين) يتم تحميل وفتح ملف المهارة المحدد بالكامل للعمل بموجبه عند استدعائه، وتظل بقية المهارات محتفظة بصيغتها المختصرة.
ولكن تذكر أن مساحة "قائمة الأسماء المختصرة" ليست مجانية بالكامل - بل تفرض الوثائق حداً أقصى لحجمها:
لحماية سياق المحادثة الأساسية، تقتصر مساحة لوحة الأسماء المختصرة على 2% تقريباً من إجمالي حجم سياق النموذج، أو 8,000 حرف كحد أقصى. وعند زيادة عدد المهارات المرتبطة بشكل كبير، يقوم Codex بتقليص شروح المهارات تلقائياً؛ وإذا تجاوزت المهارات الحد الأقصى فقد يتم إيقاف تحميل بعض المهارات وسيظهر تنبيه أمني بذلك.
وتنبهك هذه القاعدة لنصيحة هامة: احرص على كتابة الكلمات المفتاحية الأساسية في بداية حقل الشرح description. فإذا اضطر النظام لتقليص الشرح نتيجة لزيادة المهارات، تضمن بقاء الكلمات المفتاحية في البداية وعدم حذفها لتسهيل عملية الاستدعاء دلالياً؛ وتجنب تأخير الكلمات لنهاية النص لئلا تحذف - وهي نفس النصيحة التي ذكرناها في المقال 11 بشأن كتابة القواعد الهامة في بداية ملف AGENTS.md.
💡 ملخص في جملة واحدة: تعتمد ميزة الإفصاح التدريجي على تحميل اسم وشرح المهارة فقط في البداية، وفتح الملف وقراءته بالكامل عند الاستدعاء لحماية سياق المحادثة؛ واحرص على كتابة الكلمات المفتاحية في بداية الشرح لتلافي حذفها عند تقليص النصوص.
03 طريقتان للاستدعاء: الاستدعاء الصريح يدوياً vs الاستدعاء الضمني التلقائي
بعد فهم آلية حماية السياق، نأتي لكيفية تشغيل واستدعاء المهارات. وتتوفر طريقتان للتشغيل، ويساعدك فهم الفروق بينهما في تحديد الأسلوب الأنسب للمهمة.
تشبيه: طلب الوجبات من المطعم. الطريقة الأولى هي الطلب بالاسم المحدد - مثل قولك "أريد وجبة الشاورما الفلانية"، ليقوم المطبخ بتحضيرها مباشرة دون تفكير. والطريقة الثانية هي شرح ما تشتهيه - مثل قولك "أريد وجبة حارة ومشوية ولذيذة"، ليتولى المطعم مراجعة الخيارات المتاحة واقتراح الوجبة الأنسب لطلبك. وتماثل طرق استدعاء المهارات هذين الأسلوبين.
الاستدعاء الصريح: الطلب بالاسم يدوياً
الأسلوب الأول هو الاستدعاء الصريح (explicit invocation) - حيث تكتب اسم المهارة صراحة في محادثتك. ويدعم النظام الطريقتين التاليتين: كتابة رمز $ متبوعاً باسم المهارة في الرسالة، أو تشغيل أمر /skills لمراجعة واختيار المهارة المطلوبة.
$commitعند كتابة الرمز $ ستظهر قائمة منبثقة بالمهارات المتاحة لاختيارها (أو كتابة الاسم بالكامل)، ليقوم Codex بتحميل المهارة فوراً والالتزام بخطواتها دون إجراء أي فحص دلالي - فالأمر صادر منك مباشرة وهو الأسلوب الأكثر أماناً واستقراراً.
⚠️ تنبيه لتجنب أخطاء الشروحات القديمة: تكتب بعض المصادر رمز
@للاستدعاء الصريح بالاسم. والرمز المعتمد رسمياً في Codex هو$(أو استخدام أمر/skills)، وتجنب خلط الرموز.
الاستدعاء الضمني: التحليل الدلالي التلقائي
الأسلوب الثاني هو الاستدعاء الضمني (implicit invocation) - حيث تكتب طلبك باللغة الطبيعية دون الإشارة لاسم المهارة، ليتولى Codex مراجعة طلبك ومقارنته بحقول الشرح description للمهارات المتاحة، واستدعاء المهارة المتوافقة تلقائياً. وتنص الوثائق على:
عندما تتوافق متطلبات مهمتك الحالية مع شرح مهارة معينة
description، يستطيع Codex استدعاء وتطبيق هذه المهارة تلقائياً.
هذه هي الميزة المريحة للمهارات: فلا تحتاج لحفظ أسماء المهارات أو كتابة الرمز $، ويكفي شرح ما تريده ليقوم النظام بفتح المهارة المناسبة. ولكن هذا يضع المسؤولية على صياغة حقل الشرح description - وتنص الإرشادات بوضوح على:
نظراً لاعتماد الاستدعاء الضمني على حقل الشرح، احرص على كتابة شرح مختصر ومحدد النطاق وواضح الحدود. واكتب الكلمات المفتاحية في البداية لتسهيل مطابقتها دلالياً عند فحص الطلب.
واجهت مشكلة في بداياتي عندما كتبت شرح المهارة بشكل عام مثل "المساعدة في مراجعة الأكواد" - فكان المساعد يستدعي المهارة لكل عملية فحص بسيطة، أو يغفل عنها عند الحاجة الفعلية. وقمت بتعديله لاحقاً لصيغة محددة مثل: "فحص التعديلات الحالية ورصد المشاكل وتلخيص التغييرات. وتستدعى المهارة عند طلب المستخدم 'ما الذي تم تعديله'، 'اكتب رسالة commit'، أو 'راجع التغييرات الحالية'"، فكتبت الجمل والطلبات التي أستخدمها فعلياً، مما زاد من دقة التوجيه والاستدعاء تلقائياً. فالشرح هو أداة توجيه وتحليل دلالي للكمبيوتر وليس مجرد نص تعريفي للبشر.
يوضح الجدول التالي المقارنة بين طريقتي التشغيل:
| وجه المقارنة | الاستدعاء الصريح (باستخدام $ أو أمر /skills) | الاستدعاء الضمني (التحليل الدلالي تلقائياً) |
|---|---|---|
| طريقة التشغيل | الإشارة للاسم صراحة برمز $ أو الاختيار من /skills | كتابة الطلب باللغة الطبيعية ليتولى المساعد مطابقتها دلالياً |
| فحص Codex للطلب | لا يفحص الطلب، وينفذ المهارة فوراً | يفحص ويقارن الطلب بحقل الشرح description للمهارات |
| دقة التشغيل تعتمد على | اختيارك الصحيح للاسم | دقة وجودة كتابة حقل الشرح description |
| الأنسب لـ | المهام الحساسة التي تريد تشغيلها بدقة في وقت محدد | التسهيل والاستدعاء التلقائي دون حاجة لتذكر الأسماء |
| إمكانية الإيقاف | لا يمكن إيقافه (الطلب الصريح ينفذ دائماً) | يمكن إيقافه (عبر خيار allow_implicit_invocation الموضح في القسم 05) |
💡 ملخص في جملة واحدة: يتم الاستدعاء الصريح بالاسم باستخدام رمز
$أو عبر/skillsوهو الأسلوب الأكثر أماناً؛ ويتم الاستدعاء الضمني تلقائياً بناءً على توافق الطلب مع حقل الشرحdescription- وتعتمد دقة الاستدعاء الضمني على جودة صياغة الشرح وكتابة الكلمات الفعالية في بدايته.
04 مواقع المهارات وشروط مشاركتها: مجلد .agents/skills
بعد فهم طبيعة المهارات واستدعائها، نأتي لموقع حفظ الملفات على جهازك. تجنب كتابة المسارات من الذاكرة، والتزم بالمسارات المعتمدة رسمياً.
تشير الوثائق إلى أن Codex يقوم بقراءة المهارات من أربعة مستويات: المستودع (REPO)، المستخدم (USER)، الإدارة (ADMIN)، والنظام (SYSTEM). وفي مستوى المستودع، يتبع النظام أسلوباً متميزاً: حيث يبدأ Codex بفحص مجلد التشغيل الحالي صعوداً للمجلدات الأعلى حتى الوصول للجذر، ويقوم بتحميل المهارات المكتوبة في مجلدات .agents/skills في كل مستوى. وإليك تفاصيل المسارات:
| مستوى التأثير | مسار حفظ المهارة | نطاق الاستخدام |
|---|---|---|
| المستودع المحلي (REPO) | $CWD/.agents/skills | يقتصر على المجلد الحالي الذي قمت بتشغيل Codex فيه - للمهارات الخاصة بوحدة برمجية فرعية محددة |
| المستودع الأعلى (REPO) | $CWD/../.agents/skills | مجلدات المشروع الأعلى - للمهارات المشتركة بين عدة وحدات فرعية |
| المستودع الرئيسي (REPO) | $REPO_ROOT/.agents/skills | جذر المستودع الرئيسي - وتتوفر المهارة لجميع المجلدات والملفات داخل المشروع |
| المستخدم العام (USER) | $HOME/.agents/skills | المجلد الرئيسي للمستخدم - وتعمل المهارة معك في أي مشروع تفتحه على هذا الجهاز |
| إدارة النظام (ADMIN) | /etc/codex/skills | لجميع مستخدمي الجهاز أو الحاوية (لإجراء عمليات الصيانة والتشغيل الآلي وإعدادات المسؤول) |
| النظام الافتراضي (SYSTEM) | مدمجة ومحفوظة داخل برنامج Codex | تتوفر لجميع مستخدمي البرنامج (مثل مهارة skill-creator ومهام التخطيط) |
⚠️ تنبيه هام جداً لتجنب المشاكل: يتم حفظ المهارات في مجلدات
.agents/skillsالمحلية أو مجلد المستخدم$HOME/.agents/skills، وليس في مجلد~/.codex/skills/. ويختص مجلد~/.codex/بحفظ ملفات التكوين مثلconfig.toml(كما هو موضح في القسم 05)، وإذا وضعت المهارات بداخله فلن يتمكن Codex من قراءتها وستظن أنها معطلة. وتختلف هذه البنية عن مسار ملفAGENTS.mdفتجنب الخلط.
المنطق بسيط: المهارات الشخصية المخصصة لك وتستخدمها في مختلف المهام، احفظها في مجلد المستخدم الرئيسي $HOME/.agents/skills؛ أما المهارات المخصصة للمشروع البرمجي ويريد الفريق بأكمله الالتزام بها، فاحفظها في مجلد المشروع الرئيسي .agents/skills وقم برفعها في Git ليتلقاها بقية المطورين تلقائياً. ويمثل $HOME المجلد الرئيسي للمستخدم على أنظمة Mac / Linux؛ وعلى نظام Windows يطابق المسار الخاص بالمستخدم الفعلي.
ماذا يحدث عند تطابق أسماء مهارات مختلفة؟ تنص الوثائق بوضوح على: لا يقوم Codex بإلغاء أو دمج المهارات المتطابقة في الاسم، ويستمر في عرض المهارات معاً في قائمة الاختيار. ويختلف هذا السلوك عن ملف AGENTS.md الذي يطبق مبدأ "الأولوية للأقرب وإلغاء الأبعد"، حيث تظهر المهارات المتطابقة معاً لتختار منها. لذا تنصح الإرشادات: بتجنب تكرار أسماء المهارات في المستويات المختلفة لتفادي اللبس عند الاختيار.
وتفصيل فني مفيد: يقوم Codex بفحص وتحديث قائمة المهارات تلقائياً عند تعديل الملفات - وأي تعديل في ملف SKILL.md يطبق فوراً. وإذا واجهت مشكلة في التحديث، فالحل الأبسط هو إعادة تشغيل برنامج Codex.
💡 ملخص في جملة واحدة: تحفظ المهارات في المجلد
.agents/skills(المستودع المحلي والمشترك صعوداً للجذر) أو مجلد المستخدم العام$HOME/.agents/skills، وليس في مجلد~/.codex/skills؛ وتظهر الأسماء المتطابقة معاً دون إلغاء لذا يفضل تجنب تكرار الأسماء؛ ويتم التحديث تلقائياً أو بإعادة تشغيل البرنامج.
05 الإعداد والتشغيل: استخدام أداة الإنشاء، التثبيت، والتعطيل
بعد توضيح المفاهيم، نأتي للخطوات العملية للتعامل مع المهارات: إنشاء مهارة جديدة، تثبيت مهارة جاهزة، وتعطيل مهارة مؤقتاً.
إنشاء مهارة: استخدام أداة $skill-creator المدمجة
تنصح الإرشادات الرسمية بـ: الاستعانة بأداة الإنشاء المدمجة وتجنب كتابة الملفات يدوياً في البداية. اكتب في محادثة Codex أو الطرفية:
$skill-creatorسيقوم المعالج بطرح ثلاثة أسئلة مبسطة: ما هي وظيفة المهارة؟ متى يتم استدعاؤها وضبط الشرح؟ وهل تقتصر على التعليمات المكتوبة أم تتطلب سكربتات تشغيل؟ (ويقترح المعالج الاعتماد على التعليمات المكتوبة افتراضياً لسهولة صيانتها - تماشياً مع نصيحة القسم 01). وعند انتهاء الإجابات، يقوم ببناء مجلد المهارة وكتابة ملف SKILL.md تلقائياً. وهو الأسلوب المعتمد لدي لبدء كتابة أي مهارة جديدة لتجنب الأخطاء الإملائية والترتيبية في الملفات.
ويمكنك بالطبع إنشاء المجلد والملف يدوياً - باتباع النموذج الموضح في القسم 01، وإنشاء المجلد وكتابة ملف SKILL.md المحتوي على حقول name و description والتعليمات يدوياً لتؤدي نفس الغرض.
تثبيت مهارة: استخدام أداة التثبيت $skill-installer
عند الرغبة في تثبيت مهارة جاهزة طورها مطورون آخرون، يوفر Codex أداة $skill-installer لتسهيل تثبيت المهارات الخارجية. لتركيب مهارة ربط أداة Linear مثلاً:
$skill-installer linearويمكن لأداة التثبيت جلب المهارات من مستودعات ومواقع خارجية. ويتم قراءة وتفعيل المهارة تلقائياً بعد التثبيت، وأعد تشغيل البرنامج عند الحاجة.
ℹ️ تحدد الإرشادات دور أداة
$skill-installerفي "فترات التجربة والاختبار المحلي للمهارات". وعند الرغبة في توزيع ونشر المهارات بشكل رسمي للفريق أو المجتمع وبمواصفات وإعدادات متكاملة، فيفضل حزمها في إضافات (Plugins) - وهو موضوع مقالنا القادم [23 · الإضافات (Plugins)]. وتذكر هذه القاعدة: المهارة (Skill) هي صيغة كتابة وتصميم سير العمل، والإضافة (Plugin) هي صيغة التعبئة والتوزيع؛ فنصمم سير العمل كمهارة أولاً، ثم نحزمها كإضافة لمشاركتها.
تعطيل مهارة مؤقتاً
عند الرغبة في إيقاف مهارة معينة مؤقتاً (سواء كانت مهارة مدمجة في النظام أو قمت بتثبيتها) دون الرغبة في حذف ملفاتها، فيمكنك كتابة إعداد التعطيل في ملف المستخدم العام ~/.codex/config.toml (ملف التكوين العام، وتذكر أنه يقع في مجلد .codex وليس .agents):
# مسار الملف: ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = falseاكتب المسار الدقيق لملف SKILL.md للمهارة المستهدفة في حقل path واضبط حقل التشغيل كـ enabled = false لإيقافها. وأعد تشغيل برنامج Codex لتطبيق التعديل. ويساعد هذا الإجراء عند تراكم المهارات وتجاوز الحد الأقصى لحجم قائمة المهارات المختصرة الموضح في القسم 02 لتوفير المساحة للمهارات الهامة الحالية.
خيارات متقدمة: إيقاف الاستدعاء الضمني تلقائياً (عبر agents/openai.yaml)
إذا كنت تريد ضبطاً متقدماً للمهارة - مثل تحديد اسمها أو أيقونتها في واجهة تطبيق Codex، أو كتابة الأدوات التي تعتمد عليها، أو إيقاف ميزة الاستدعاء الدلالي الضمني التلقائي - فيمكنك إنشاء ملف تكوين فرعي باسم agents/openai.yaml داخل مجلد المهارة نفسه، وكتابة الإعداد التالي:
# مسار الملف: <skill_dir>/agents/openai.yaml
policy:
allow_implicit_invocation: falseتكون القيمة الافتراضية لحقل allow_implicit_invocation هي true (للسماح بالاستدعاء الضمني تلقائياً)؛ وعند تعديلها لـ false يُمنع Codex من استدعاء المهارة تلقائياً بناءً على تحليل المحادثة، ويقتصر تشغيلها على كتابتك لاسمها صراحة بالرمز $名字. وهو خيار هام للمهارات التي يترتب عليها تغييرات هامة أو عمليات نشر (مثل "نشر الكود للإنتاج") لتجنب قيام Codex بتشغيلها تلقائياً عند استنتاج جاهزية الكود، وحصر تفعيلها بموافقتك وكتابتك للاسم صراحة.
يوضح الجدول التالي العمليات المختلفة ومواقع تعديلها لتجنب التداخل:
| العملية المطلوبة | الأداة المستخدمة | الملف أو الأمر المطلوب |
|---|---|---|
| إنشاء مهارة جديدة بسرعة | $skill-creator | يكتب في محادثة Codex أو CLI مباشرة |
| تثبيت مهارة جاهزة | $skill-installer <name> | يكتب في محادثة Codex أو CLI مباشرة |
| إيقاف مهارة مؤقتاً | [[skills.config]] | يكتب في ملف التكوين العام ~/.codex/config.toml |
| إيقاف الاستدعاء الضمني التلقائي للمهارة | allow_implicit_invocation: false | يكتب في ملف agents/openai.yaml داخل مجلد المهارة |
| موقع حفظ المهارات المكتوبة يدوياً | إنشاء مجلد وملف SKILL.md | مجلدات .agents/skills المحلية أو مجلد المستخدم $HOME/.agents/skills |
💡 ملخص in جملة واحدة: يتم الإنشاء بأداة
$skill-creator(للمهارات النصية)، والتثبيت بأداة$skill-installer، والإيقاف المؤقت بكتابة قسم[[skills.config]]في ملف~/.codex/config.tomlالعام، وإيقاف الاستدعاء الضمني بملفagents/openai.yamlوضبطallow_implicit_invocation: false؛ وتذكر أن الإعدادات تكتب في مجلدات.codexوالمهارات تحفظ في مجلدات.agents.
06 تدريب عملي: إنشاء مهارة مبسطة وتجربتها
نطبق معاً تدريباً عملياً متكاملاً: إنشاء مهارة مستخدم عام جديدة ← صياغة ملف SKILL.md ← التحقق من قراءتها في القائمة ← وتجربة استدعائها بالأسلوبين الضمني والصريح للتأكد من فاعلية الخطوات.
سنقوم بإنشاء مهارة تسمى explain-self وظيفتها تبسيط وشرح الأكواد البرمجية أو رسائل الخطأ بلغة مبسطة خالية من التعقيد الفني.
الخطوة الأولى: إنشاء مجلد المهارة العام للمستخدم
mkdir -p ~/.agents/skills/explain-selfالمتوقع: إنشاء مجلد فارغ باسم explain-self تحت مسار المهارات العام للمستخدم. وتأكد من كتابة المجلد .agents وليس .codex لتجنب خطأ التداخل الشائع الموضح في القسم 04.
الخطوة الثانية: كتابة ملف SKILL.md المبسط
افتح محرر الأكواد، واحفظ الملف التالي في المسار ~/.agents/skills/explain-self/SKILL.md:
---
name: explain-self
description: تبسيط وشرح الأكواد البرمجية ورسائل الخطأ بلغة عامة مبسطة. وتستدعى المهارة عند طلب المستخدم 'ما وظيفة هذا الكود'، 'شرح لهذا الخطأ'، أو 'ساعدني في فهم هذا'.
---
قم بشرح الكود أو رسالة الخطأ المقدمة من المستخدم بأسلوب مبسط يناسب المبتدئين:
1. اشرح الوظيفة العامة للكود في جملة واحدة واضحة.
2. قم بتقسيم الكود وشرح أجزائه بالتفصيل خطوة بخطوة.
3. في حال وجود رسالة خطأ، وضح السبب المحتمل وطريقة معالجته بوضوح.
وتجنب استخدام المصطلحات الفنية المعقدة، واعتمد على التشبيهات الحياتية المبسطة لتسهيل الفهم.لاحظ صياغة حقل الشرح description بكتابة الأسئلة والطلبات التي نستخدمها في العادة لتكون بمثابة مؤشرات فحص دلالي للنظام.
المتوقع: كتابة ملف SKILL.md وحفظه في مجلد المهارة بنجاح.
الخطوة الثالثة: تشغيل Codex والتحقق من قراءة المهارة
codexاكتب هذا الأمر للتأكد من قراءة وتحديث قائمة المهارات:
/skillsالمتوقع: ظهور اسم المهارة explain-self في القائمة المنبثقة مع عرض الشرح التعريفي المرفق بها، مما يثبت نجاح التعرف على المهارة ومسار حفظها. ويوضح هذا الظهور فكرة الإفصاح التدريجي: حيث يقتصر استهلاك السياق حالياً على هذا السطر المختصر، ولا يتم تحميل بقية الملف إلا عند الاستدعاء الفعلي.
الخطوة الرابعة: تجربة الاستدعاء الضمني التلقائي باللغة الطبيعية
تجنب كتابة اسم المهارة أو استخدام الرمز $, واكتب طلباً عادياً يطابق الشرح:
ما وظيفة هذا الكود: print(sum([1,2,3]) / len([1,2,3]))المتوقع: سيقوم Codex بتحليل طلبك دلالياً ومطابقته مع مهارة explain-self تلقائياً، ويقوم بفتح وقراءة ملف المهارة والالتزام بالخطوات الثلاث المكتوبة بداخلها (توضيح الوظيفة العامة وهي حساب المتوسط الحسابي وقيمته 2.0، تقسيم العملية خطوة بخطوة، مع تجنب المصطلحات المعقدة). وهي عملية استدعاء تلقائي وضمني ناجحة.
الخطوة الخامسة: تجربة الاستدعاء الصريح بالاسم
نجرب الآن استدعاء المهارة بالاسم صراحة باستخدام رمز $:
$explain-self ما سبب هذا الخطأ: ZeroDivisionError: division by zeroالمتوقع: استدعاء المهارة وتطبيق خطواتها بنجاح لمعالجة رسالة الخطأ (توضيح أن الخطأ هو القسمة على صفر، وشرح سببه وطريقة حله بأسلوب مبسط). وتطابق هذه الخطوة مبدأ الاستدعاء الصريح بالاسم المباشر الموضح في القسم 03.
بإتمام هذه الخطوات الخمس، تكون قد تحققت عملياً من دورة عمل المهارات: حفظ الملف في المجلد الصحيح .agents ← قراءة المهارة في القائمة ← استدعاؤها ضمنياً بالتحليل الدلالي ← واستدعاؤها صراحة بالاسم.
💡 ملخص في جملة واحدة: خطوات التدريب هي: إنشاء مجلد المهارة explain-self تحت
.agents← كتابة ملفSKILL.mdبشرح واضح ← التحقق من المهارة بأمر/skills← وتجربتها بالأسلوبين الضمني والصريح؛ للتأكد من فهم وإعداد مهارات الوكيل بنجاح وتجنب أخطاء المسارات.
07 ملخص
شرحنا في هذا المقال مهارات الوكيل (Skills) في Codex بالتفصيل - وكيفية حزم خطوات وسير العمل المكرر وتأمين وإدارة استدعاء المهارات محلياً ومشتركتها.
دعنا نلخص النقاط الأساسية معاً بشكل سريع:
| وجه المقارنة | الشرح والنقاط الهامة |
|---|---|
| مفهوم المهارة (Skill) | مجلد يضم ملف SKILL.md (يحتوي على الاسم والشرح وإرشادات العمل) وسكربتات اختيارية ومواد مرجعية، ويمثل طريقة لحزم المهام المكررة |
| حماية سياق المحادثة | عبر ميزة الإفصاح التدريجي: حيث يقتصر التحميل على الاسم والشرح، ويفتح الملف بالكامل عند الاستدعاء فقط؛ وتلتزم بمساحة 2% أو 8000 حرف للأسماء المختصرة |
| طرق الاستدعاء والتشغيل | الاستدعاء الصريح بالاسم المباشر عبر رمز $ أو /skills؛ أو الاستدعاء الضمني بالتحليل الدلالي لمطابقة الطلب مع حقل الشرح description |
| مواقع حفظ الملفات | المجلدات المحلية للمستودع .agents/skills (صعوداً من مجلد العمل للجذر) أو مجلد المستخدم العام $HOME/.agents/skills، وليس مجلد ~/.codex/skills |
| خيارات الإدارة | إنشاء مهارة جديدة بأداة $skill-creator، وتثبيت مهارة جاهزة بأداة $skill-installer، وإيقاف مهارة بملف config.toml يدوياً |
| خيارات متقدمة | كتابة ملف التكوين agents/openai.yaml للمهارة وتعديل خيار allow_implicit_invocation: false لإلغاء الاستدعاء التلقائي وحصر تشغيلها بالاسم صراحة |
يجب أن تكون الآن قادراً على: فهم طبيعة مهارات الوكيل ودورها في حزم المهام المكررة واستيعاب ميزة الإفصاح التدريجي لحماية الذاكرة؛ وصياغة حقل الشرح بدقة لزيادة دقة الاستدعاء الضمني أو استخدام الرمز $ للاستدعاء الصريح؛ وحفظ الملفات في مجلدات .agents/skills وتجنب المسارات الخاطئة؛ واستخدام أدوات الإنشاء والتثبيت والإيقاف. هذه القدرة على حزم وسير العمل في مهارات هي ما يحول Codex من مساعد كود تقليدي إلى شريك عمل يتقن وينفذ أساليب ومعايير عملك المخصصة بكلمة واحدة.
تذكر دائماً القيود والأخطاء الشائعة - واحفظ قاعدة "تحفظ المهارات في مجلدات .agents/skills والرمز المعتمد للاستدعاء هو $ ويجب كتابة الكلمات المفتاحية في بداية الشرح لتلافي الحذف" لتسريع العمل وتجنب المشاكل.
المقال التالي [23 · الإضافات (Plugins)] - ساعدتنا المهارات على حزم وتسهيل العمليات المكررة وتطبيقها محلياً، ولكن عند الرغبة في مشاركة وتوزيع هذه المهارات وإعداداتها البرمجية المرفقة ومخازن التكوين مع أعضاء الفريق أو المجتمع لتثبيتها بضغطة زر، فنحن بحاجة لوعاء توزيع أشمل. سنتحدث في المقال القادم بالتفصيل عن الإضافات (Plugins): وكيفية تجميع المهارات والوكلاء والتكوينات وحزمها في إضافة برمجية واحدة قابلة للنشر والتثبيت بضغطة زر، لتحويل تفضيلاتك وتطويرك لأدوات وحلول برمجية يسهل مشاركتها والعمل بها.