كيف تكتب أول ملف SKILL.md — دليل شامل لوكلاء البرمجة بالذكاء الاصطناعي

إذا سبق لك نسخ نفس التعليمات في ملفات CLAUDE.md و .cursorrules وإعدادات Copilot، فأنت تفهم بالفعل المشكلة التي تحلها مهارات الوكلاء. ملف SKILL.md واحد معياري يحل محل كل ذلك — ويعمل عبر أكثر من 30 أداة برمجة بالذكاء الاصطناعي دون تعديل.

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

المتطلبات الأساسية

قبل البدء، تأكد من توفر:

• أداة برمجة بالذكاء الاصطناعي مثبتة (Claude Code أو GitHub Copilot أو Cursor أو OpenAI Codex أو Google Gemini CLI)
• مستودع مشروع حيث تريد إضافة المهارات
• معرفة أساسية بصيغ YAML و Markdown
• طرفية ومحرر نصوص

إذا كنت جديداً على معيار مهارات الوكلاء، اقرأ مقالتنا التعريفية عن مهارات الوكلاء ومواصفات SKILL.md أولاً.

ماذا ستبني

بنهاية هذا الدليل ستكون قد أنشأت مهارتين عاملتين:

1. مهارة مراجعة الكود تُفعّل عندما تطلب مراجعة طلبات الدمج أو تدقيق الكود أو فحص الجودة
2. مهارة فحص النشر تشغل التحقق من جاهزية النشر مع سكربت مُرفق

كلتا المهارتين ستعملان عبر Claude Code و Codex و Copilot و Cursor و Gemini CLI و JetBrains Junie.

الخطوة 1: إنشاء مجلد المهارات

تعيش مهارات الوكلاء في مجلد .agents/skills/ في جذر المستودع. هذا هو الاتفاق المعتمد عبر جميع الأدوات المتوافقة.

mkdir -p .agents/skills/code-review
mkdir -p .agents/skills/deploy-checker

كل مهارة لها مجلدها الخاص. اسم المجلد للتنظيم البشري فقط — الوكيل يقرأ حقل name من SKILL.md وليس اسم المجلد.

هيكل مشروعك الآن يبدو هكذا:

your-project/
├── .agents/
│   └── skills/
│       ├── code-review/
│       │   └── (SKILL.md يوضع هنا)
│       └── deploy-checker/
│           └── (SKILL.md يوضع هنا)
├── src/
└── package.json

المجلدات الخاصة بالأدوات تعمل أيضاً. Claude Code يقرأ من .claude/skills/، و Cursor من .cursor/skills/، وهكذا. لكن .agents/skills/ هو الموقع العالمي الذي تتعرف عليه كل أداة. استخدمه لأقصى توافق.

الخطوة 2: كتابة البيانات الوصفية YAML

كل ملف SKILL.md يبدأ ببيانات وصفية YAML محاطة بثلاث شرطات. هذه هي البيانات التي يقرأها الوكيل عند بدء التشغيل.

أنشئ .agents/skills/code-review/SKILL.md وأضف:

---
name: code-review
description: >
  Reviews code changes for quality, security, and adherence to project
  conventions. Use when the user asks to 'review code', 'check this PR',
  'audit this change', 'look at my diff', or 'review my changes'.
---

الحقول المطلوبة

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

حقل description يستحق اهتماماً خاصاً — فهو آلية التفعيل التي تحدد ما إذا كانت مهارتك ستُفعّل أبداً.

الخطوة 3: كتابة وصف تفعيل قوي

الوصف ليس توثيقاً للبشر. إنه الإشارة الأساسية التي يستخدمها وكيل الذكاء الاصطناعي لتقرير ما إذا كان سيحمّل هذه المهارة لطلب معين.

وصف ضعيف (نادراً ما يُفعّل):

description: يساعد في جودة الكود

وصف قوي (يُفعّل بموثوقية):

description: >
  Reviews code changes for quality, security, and adherence to project
  conventions. Use when the user asks to 'review code', 'check this PR',
  'audit this change', 'look at my diff', or 'review my changes'.

ما يجعل الوصف فعالاً

1. حدد ماذا تفعل المهارة في الجملة الأولى
2. أدرج عبارات تفعيل محددة قد يقولها المستخدم — بين علامات اقتباس ومفصولة بفواصل
3. أضف مرادفات لنفس الإجراء (review, audit, check, look at)
4. حافظ على أقل من 200 كلمة — هذا يُحمّل مع كل بداية محادثة

اختبار وصفك

بعد كتابته، اختبر ذهنياً مع هذه الطلبات:

• "Can you review this PR?" — يجب أن يُفعّل
• "Check my code for security issues" — يجب أن يُفعّل
• "Write a new function" — يجب ألا يُفعّل
• "Deploy to production" — يجب ألا يُفعّل

