الإجابة المختصرة
- 1استدعها باسمها:
/skill-nameأو$skill-name. إذا اشتغلت، فالتثبيت سليم. - 2لم يعثر عليها؟ تحقق من المجلد. يجب أن يكون
SKILL.mdمباشرة داخل<skills folder>/<name>/. - 3ما زلت عالقًا؟ ابحث أدناه عما تواجهه.
اعثر على المشكلة في 30 ثانية
طابق ما تواجهه مع العمود الأول، ثم انتقل إلى الحل في العمود المقابل.
يفشل استدعاؤها باسمها
ليست في مكان يبحث فيه الوكيل. راجع المهارة لا تظهر.
تعمل باسمها لكن لا تعمل عند طلب عادي
تحقق من الوصف أوالإعدادات. راجع المهارة لا تتفعّل.
تعمل مهارة أخرى
يوجد تداخل بين وصفين. راجع تعمل مهارة غير مقصودة.
تبدأ ثم تتوقف
إحدى التبعيات مفقودة. راجع تفشل أثناء التنفيذ.
تشغّل الإصدار القديم
توجد نسخة ثانية، أوالجلسة لم تتحدث. راجع إصدار قديم.
المهارة لا تظهر في Claude Code أوCodex أوCursor
إذا لم تظهر المهارة في /skills أوCustomize → Skills، فالوكيل لم يحمّلها. غالبًا يكون المجلد في المكان الخطأ أو أعمق بمستوى واحد من المطلوب.
| السبب المحتمل | الحل |
|---|---|
ثبّتها لـClaude Code باستخدام Skillry CLI لكنك لم تضف --agent claude-code | أعد التثبيت مع هذا الخيار. من دونه، تستخدم CLI المسار ~/.agents/skills/ |
| أضاف ZIP مستوى إضافيًا للمجلد | انقل المجلد الداخلي مستوى واحدًا إلى أعلى. يحتاج Claude Code إلى المسار skills/<name>/SKILL.md بالضبط |
خطأ في الترويسة بين سطرَي --- | صحّحه. يحتاج Codex وCursor إلى name وdescription، ويجب في Cursor أن يطابق name اسم المجلد |
| لم يكتشفها الوكيل بعد | Claude Code: شغّل /reload-skills. Codex: أعد تشغيله داخل المستودع. Cursor: افتح محادثة جديدة أوأعد تحميل النافذة |
Codex في تطبيق ChatGPT لسطح المكتب: لا يعثر $ على شيء | مشكلة مُبلّغ عنها (openai/codex#28505). تحقق من /skills، أوأعد التشغيل، أوجرّب وضع نسخة في ~/.codex/skills/ (لم نختبر ذلك بعد) |
لمعرفة كل المجلدات التي يقرؤها كل وكيل، راجع مواقع المهارات.
المهارة تظهر لكنها لا تتفعّل تلقائيًا
يقرر الوكيل استخدام المهارة بقراءة وصفها. إذا لم تعمل إلا عند استدعائها باسمها، فإما أن وصفها لا يطابق طريقة طلبك، أوأن أحد الإعدادات يمنعها.
- جرّب التعليمة النموذجية في صفحة المهارة. فقد كُتبت لتطابق الوصف.
- راجع
paths. فهو يقصر الاستخدام التلقائي على الملفات المطابقة. - هل ثبّتَّ مهارات كثيرة؟ يختصر الوكيل الأوصاف أويحذف بعضها ليستوعبها جميعًا، لذا ضع الاستخدام الأساسي أولًا. راجع التفعيل.
تعمل مهارة مختلفة بدلًا منها
عندما تصف مهارتان مثبتتان العمل نفسه، تتنافسان ويختار الوكيل الوصف الأقرب إلى طلبك. عادةً يعني ذلك وجود مهارتين لعمل متشابه، أوتثبيت المهارة نفسها مرتين.
| ما الذي يحدث؟ | الحل |
|---|---|
| تُختار مهارة مشابهة باستمرار | استدعِ المهارة التي تريدها باسمها: /skill-name في Claude Code وCursor، و$skill-name في Codex. الاستدعاء بالاسم يشغّل تلك المهارة دائمًا. |
| أوصاف مهاراتك متداخلة | ضيّق نطاق كل وصف بحسب المدخلات أوالجمهور أوالمخرجات حتى تختص كل مهارة بمهمة واحدة. راجع التفعيل. |
| الاسم نفسه مثبت مرتين | يقدّم Claude Code نسخة المؤسسة، ثم الشخصية، ثم نسخة المشروع. وقد يعرض Codex النسختين. احتفظ بنسخة واحدة. |
| تبدأ مهارة باستمرار دون أن تطلبها | اجعل وصفها أكثر تحديدًا لموعد استخدامها، حتى لا يطابق طلبات غير مرتبطة. ثم استدعِ المهارة المطلوبة باسمها. راجع التفعيل. |
تبدأ ثم تفشل أثناء التنفيذ
غالبًا ما تكون إحدى التبعيات مفقودة: إصدار Node.js غير مناسب، أوغياب Python أوFFmpeg أومفتاح FAL. توضح صفحة المهارة متطلباتها، لذا راجعها أولًا:

تستمر في تشغيل الإصدار القديم
حدّثت المهارة لكن الوكيل لا يزال يعمل بالطريقة القديمة. أحد الأسباب التالية هو المسؤول:
- استُبدل
SKILL.mdوحده. أعد التثبيت باستخدام--force، أواستبدل المجلد كاملًا. - توجد نسخة أخرى بالاسم نفسه في مكان آخر. أزلها.
- في Claude Code، تبقى المهارة التي شُغّلت سابقًا على حالها لبقية المحادثة. ابدأ محادثة جديدة لالتقاط تعديلاتك.
للنسخ الاحتياطي والعودة إلى إصدار سابق، راجع الإدارة والتحديث.
تعمل على جهازك ولا تعمل في السحابة
تعمل الجلسات السحابية على جهاز آخر، لذا لا تنتقل إليها المهارة الموجودة على جهازك وحده إلا إذا أعددتها لذلك:
| الوكيل | الحل |
|---|---|
| Claude Code | الجلسات السحابية: أضفها إلى Git في .claude/skills/، أوفعّلها في claude.ai. وفي Cowork: فعّلها في claude.ai. |
| Codex | لا تصل المهارات المستقلة إلى ChatGPT على الويب أوالهاتف. وزّعها ضمن إضافة. |
| Cursor | ضعها في ~/.cursor/skills/، ثم فعّل Settings → Agents → Context and Tools → Sync Skills for Cloud Agents. |
رسائل أخطاء Skillry CLI
اعثر على الرسالة التي طبعتها Skillry CLI، ثم اتبع الإجراء في العمود المقابل.
| الرسالة التي تراها | الإجراء المطلوب |
|---|---|
| “Not logged in.” أو“Session expired.” — لم تسجّل الدخول أو انتهت الجلسة | شغّل npx --yes skillry-cli@latest login |
| “…already exists. Re-run with --force to replace it safely.” — النسخة موجودة؛ أعد التشغيل مع --force لاستبدالها بأمان | أضف --force. تُنشأ نسخة احتياطية من نسختك القديمة |
| “This Skill requires a paid plan.” — تتطلب هذه المهارة خطة مدفوعة | تحقق من سعر المهارة أوخطتك |
| “--agent and --target cannot be used together.” — لا يمكن الجمع بين الخيارين | اختر أحد الخيارين |
| “Secure session storage is currently supported on macOS and Windows only.” — تخزين الجلسة الآمن مدعوم حاليًا على macOS وWindows فقط | إصدار CLI لديك أقدم من 0.2.2. شغّلها باستخدام npx --yes skillry-cli@latest للحصول على الإصدار الذي يعمل على Linux |
| “Refusing to use … because other users can access it.” — رُفض استخدام الملف لأن مستخدمين آخرين يستطيعون الوصول إليه | على Linux، أصبحت أذونات ملف الجلسة تسمح لمستخدمين آخرين بالوصول إليه. احذف الملف المذكور، ثم سجّل الدخول مجددًا |
أسئلة شائعة
لماذا لا تُحمَّل مهارتي في Claude Code؟
غالبًا ما تكون في ~/.agents/skills/ بدلًا من ~/.claude/skills/، أويوجد مستوى إضافي للمجلد. صحّح المسار، ثم شغّل /reload-skills إذا كان المجلد جديدًا.
لماذا تطلب مهارتي مفتاح API؟
لأنها تستخدم خدمة مدفوعة مذكورة تحت «التكاليف الخارجية» في صفحة المهارة. اضبط المفتاح بالطريقة التي تحددها تلك الخدمة، ولا تلصقه في المحادثة أبدًا.
كيف أعرف أن التثبيت نجح؟
تظهر في /skills (أوCustomize → Skills في Cursor)، وتعمل عند استدعائها باسمها.
المصادر
هل ساعدك هذا الدليل؟
