كيف تبني مهارة خاصة بك
في كلود كود؟

كل مطوّر لديه روتين يكرره — طريقة معينة يكتب فيها رسائل الحفظ (commit)، قائمة مراجعة قبل فتح طلب الدمج (Pull Request)، أو هيكل ثابت يتبعه عند مراجعة الكود. يشرحه للوكيل الذكي في كل جلسة، ثم يراقبه يفسّره بطريقة مختلفة في كل مرة.

مهارات الوكيل (Agent Skills) تحل هذه المشكلة تماماً. المهارة هي ملف نصي يُحمَّل تلقائياً في كلود كود (Claude Code) حين تحتاجه — تكتب سير عملك مرة واحدة والوكيل يتبعه دائماً. والأروع أن نفس الملف يعمل في كلود كود (Claude Code)، كوبايلوت (GitHub Copilot)، كيرسر (Cursor)، وجيميناي (Gemini CLI).

ما هي مهارة الوكيل بالضبط؟

المهارة هي مجلد يحتوي ملفاً واحداً اسمه SKILL.md. هذا الملف مكوّن من قسمين: ترويسة الإعداد (YAML frontmatter) في الأعلى، ومحتوى التعليمات بداخله.

my-skill/
└── SKILL.md

ترويسة الإعداد تُخبر الوكيل باسم المهارة ومتى يستخدمها. والمحتوى يخبره ماذا يفعل حين يُحمّلها:

---
name: my-skill
description: ما تفعله هذه المهارة ومتى تُستخدم.
---

# عنوان المهارة

تعليمات الوكيل هنا.

المهارة ليست؟

المهارات ليست إضافات أو حزم برمجية. لا يوجد لها بيئة تشغيل خاصة — لكنها تأمر الوكيل باستخدام أدواته الموجودة لتنفيذ المهام. هي ملفات نصية يقرأها الوكيل كما يقرأ الشيف وصفة الطبخ.

كيف تختار ماذا تبني؟

أفضل المهارات تشترك في ثلاث خصائص:

• 🔁 ترمّز سير عمل متكرراً — إذا كنت تفعله بطريقة مختلفة في كل مرة، المهارة لن تساعد. أما إذا كنت تتبع نفس الخطوات في كل جلسة — هذا مرشح مثالي.
• 🎯 لها محفّز واضح — يجب أن تُكمل الجملة: "أحتاج هذه المهارة حين أريد…" في عبارة واحدة.
• 📋 تنتج مخرجاً بصيغة ثابتة — رسالة حفظ، مراجعة كود، سجل تغييرات — أسهل في البناء والاختبار.

كيف تكتب الوصف بشكل صحيح.

حقل الوصف هو شرط التفعيل. معظم المهارات تفشل ليس لأن التعليمات خاطئة، بل لأن الوصف لا يطابق الطريقة التي يطلب بها المطورون المساعدة فعلياً.

❌ وصف ضعيف

description: Generates commit messages.

هذا سيؤدي إلى عدم تفعيل المهارة في أحيان كثيرة. "اكتب رسالة حفظ" ستُحمّلها. أما "لخّص تغييراتي لقيت (git)" فعلى الأرجح لن تفعل.

✅ وصف قوي

description: Generates structured commit messages following the Conventional
  Commits standard. Use when you want to commit your changes and need a
  well-formatted message. Triggers on "write a commit message", "commit my
  changes", "summarize my staged diff", or any request to describe code
  changes for version control.

النمط هو: ماذا تفعل المهارة + متى تُستخدم + عبارات تفعيل محددة.

كيف تكتب التعليمات بشكل صحيح.

محتوى الملف يتبع مبدأين أساسيين:

• ⚡ أنتج أولاً، اسأل ثانياً: الوكيل يجب أن ينتج مخرجاً فوراً بدل أسئلة توضيحية. إذا احتاج افتراضات — يضعها ويُلاحظها بعد المخرج.
• 📐 حدّد صيغة المخرج بدقة: لا تقل "اكتب رسالة حفظ جيدة". قل بالضبط ما هو الهيكل، وما الحقول المطلوبة، وما حدود الأحرف.

❌ تعليمات ضعيفة

# كاتب رسائل الحفظ

انظر إلى التعديلات المُعدّة واكتب رسالة حفظ تصف ما تغيّر.

هذا سينتج نتائج مختلفة في كل مرة. هذا توجيه عام لا مهارة محددة.

✅ تعليمات قوية

# كاتب رسائل الحفظ

اقرأ التعديلات المُعدّة باستخدام `git diff --staged`.
أنتج رسالة حفظ تتبع معيار الحفظات التقليدية (Conventional Commits).

صيغة المخرج:
النوع(النطاق): وصف قصير أقل من 72 حرفاً

المحتوى (إذا كانت التغييرات غير بسيطة):
- ماذا تغيّر ولماذا، لا كيف
- نقطة واحدة لكل تغيير منطقي

ابنِ المهارة خطوة بخطوة.

# ماك / لينكس
mkdir -p ~/.claude/skills/commit-message-writer

