ملاحظة من المؤلف: شرح مفصل للاختلافات في تحديد موقع مجلدي التكوين .agents و .claude في تطوير وكلاء الذكاء الاصطناعي، ومواصفات تخزين المهارات، ومقارنة بنية الدليل، ومشهد التطبيق لملفي AGENTS.md و CLAUDE.md
تطوير وكلاء الذكاء الاصطناعي (AI Agents) يزداد شعبية، وبدأت مجلدات التكوين المختلفة تظهر في الدليل الجذر للمشروع – مثل .agents و .claude و .cursor… يمكن لكل من .agents و .claude وضع المهارات (Skills)، ولكن تحديد موقعهما، وفلسفة تصميمهما، ونطاق تطبيقهما تختلف تمامًا. اختيار مكان خاطئ لتخزين المهارات قد يؤدي إلى عدم تفعيلها في أحسن الأحوال، أو إلى تعارض في التكوين عند العمل الجماعي في أسوأ الأحوال. سيوضح هذا المقال الاختلافات الأساسية بينهما من منظور التصميم الأساسي، وأفضل الممارسات.
القيمة الأساسية: بعد قراءة هذا المقال، ستكون قادرًا على تحديد ما إذا كان يجب وضع المهارات في .agents أو .claude، وكيفية إدارة تكوينات الوكلاء بكفاءة في فريق متعدد الأدوات.
النقاط الأساسية للمجلدين .agents و .claude
لنجب أولاً على السؤال الأكثر أهمية: هذان المجلدان ليسا في علاقة تنافسية، بل هما نظامان مختلفان من مستويات التكوين.
| بُعد المقارنة | مجلد .claude/ |
مجلد .agents/ |
|---|---|---|
| الجهة المالكة | Anthropic (خاص بـ Claude Code) | مؤسسة Agentic AI / مؤسسة Linux |
| الموقع | دليل تكوين مشروع Claude Code | معيار تكوين الوكيل (Agent) المستقل عن الأدوات |
| تنسيق المهارات (Skills) | SKILL.md (Markdown + بيانات وصفية YAML في المقدمة) |
SKILL.yaml (YAML خالص) |
| النضج | جاهز للإنتاج، مدعوم رسميًا من Claude Code | قيد وضع المعايير (قيد العمل) |
| دعم الأدوات المتعددة | Claude Code فقط | الهدف التصميمي هو جميع أدوات الوكيل (Agent) |
اختلافات فلسفة التصميم بين مجلدي .agents و .claude
يكمن الاختلاف الجوهري بين هذين المجلدين في فلسفة التصميم:
مجلد .claude/ يتبع نهج "التكامل العميق الحصري". تم تصميمه خصيصًا لـ Claude Code، ويوفر قدرات كاملة للمهارات (Skills)، والوكلاء الفرعيين (Subagents)، والخطافات (Hooks)، والأذونات (Permissions)، وهو مرتبط بعمق بسلسلة أدوات Claude Code. ميزته هي الوظائف الكاملة، وجاهزيته للاستخدام الفوري؛ أما ثمنه فهو الارتباط بالنظام البيئي لـ Claude Code.
مجلد .agents/ يتبع نهج "المعيار العام عبر الأدوات". يحاول تحديد مواصفات تكوين يمكن لجميع أدوات الوكيل (AI Agent) قراءتها، على غرار .editorconfig للمحررات. ميزته هي أن تكوينًا واحدًا يعمل مع أدوات متعددة؛ أما ثمنه فهو أن المعيار لا يزال قيد التطور، وتختلف درجة الدعم من قبل الأدوات.
يمكن لهذين المجلدين التعايش تمامًا في نفس المشروع – يتم وضع التكوينات العميقة الخاصة بـ Claude Code في .claude/، والتكوينات العامة القابلة لإعادة الاستخدام عبر الأدوات في .agents/.
هيكل الدليل الكامل لمجلد .claude
لنلقِ نظرة أولاً على مجلد Claude Code الأصلي .claude/، وهو التنفيذ الأكثر نضجًا حاليًا.
شرح تفصيلي لهيكل دليل مجلد .claude
.claude/
├── CLAUDE.md # تعليمات المشروع (بديل لـ CLAUDE.md في الدليل الجذر)
├── settings.json # إعدادات المشروع (يتم إرسالها إلى git، للمشاركة بين الفريق)
├── settings.local.json # إعدادات محلية (في gitignore، تكوين شخصي)
├── skills/ # دليل مهارات (Skills)
│ └── <skill-name>/
│ ├── SKILL.md # ملف تعريف المهارة (مطلوب)
│ ├── scripts/ # نصوص برمجية مساعدة
│ ├── references/ # مواد مرجعية
│ └── templates/ # ملفات قوالب
├── agents/ # تعريفات الوكلاء الفرعيين (Subagents)
│ └── <agent-name>.md # ملف تعريف الوكيل الفرعي
├── commands/ # أوامر الشرطة المائلة للإصدار القديم (تم دمجها في skills)
│ └── <command-name>.md
└── agent-memory/ # ذاكرة الوكيل الفرعي الدائمة
└── <agent-name>/
└── MEMORY.md
بالإضافة إلى ذلك، يوجد دليل على مستوى المستخدم ~/.claude/، حيث يمكن وضع المهارات (Skills) الشخصية لتكون فعالة في جميع المشاريع:
~/.claude/
├── CLAUDE.md # تعليمات على مستوى المستخدم (عبر المشاريع)
├── settings.json # إعدادات على مستوى المستخدم
├── skills/ # مهارات شخصية (متاحة في جميع المشاريع)
├── agents/ # وكلاء فرعيون شخصيون
└── projects/ # سجلات الجلسات والبيانات
تنسيق SKILL.md لمهارات مجلد .claude
تستخدم مهارات Claude Code ملف Markdown مع بيانات وصفية YAML في المقدمة:
---
name: my-skill
description: وصف المهارة، يساعد Claude على تحديد وقت تشغيلها
user-invocable: true # يمكن للمستخدم استدعاؤها عبر /my-skill
allowed-tools: Read, Grep # تقييد الأدوات المتاحة
context: fork # التشغيل في وكيل فرعي مستقل
model: sonnet # تغطية النموذج
---
أنت مساعد متخصص لمراجعة الكود...
(تعليمات المهارة بتنسيق Markdown)
شرح الحقول الرئيسية:
- المهارات التي تحتوي على
user-invocable: trueسيتم تسجيلها كـ/slash-command context: forkيعني التشغيل في سياق مستقل، ولن يؤثر على المحادثة الرئيسيةallowed-toolsيمكنها تقييد مجموعة الأدوات التي يمكن للمهارة استخدامها- دعم استبدال المعلمات
$ARGUMENTS،$0،$1
🎯 نصيحة التطوير: يتبع نظام مهارات Claude Code معيار المهارات المفتوحة للوكلاء (agentskills.io)، والتنسيق مشترك بين Claude Code و Claude API و VS Code Copilot.
إذا كنت تقوم بتطوير تطبيقات الذكاء الاصطناعي باستخدام Claude Code، فمن المستحسن الحصول على مفتاح API عبر APIYI apiyi.com لإدارة استدعاءات النماذج المتعددة بشكل موحد.
الهيكل الكامل للمجلد .agents
يتم الاحتفاظ بمواصفات مجلد .agents (مواصفات AGENTS-1) بواسطة مؤسسة Agentic AI، ويتم استضافتها تحت Linux Foundation، بهدف تحديد معيار تكوين عام يمكن لجميع أدوات ترميز الذكاء الاصطناعي فهمه.
شرح تفصيلي لهيكل مجلد .agents
.agents/
├── manifest.yaml # مطلوب: يسجل سجل التكوينات، ويعلن عن جميع التكوينات المتاحة
├── prompts/ # مطلوب: موجهات التعليمات
│ ├── base.md # تعليمات عامة للوكيل
│ ├── project.md # تعليمات خاصة بالمشروع
│ └── snippets/ # مقاطع تعليمات نمطية
├── modes/ # مطلوب: أنماط السلوك (مشابه لـ .claude/agents/)
│ ├── plan.md # نمط التخطيط
│ ├── code.md # نمط الترميز
│ └── review.md # نمط المراجعة
├── policies/ # مطلوب: سياسات الأمان وقيود القدرات
├── skills/ # مطلوب: تعريفات المهارات (تتبع مواصفات مهارات الوكيل)
│ └── <name>/
│ └── SKILL.yaml # تعريف المهارة بتنسيق YAML
├── scopes/ # مطلوب: تجاوزات على مستوى المسار (دعم Monorepo)
├── profiles/ # مطلوب: تراكبات تكوين مسماة (dev/ci/staging)
├── schemas/ # مطلوب: التحقق من صحة مخطط JSON
└── state/ # الحالة المحلية (لا يتم إرسالها إلى git)
├── .gitignore
└── state.yaml
على عكس .claude/ الذي يستخدم SKILL.md (Markdown) لمهاراته، يستخدم .agents/ تنسيق SKILL.yaml (YAML عادي) لمهاراته.
التصميم الفريد لمجلد .agents
يحتوي مواصفات .agents على عدة مفاهيم غير موجودة في .claude/:
- Scopes (النطاقات): تحديد تكوينات مختلفة للدلائل الفرعية المختلفة في Monorepo، مع إعطاء الأولوية للمسار الأكثر تحديدًا.
- Profiles (ملفات التعريف): دعم تراكبات التكوين المسماة مثل
devوciوprod، مشابه لمتغيرات البيئة. - Policies (السياسات): دليل مستقل لقيود الأمان، حيث تتجاوز قواعد الرفض دائمًا قواعد السماح.
- Determinism (الحتمية): يجب أن ينتج نفس الإدخال نفس الإخراج، دون الاعتماد على الحالة الخارجية.
مقارنة قواعد تخزين المهارات في مجلدي .agents و .claude
هذه هي المسألة العملية الأكثر أهمية للمطورين: أين أضع مهاراتي بالضبط؟
مقارنة مهارات مجلدي .agents و .claude
| بُعد المقارنة | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| ملف التعريف | SKILL.md (Markdown + YAML frontmatter) |
SKILL.yaml (YAML عادي) |
| دعم Claude Code | دعم أصلي، اكتشاف تلقائي | يتطلب تكوينًا يدويًا أو انتظار دعم رسمي |
| أوامر الشرطة المائلة | user-invocable: true يسجل تلقائيًا /command |
يعتمد على تنفيذ الأداة المحدد |
| تشغيل وكيل فرعي | context: fork يعمل في سياق مستقل |
يتم تكوينه عبر modes/ |
| تجاوز النموذج | model: sonnet يحدد مباشرة |
يتم تكوينه عبر profiles/ |
| قيود الأدوات | allowed-tools: Read, Grep |
يتم تكوينها عبر policies/ |
| الملفات المساعدة | الدلائل الفرعية scripts/ و references/ و templates/ |
يعتمد على التنفيذ |
| تمرير المعلمات | استبدال المتغيرات $ARGUMENTS و $0 و $1 |
لم يتم تحديده بوضوح في المواصفات |
كيف يمكن لمجلدي .agents و .claude التعايش
في المشاريع العملية، يمكن للمجلدين التعايش ويكمل كل منهما الآخر. خذ هذا المشروع كمثال:
.claude/skills/ لتخزين المهارات الخاصة بـ Claude Code:
apiyi-article-generator— مولد المقالات، يتكامل بعمق مع قوالب المشروع ومواصفاته.apiyi-svg-generator— مولد رسوم SVG، يعتمد على قوالب SVG الخاصة بالمشروع.apiyi-content-reviewer— مراجع المحتوى، يستخدم معايير جودة المشروع.
.agents/skills/ لتخزين المهارات العامة القابلة للنقل:
markdown-proxy— جلب URL إلى Markdown، باستخدام سكربت Python.nano-banana-pro-image-gen— توليد الصور، يستدعي واجهة برمجة تطبيقات خارجية.
مبدأ التقسيم واضح: ضع المهارات المتكاملة بعمق مع Claude Code في .claude/، والمهارات التي يمكن استخدامها في أدوات الذكاء الاصطناعي الأخرى في .agents/.
🎯 اقتراح الاختيار: إذا كان فريقك يستخدم Claude Code فقط، فضع كل شيء في
.claude/skills/، وستحصل على الوظائف الأكثر اكتمالاً.
إذا كان أعضاء الفريق يستخدمون أدوات ذكاء اصطناعي مختلفة (Cursor، Windsurf، Codex، إلخ)، فإن وضع المهارات العامة في.agents/skills/يسهل التعاون.
نوصي بإدارة استدعاءات واجهة برمجة التطبيقات في تطوير وكيل الذكاء الاصطناعي بشكل موحد عبر APIYI apiyi.com، مع مفتاح واحد يغطي نماذج متعددة.
مقارنة ملفات التوجيهات المرافقة لـ .agents و .claude
بالإضافة إلى مجلد المهارات (Skills)، تمتلك كلتا المنظومتين ملفات توجيهات خاصة بالمشروع.
الاختلافات بين CLAUDE.md و AGENTS.md
| بُعد المقارنة | CLAUDE.md | AGENTS.md |
|---|---|---|
| الأدوات المدعومة | Claude Code | Claude Code، OpenAI Codex، Google Jules، Cursor، GitHub Copilot، إلخ. |
| مستوى الملف | مستوى المستخدم (~/.claude/) → مستوى المشروع (./) → مستوى الدليل الفرعي |
مستوى المشروع (./) → مستوى الدليل الفرعي |
| التغطية المحلية | CLAUDE.local.md (يتم تجاهله بواسطة gitignore) |
لا يوجد |
| التوحيد الرسمي | لا يوجد (وثائق منتجات Anthropic) | يوجد (مؤسسة Agentic AI تحت مؤسسة Linux) |
| حجم النظام البيئي | في تزايد (معتمد من Next.js، LangChain، Deno، إلخ.) | واسع النطاق (n8n 178 ألف نجمة، llama.cpp 97 ألف نجمة، Bun 82 ألف نجمة) |
| التهيئة | أمر /init داخل Claude Code |
إنشاء يدوي |
اقتراح عملي: يمكن للملفين التعايش. يمكن وضع CLAUDE.md للتوجيهات الخاصة بـ Claude Code (مثل تكوينات الـ Hooks وقواعد الأذونات)، ووضع AGENTS.md لسياق المشروع العام لجميع أدوات الذكاء الاصطناعي (مثل أوامر البناء، ومعايير الترميز، ووصف البنية).
نظرة عامة على النظام البيئي للملفات المرافقة لـ .agents و .claude
| الملف/الدليل | النظام البيئي التابع له | الاستخدام | هل يتم إرساله إلى git؟ |
|---|---|---|---|
CLAUDE.md |
.claude | توجيهات مشروع Claude Code | نعم |
CLAUDE.local.md |
.claude | التوجيهات المحلية الشخصية | لا |
.claude/settings.json |
.claude | الأذونات، الـ Hooks، MCP | نعم |
.claude/settings.local.json |
.claude | الإعدادات المحلية الشخصية | لا |
AGENTS.md |
.agents | توجيهات مشروع Agent العام | نعم |
.agents/manifest.yaml |
.agents | سجل التكوين | نعم |
.agents/state/state.yaml |
.agents | حالة التشغيل المحلية | لا |
.cursorrules |
Cursor | قواعد Cursor الخاصة | نعم |
نصيحة: تشير دراسة من ETH Zurich في عام 2026 إلى أن ملفات السياق التي تم إنشاؤها بواسطة الذكاء الاصطناعي قد تقلل أحيانًا من أداء الوكيل (Agent)، لذا يُنصح بكتابتها يدويًا والحد منها إلى المعلومات غير الصريحة التي لا يمكن استنتاجها من الكود (مثل سلاسل الأدوات المخصصة، والأنماط غير التقليدية، وما إلى ذلك).
أسئلة متكررة
س1: هل يمكن لـ Claude Code قراءة المهارات (Skills) الموجودة في مجلد .agents/skills/؟
حاليًا، يقوم Claude Code تلقائيًا باكتشاف وتحميل المهارات (Skills) فقط من مجلد .claude/skills/. لن يتم التعرف على المحتوى الموجود في .agents/skills/ تلقائيًا. قدم المجتمع طلبًا (Issue #31005) على GitHub لدعم Claude Code لمجلد .agents/. إذا كنت بحاجة إلى أن تعمل مهاراتك في Claude Code، فيجب وضعها حاليًا في .claude/skills/.
س2: هل مواصفات مجلد .agents ناضجة؟ هل يمكن استخدامها في مشاريع الإنتاج؟
مواصفات مجلد .agents/ (AGENTS-1 Spec) لا تزال قيد التطوير (Work In Progress)، ولكن تم اعتماد ملف AGENTS.md على نطاق واسع – تستخدمه مشاريع مفتوحة المصدر كبيرة مثل n8n (178 ألف نجمة)، llama.cpp (97 ألف نجمة)، Bun (82 ألف نجمة). يُقترح استخدام AGENTS.md كملف تعليمات عام، واستخدام بنية مجلد .agents/ الكاملة بعد استقرار المواصفات.
س3: كيف يمكن إدارة الإعدادات عندما يستخدم أعضاء الفريق أدوات ذكاء اصطناعي مختلفة (Claude Code + Cursor)؟
نوصي بالإدارة المتدرجة: 1) ضع المعلومات العامة للمشروع في AGENTS.md (أوامر البناء، معايير الترميز)، والتي تقرأها جميع الأدوات؛ 2) ضع التعليمات الخاصة بـ Claude Code في CLAUDE.md؛ 3) ضع القواعد الخاصة بـ Cursor في .cursorrules. ضع المهارات العامة في .agents/skills/، والمهارات الخاصة بالأدوات في مجلداتها الخاصة. قم بإدارة استدعاءات واجهة برمجة تطبيقات الذكاء الاصطناعي الخاصة بالفريق بشكل موحد عبر APIYI apiyi.com، حيث توفر المنصة واجهة واحدة تغطي جميع النماذج.
س4: ما هو الفرق في التنسيق بين SKILL.md و SKILL.yaml؟
SKILL.md هو تنسيق Claude Code، يستخدم ملف Markdown مع بيانات وصفية YAML في المقدمة (frontmatter)، ويتم كتابة قسم التعليمات باستخدام Markdown، مما يجعله أكثر قابلية للقراءة للبشر. SKILL.yaml هو تنسيق مواصفات .agents/، ويستخدم تعريفات منظمة بالكامل بتنسيق YAML، مما يسهل تحليله آليًا. المعلومات الأساسية في كليهما (الاسم، الوصف، شروط التشغيل) متطابقة، والاختلاف الوحيد هو التنسيق.
ملخص
الفرق الأساسي بين مجلدي .agents و .claude:
- الغرض المختلف:
.claude/هو مجلد تكوين خاص بـ Claude Code، ويتكامل بعمق مع جميع ميزات Claude Code؛.agents/هو معيار عام عبر الأدوات تحت مؤسسة Linux Foundation. - تنسيق المهارات المختلف: يستخدم
.claude/skills/تنسيقSKILL.md(Markdown)، ويقوم Claude Code بتحميله أصلاً؛ يستخدم.agents/skills/تنسيقSKILL.yaml(YAML)، وهو مصمم ليكون مستقلاً عن الأداة. - يمكن أن يتعايشا ويكمل كل منهما الآخر: ضع ميزات Claude Code المتعمقة (Hooks، الوكلاء الفرعيون، الأذونات) في
.claude/، والمهارات العامة القابلة للنقل في.agents/، وتعليمات المشروع الأساسية فيAGENTS.md.
يعتمد اختيار المجلد على تركيبة سلسلة أدوات فريقك ومتطلبات قابلية نقل المهارات.
نوصي بإدارة استدعاءات النماذج في تطوير وكلاء الذكاء الاصطناعي بشكل موحد عبر APIYI apiyi.com. توفر المنصة حدودًا مجانية وواجهة موحدة للنماذج المتعددة، وتدعم الوصول الشامل إلى النماذج الرئيسية مثل Claude و GPT و Gemini.
📚 مصادر
-
وثائق Claude Code Skills الرسمية: تعريف كامل لـ Skills، تنسيقها وطرق استخدامها
- الرابط:
code.claude.com/docs/en/skills - الشرح: فهم تنسيق SKILL.md، وقواعد التشغيل، وتمرير المعاملات.
- الرابط:
-
وثائق Claude Code الفرعية (Subagents): تعريف وتكوين الوكلاء الفرعيين (Subagents)
- الرابط:
code.claude.com/docs/en/sub-agents - الشرح: فهم تنسيق الملفات في مجلد
.claude/agents/.
- الرابط:
-
الموقع الرسمي لـ AGENTS.md: معيار ملفات تعليمات الوكيل (Agent) متعدد الأدوات
- الرابط:
agents.md - الشرح: فهم مواصفات كتابة AGENTS.md وقائمة الأدوات المدعومة.
- الرابط:
-
مواصفات مجلد
.agents/: تعريف كامل لهيكل مجلد AGENTS-1 Spec- الرابط:
github.com/agentsfolder/spec - الشرح: فهم تصميم manifest.yaml، modes، policies، scopes.
- الرابط:
-
مركز وثائق APIYI: إدارة موحدة لاستدعاءات واجهات برمجة التطبيقات (API) في تطوير وكلاء الذكاء الاصطناعي (AI Agent)
- الرابط:
docs.apiyi.com - الشرح: دعم واجهة موحدة لنماذج متعددة، مناسبة لسيناريوهات تطوير الوكلاء.
- الرابط:
المؤلف: فريق APIYI التقني
تبادل تقني: نرحب بالمناقشة في قسم التعليقات، ولمزيد من المعلومات، تفضل بزيارة مركز وثائق APIYI على docs.apiyi.com.