الخطوة 4: كتابة نص التعليمات

تحت البيانات الوصفية، اكتب نص Markdown. هذه هي مجموعة التعليمات الفعلية التي تُحمّل عند تفعيل المهارة.

---
name: code-review
description: >
  Reviews code changes for quality, security, and adherence to project
  conventions. Use when the user asks to 'review code', 'check this PR',
  'audit this change', 'look at my diff', or 'review my changes'.
---
 
# Code Review
 
## سير العمل
 
1. اقرأ الفروقات أو الملفات المتغيرة باستخدام `git diff` أو مسارات الملفات المقدمة
2. افحص الثغرات الأمنية مقابل OWASP Top 10
3. تحقق من معالجة الأخطاء — لا كتل catch فارغة ولا أخطاء مبتلعة
4. افحص أسلوب الكود مقابل اتفاقيات المشروع
5. ابحث عن مشاكل الأداء — حلقات غير ضرورية وفهارس مفقودة واستعلامات N+1
6. تحقق من تغطية الاختبارات — الدوال العامة الجديدة يجب أن تُختبر
7. قدم ملاحظات منظمة
 
## صيغة المخرجات
 
نظّم كل مراجعة في ثلاثة أقسام:
 
### حرج (يجب الإصلاح قبل الدمج)
- ثغرات أمنية
- مخاطر فقدان بيانات
- تغييرات كاسرة بدون ترحيل
 
### تحذير (يُفضّل الإصلاح)
- معالجة أخطاء مفقودة
- مخاوف أداء
- تغطية اختبارات ناقصة
 
### اقتراح (تحسينات)
- تحسينات أسلوب الكود
- تحسينات قابلية القراءة
- فجوات التوثيق

نصائح الكتابة

• استخدم صيغة الأمر. "اقرأ الفروقات" وليس "يجب قراءة الفروقات"
• كن محدداً. "افحص حقن SQL في معاملات الاستعلام" وليس "افحص المشاكل الأمنية"
• حافظ على أقل من 5,000 رمز. إذا كان أطول، قسّمه إلى مهارات متعددة
• نظّم بالعناوين. الوكيل يتنقل بين الأقسام عبر العناوين

الخطوة 5: فهم الإفصاح التدريجي

تستخدم مهارات الوكلاء نظام تحميل من ثلاثة مستويات يوفر الرموز:

المستوى 1: البيانات الوصفية (تُحمّل دائماً)

عند بدء التشغيل، يقرأ الوكيل فقط name و description من البيانات الوصفية — حوالي 100 رمز لكل مهارة. مع 50 مهارة مثبتة، هذا حوالي 5,000 رمز إجمالاً.

المستوى 2: التعليمات (تُحمّل عند التفعيل)

عندما يتطابق طلب المستخدم مع وصف مهارة، يُحمّل نص SKILL.md الكامل — عادة أقل من 5,000 رمز.

المستوى 3: الموارد (تُحمّل عند الحاجة)

السكربتات والملفات المرجعية والقوالب تُحمّل فقط عند الإشارة إليها في التعليمات.

هذا يعني أن 50 مهارة مركزة تستهلك رموزاً أقل من ملف تهيئة واحد ضخم.

الخطوة 6: بناء مهارة فحص النشر

الآن لنبنِ مهارة أكثر تقدماً تتضمن سكربت قابل للتنفيذ.

أنشئ .agents/skills/deploy-checker/SKILL.md:

---
name: deploy-checker
description: >
  Validates deployment readiness before pushing to staging or production.
  Use when the user says 'check deploy', 'pre-deploy check', 'is this
  ready to deploy', 'deployment readiness', or 'can we ship this'.
allowed-tools: Read, Grep, Glob, Bash
---
 
# فحص جاهزية النشر
 
## سير العمل
 
1. شغّل سكربت فحص جاهزية النشر:
 
