المهارات والأدوات
توجد المهارات المشتركة في .agents/skills/. عدّل هذه المصادر، ثم شغّل yarn ai-workflow:sync لتوليد .claude/skills/ من أجل Claude Code. يكتشف Codex المهارات مباشرةً في .agents/skills/.
توجد تعليمات الأدوار المشتركة في .agents/roles/*.md. وهذه صيغة مصدر خاصة بهذا المستودع، وليست مسارًا أصليًا يكتشف منه الوكلاء. ويحوّل scripts/ai-workflow-files.mjs هذه المصادر إلى الملفات الخاصة بكل تطبيق المذكورة أدناه؛ ويكتبها yarn ai-workflow:sync. أودِع الملفات المولَّدة إلى جانب مصادرها حتى تحصل أي نسخة جديدة من المستودع على الإعداد الأصلي دون تشغيل مولّد أولًا. وبعد حذف مصدر ما، احذف مخرجاته المولَّدة المتقادمة صراحةً؛ فأداة التحقق تبلّغ عنها بدلًا من حذف الملفات بصمت.
مسارات الاكتشاف الأصلية
جرى التحقق منها مقابل التوثيق الرسمي في 2026-09-12:
| التطبيق | تعليمات المشروع | المهارات التي يستخدمها هذا المستودع | الوكلاء المخصّصون الذين يستخدمهم هذا المستودع |
|---|---|---|---|
| Codex | AGENTS.md | .agents/skills/<name>/SKILL.md | يُولَّد في .codex/agents/<name>.toml |
| Claude Code | يستورد CLAUDE.md الملف @AGENTS.md | يُولَّد في .claude/skills/<name>/SKILL.md | يُولَّد في .claude/agents/<name>.md |
المصادر: مهارات Codex، والوكلاء الفرعيون في Codex، وذاكرة Claude، ومهارات Claude، والوكلاء الفرعيون في Claude.
لا تستبدل مجلدات الوكلاء الأصلية بـ .agents/roles، ولا تفترض أن Claude يكتشف .agents/skills. لكن Claude يظل قادرًا على قراءة ملف مُشار إليه هناك بوصفه سياقًا عاديًا للمشروع.
تستخدم مجلدات الذكاء الاصطناعي نهايات أسطر LF عبر .gitattributes حتى يبقى النص المولَّد متطابقًا على مختلف المنصات. وتُنسخ أصول المهارات المساندة بايتًا ببايت.
المهارات
| المهارة | الغرض |
|---|---|
commit | إنشاء إيداعات محلية مصرَّح بها ومحددة النطاق |
commit-format، issue-format | تنسيق الاقتراحات عند طلبها |
make-closed-issue | إنشاء مشكلة مصرَّح بها مع إيداع محدد النطاق وطلب سحب |
review-and-merge-pr | فرز ملاحظات طلب السحب؛ والإصلاح أو النشر أو الدمج ضمن النطاق المطلوب فقط |
fix-merge-conflicts | حل التعارضات والتحقق من النتيجة بعد الدمج |
release | إعداد صياغة الإصدار وتنفيذ خطوات الإصدار المصرَّح بها |
code-quality-review | مراجعة فروق التغييرات غير البسيطة أو مسألة جودة طُلبت صراحةً |
retro | تحويل الأخطاء التي ثبت وقوعها إلى فحوص أو إرشادات مركّزة تمنع تكرارها |
refactor-pass، deslop | تنظيف مطلوب للتغييرات القائمة |
debug-agent | تصحيح أخطاء قائم على الأدلة، مع إضافة أدوات رصد عند الحاجة |
you-might-not-need-an-effect | مراجعة مركّزة للتأثيرات وmemo |
vercel-react-best-practices | إرشادات أداء React المنطبقة؛ مع تخطي قواعد Next.js والقواعد الخاصة بالخادم في عميل Vite هذا |
translate | توليد الترجمات، ثم تطبيق الخرائط عبر كاتب واحد |
playwright-cli، inspect-elements | التحقق عبر المتصفح وربط عناصر DOM بالشيفرة المصدرية |
profile-browsing | تنميط محدد النطاق للمتصفح وReact |
test-apk | التحقق من غلاف Android المرافق المقدَّم |
impeccable، improve-threejs | تصميم واجهات محدد النطاق ومراجعة العرض في Three.js |
implement-plan | تنفيذ خطة مع تفويض اختياري محدود |
readme | صيانة توثيق المشروع بعد التحقق منه |
context7 | جلب توثيق المكتبات المناسب للإصدار المستخدم |
find-skills | العثور على مهارات إضافية عند طلب ذلك صراحةً |
الأدوار والنماذج
احتفظ بالأدوار المخصّصة browser-check وprofiler وtest-apk وtranslator وreviewer. واستخدم دور العامل أو الدور العام أو دور المستكشف المدمج في بيئة الوكيل للتنفيذ العادي ولاستكشاف الشيفرة. يحدد الوكيل الأب معايير القبول والملكية؛ ويتولى مالك واحد تشغيل الفحوص الثقيلة.
تتضمن ملفات وكلاء Codex الحقول name وdescription وdeveloper_instructions. ويحدّ .codex/config.toml عدد الوكلاء الفرعيين المتزامنين بأربعة عبر max_concurrent_threads_per_session. وتتضمن البيانات الوصفية المشتركة للأدوار الاسم والوصف ووضع صندوق العزل الاختياري؛ ولا تحتوي عمدًا على أي حقول للنموذج.
أبقِ حقول النموذج ومستوى الاستدلال خارج المهارات والوكلاء المخصّصين المُودَعين. فهذا يتيح خيارات الاستدعاء وقت التشغيل، وإعدادات المستخدم الافتراضية، والوراثة من الوكيل الأب وفق ترتيب الأولوية الموثّق لكل تطبيق. وتقلّل الأسماء البديلة لعائلات Claude أعباء متابعة الإصدارات لكنها تظل تختار عائلة بعينها. واحتفظ بمثل هذه الخيارات في إعدادات المستخدم أو الجلسة عند الحاجة. ولا تَعِد الوراثة باختيار تلقائي لأفضل نموذج حالي. ولا تخترع اسمًا بديلًا باسم latest، ولا تضف بحثًا في فهارس النماذج إلى المهام الروتينية. راجع اختيار النموذج في Codex، واختيار النموذج في Claude.
يُقابَل sandbox-mode: read-only بصندوق العزل في Codex. أما في Claude فتقيّد قائمة الأدوات وتعليمات الدور سير عمل المراجعة، لكن الوصول إلى Bash ليس صندوق عزل على مستوى نظام التشغيل.
تستخدم الترويسة الأمامية للمهارات المشتركة disable-model-invocation: true لسير العمل الذي يستدعيه المستخدم حيثما ينطبق ذلك. ويوجد الإعداد المقابل في Codex داخل agents/openai.yaml بصيغة policy.allow_implicit_invocation: false؛ وتشترط أداة التحقق وجود الاثنين معًا. وتُكمل بيانات الاستدعاء الوصفية قواعد التفويض الصريحة؛ فطلب المراجعة لا يجيز النشر أبدًا لمجرد أن مهارة ما تتضمن خطوات نشر.
الفحوص والاكتشاف
- يعيد
yarn ai-workflow:syncتوليد مخرجات التوافق باستخدامjs-yamlوsmol-tomlالمثبّتتين. - يحلل
yarn ai-workflow:checkالمصادر والترويسات الأمامية والإعدادات، ويفحص المخرجات المولَّدة، وبيانات الاستدعاء الوصفية، وموضع حقول النموذج، وربط الخطاف المقتصر على التنسيق. ولا يتحقق من معرّفات النماذج مقابل فهرس أي مزوّد. - يشغّل
yarn ai-workflow:testتجهيزات اختبار Node معزولة لحمولات الخطافات ولتوليد سير العمل والتحقق منه. - بعد ترقية أي تطبيق وكيل، تحقق من اكتشاف المهارات والأدوار داخل ذلك التطبيق. ففحوص الصياغة والتطابق لا تغني عن فحص المُحمِّل. وأعد تحميل التطبيق إذا احتفظت جلسة قائمة بفهرس قديم.
- تتطلب الخطافات ثقة بيئة الوكيل بالمشروع ومراجعة الخطافات؛ فلا تتجاوز الثقة لكي ينجح فحص ما. راجع hooks-setup.md.
الحفاظ على تعليمات مفيدة
اتبع إرشادات OpenAI بشأن المهارات والتعليمات (رُوجعت في 2026-09-12): اجعل الأوصاف دقيقة، ولا تحمّل التفاصيل إلا عند الحاجة إليها، وحافظ على النطاق الذي طلبه المستخدم. فالمهارات المشتركة تخدم نماذج مختلفة؛ لذا احتفظ بالثوابت الخاصة بالمشروع مع ترك خيارات التنفيذ الروتينية مفتوحة.
احتفظ بغرض المهارة وحدود قراراتها وقيودها الأساسية في SKILL.md. واربط الأوامر أو الأمثلة الكبيرة الخاصة بوضع معيّن بوصفها مراجع اختيارية. وضع شروط التفعيل في بداية الأوصاف القصيرة؛ فلا ينبغي لمجرد تطابق كلمة مفتاحية أن يوسّع المهمة. وحافظ على بيانات الاستدعاء الوصفية القائمة ما لم يكن تغيير سلوكها مقصودًا.
بعد أي تغيير جوهري في التعليمات، جرّب بضعة طلبات تمثيلية صغيرة وكبيرة. وتحقق من المهارات والمراجع التي اختيرت، ومن بقاء الإجراءات ضمن النطاق، ومن ملاءمة التحقق للتغيير، ومن اكتمال العمل المصرَّح به. فاختبارات المخططات وتجهيزات الاختبار تثبت صحة الأدوات، لا جودة قرارات الوكيل.
الأدوات وملكية المتصفح
فضّل فهرس المهارات والأدوات القائم وأدوات CLI المثبّتة في المشروع. استخدم gh لـ GitHub، وplaywright-cli للتحقق عبر المتصفح، والتوثيق الرسمي أو الخاص بالإصدار عندما يكون سلوك المكتبة مهمًا. وتجنّب تثبيت مهارات مكرّرة أو جلب حزمة غير محددة الإصدار لمجرد تشغيل أداة تنسيق موجودة.
يتوقف عبء MCP على بيئة الوكيل: فالتحميل المؤجَّل للأدوات قد يُغني عن تحميل كل المخططات مسبقًا. أبقِ التكاملات ذات صلة بدلًا من معاملة MCP نفسه كأمر متقادم. وتظل خيارات CLI القائمة مفيدة لقابلية إعادة الإنتاج وللتحكم في الموارد.
تستخدم كل جلسات المتصفح ./scripts/pw-session.sh، الذي يفرض متصفحًا نشطًا واحدًا على مستوى الجهاز كله. واجعل الافتراض جلسة جديدة معزولة. ويحتاج الوصول الحالي إلى المتصفح الشخصي إلى تفويض صريح؛ وأعد استخدام ذلك التفويض في الخطوات اللاحقة. واختر المتصفحات ونوافذ العرض بحسب السلوك المتأثر، وشغّل المحركات المختارة بالتتابع، وأغلق الجلسة المسمّاة بعينها عند التنظيف، ولا تستخدم أبدًا close-all أو kill-all. راجع مهارة playwright-cli وverification.md.