# ويندوز باورشيل (Windows PowerShell)
New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\commit-message-writer"

---
name: commit-message-writer
description: Generates structured commit messages following the Conventional Commits
  standard. Use when you want to commit your changes and need a well-formatted message.
  Triggers on "write a commit message", "commit my changes", "summarize my staged
  diff", "what should my commit say", or any request to describe staged changes
  for version control.
---

# كاتب رسائل الحفظ

أنت تولّد رسائل حفظ منظمة من تعديلات قيت (git) المُعدّة.

## طريقة التفعيل

نفّذ `git diff --staged` لقراءة التعديلات المُعدّة.
إذا لم يكن هناك شيء مُعدّ، أخبر المستخدم واقترح تنفيذ `git add` أولاً.

أنتج المخرج فوراً. لا تسأل أسئلة توضيحية قبل إنتاج رسالة الحفظ.

## صيغة المخرج

النوع(النطاق): وصف قصير

[المحتوى — اختياري، أضفه إذا كانت التغييرات غير بسيطة]

[التذييل — اختياري]

**أنواع الحفظ** — اختر واحداً:
- `feat`     — ميزة جديدة
- `fix`      — إصلاح خطأ
- `docs`     — تغييرات في التوثيق فقط
- `refactor` — تغيير في الكود لا يُصلح خطأ ولا يُضيف ميزة
- `test`     — إضافة أو تحديث اختبارات
- `chore`    — أدوات البناء أو التبعيات

**النطاق** — الوحدة أو الملف أو المنطقة المتأثرة. احذفه إذا كان التغيير شاملاً.

**الوصف القصير** — صيغة أمرية، أقل من 72 حرفاً، بدون نقطة في النهاية.

## قواعد الجودة

- لا تستخدم "تم تحديث" أو "تم تغيير" — كن محدداً
- لا تكتب "تحسينات متنوعة" أو "إصلاحات عامة"
- إذا تغيّر أكثر من 3 ملفات في موضوعات غير مترابطة → نبّه إلى ضرورة التقسيم

## مثال على المخرج

feat(api): إضافة تحديد معدل الطلبات لنقطة /query

- يحدد الطلبات بـ 100 في الدقيقة لكل عنوان IP
- يُرجع 429 مع ترويسة Retry-After عند تجاوز الحد

Closes #47

cat ~/.claude/skills/commit-message-writer/SKILL.md

اكتب رسالة حفظ لتعديلاتي المُعدّة
ماذا يجب أن تقول رسالة الحفظ؟

كيف تحسّن المهارة مع الوقت.

إذا لم تُفعَّل المهارة

إذا كتبت "لخّص تغييراتي لقيت (git)" ولم تُحمَّل المهارة — أضف هذه العبارة إلى قائمة المحفّزات في حقل الوصف. الوصف هو المقود الرئيسي لمعالجة مشاكل التفعيل.

إذا انحرفت صيغة المخرج

إذا بدأ الوكيل ينتج رسائل لا تطابق الصيغة — التعليمات تحتاج تحديداً أكثر. أضف أمثلة مضادة توضح الخطأ والصواب:

## أمثلة على الأخطاء الشائعة

خطأ:  "تم تحديث سير المصادقة"
صواب: "refactor(auth): تبسيط منطق التحقق من الرمز المميز"

خطأ:  "إصلاح أخطاء"
صواب: "fix(api): معالجة الاستجابة الفارغة من الخدمة الخارجية"

إذا كبر حجم الملف

إذا وجدت نفسك تضيف مهام إضافية لنفس المهارة — لا تفعل. ابنِ مهارات منفصلة. كل مهارة تفعل شيئاً واحداً بإتقان. المعيار مصمم للتركيب لا للتضخيم.

في أي أدوات تعمل مهارتك؟

ملف المهارة الذي بنيته مرة واحدة يعمل في أكثر من أداة. فقط مسار التثبيت مختلف:

أفكار لمهارات جديدة تبنيها

• 📝 كاتب وصف طلب الدمج — يقرأ التعديلات ويطبّق هيكلاً ثابتاً للوصف مع قسم الاختبار
• 🔍 قائمة مراجعة الكود — تفعّل عند "راجع هذا الكود"، وتُشغّل معايير الفريق الثابتة
• 📋 مولّد سجل التغييرات — من رسائل الحفظ منذ آخر إصدار إلى ملف تغييرات منظم
• 🏗️ كاتب المتطلبات — يكتب المواصفات بصيغة ثابتة مع إبراز الافتراضات

"المهارة الأولى تأخذ وقتاً. الثانية أقل. بالثالثة ستبدأ ترى كل سير عمل تكرره وتفكر فيه مباشرةً: هذا يجب أن يصبح مهارة."

ما بنيته اليوم ليس مجرد ملف نصي — هو سير عمل مُرمَّز يعمل عبر أدوات متعددة، يوفّر عليك الشرح المتكرر، ويضمن نتائج متسقة في كل جلسة. ابدأ بكاتب رسائل الحفظ، ثم ابنِ مهارات لكل سير عمل تكرره.