\`\`\`bash
bash .agents/skills/deploy-checker/scripts/check_deploy.sh
\`\`\`
 
2. راجع مخرجات السكربت لأي نتائج FAIL
3. إذا نجحت كل الفحوصات، أكّد جاهزية النشر
4. إذا فشل أي فحص، اشرح الفشل واقترح حلاً

إنشاء السكربت المُرفق

أنشئ .agents/skills/deploy-checker/scripts/check_deploy.sh:

#!/bin/bash
# فحوصات جاهزية النشر المسبقة
 
echo "=== فحص جاهزية النشر ==="
echo ""
 
# الفحص 1: لا تغييرات غير محفوظة
if [ -z "$(git status --porcelain)" ]; then
  echo "PASS: مجلد العمل نظيف"
else
  echo "FAIL: توجد تغييرات غير محفوظة"
  git status --short
fi
 
# الفحص 2: الاختبارات تنجح
if npm test --silent 2>/dev/null; then
  echo "PASS: الاختبارات ناجحة"
else
  echo "FAIL: الاختبارات فاشلة"
fi
 
# الفحص 3: البناء ينجح
if npm run build --silent 2>/dev/null; then
  echo "PASS: البناء ناجح"
else
  echo "FAIL: البناء معطل"
fi
 
echo ""
echo "=== اكتمل الفحص ==="

لاحظ حقل allowed-tools في البيانات الوصفية. هذه المهارة تحتاج Bash لتنفيذ السكربت، لكن مهارة للقراءة فقط يمكن أن تقتصر على Read, Grep, Glob.

الخطوة 7: إضافة ملفات مرجعية (اختياري)

للمهارات التي تحتاج توثيقاً مكثفاً، أضف ملفات مرجعية بدلاً من حشو كل شيء في SKILL.md.

code-review/
├── SKILL.md
├── references/
│   ├── owasp-top-10-checklist.md
│   └── style-guide-summary.md
└── assets/
    └── review-template.md

الوكيل يحمّل الملفات المرجعية فقط عند الحاجة — موفراً الرموز في المراجعات الروتينية.

الخطوة 8: اختبر مهاراتك

اختبار التفعيل

افتح أداة البرمجة بالذكاء الاصطناعي واختبر هذه الطلبات:

يجب أن تُفعّل code-review:

• "Review this PR"
• "Check my latest changes for issues"
• "Audit the auth module"

يجب أن تُفعّل deploy-checker:

• "Are we ready to deploy?"
• "Run pre-deploy checks"
• "Can we ship this to production?"

يجب ألا تُفعّل أياً منهما:

• "Write a new API endpoint"
• "Explain how this function works"

الخطوة 9: تثبيت مهارات شخصية (عامة)

المهارات في .agents/skills/ خاصة بالمشروع. للمهارات التي تريدها في جميع المشاريع:

mkdir -p ~/.agents/skills/my-global-skill

المهارات العامة مفيدة لسير العمل الشخصي. المهارات المشروعية لإجراءات الفريق المشتركة.

الأولوية: مهارات المشروع تتجاوز المهارات العامة بنفس الاسم.

الخطوة 10: التحقق عبر المنصات

مهاراتك يجب أن تعمل بدون تعديل عبر جميع الأدوات المتوافقة:

استكشاف الأخطاء وإصلاحها

المهارة لا تُفعّل أبداً

السبب: الوصف لا يتطابق مع طلبات المستخدم بدقة كافية.

الحل: أضف المزيد من عبارات التفعيل.

المهارة تُفعّل لكن التعليمات تُتجاهل

السبب: التعليمات غامضة أو تستخدم صيغة المبني للمجهول.

الحل: أعد الكتابة بصيغة الأمر مع إجراءات محددة.

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

السبب: نص SKILL.md يتجاوز 5,000 رمز.

الحل: انقل المواد المرجعية إلى ملفات منفصلة في references/.

اعتبارات الأمان

المهارات تعليمات ذات امتيازات. مهارة خبيثة يمكنها توجيه وكيل لتنفيذ أوامر تعسفية أو تسريب بيانات.

قبل تثبيت مهارات طرف ثالث:

1. اقرأ كل سطر من SKILL.md وجميع السكربتات المُرفقة
2. افحص وجود اتصالات شبكية غير متوقعة
3. ابحث عن وصول للملفات خارج مجلد المشروع
4. تحقق من مصداقية المصدر
5. استخدم allowed-tools لتقييد القدرات

ملخص أفضل الممارسات

الخطوات التالية

• اقرأ نظرة عامة على مواصفات مهارات الوكلاء لتفاصيل الهندسة المعمارية
• استكشف مهارات الوكلاء لفرق الأعمال لتوسيع المهارات عبر مؤسستك
• فكر في تدقيق مهارات احترافي لتحسين مكتبة مهارات فريقك

الخلاصة

كتابة أول SKILL.md تستغرق أقل من عشر دقائق. العائد فوري — وكيل البرمجة بالذكاء الاصطناعي يُفعّل التعليمات الصحيحة للمهمة الصحيحة ويستخدم رموزاً أقل ويعمل بنفس الطريقة عبر كل أداة في مجموعتك التقنية.

ابدأ بمهارة واحدة لسير عملك الأكثر تكراراً. اختبرها وحسّن الوصف والتزم بها في مستودعك. ثم ابنِ من هناك.

تحتاج مساعدة في بناء مكتبة مهارات مخصصة لفريق الهندسة؟ نقطة تقدم استشارات مهارات الوكلاء — من تطوير المهارات الفردية إلى حوكمة المهارات المؤسسية وتدقيقات الأمان.