كيف تكتب مهارة Claude Code الخاصة بك

لقد ثبّتت بعض مهارات Claude Code ورأيت كيف تحوّل سير عملك. الآن تتساءل: هل يمكنني كتابة مهارتي الخاصة؟ بالتأكيد — والأمر أبسط مما تظن.

يغطي هذا الدليل كل شيء: بنية ملف المهارة، وأين تحفظها، واتفاقيات التسمية، وكتابة قواعد فعّالة، وأنماط متقدمة لمزيد من التحكم.

بنية ملف المهارة

المهارة هي ملف Markdown بجزأين: بيانات وصفية في frontmatter وجسم المحتوى.

---
name: my-skill-name
description: Use when doing X with Y technology
triggers:
  - keywords: ["keyword1", "keyword2"]
  - fileTypes: [".ext"]
version: "1.0"
author: "Your Name"
---

## Rules

- القاعدة الأولى
- القاعدة الثانية

## Patterns

أمثلة أكواد أو توجيهات منظمة هنا.

الـ frontmatter هو YAML بين علامات ---. الجسم هو Markdown عادي — عناوين وقوائم نقطية وكتل أكواد، أي شيء يمكن لـ Claude قراءته.

حقول الـ Frontmatter

| الحقل | مطلوب | الغرض | |-------|--------|-------| | name | نعم | معرف فريد للمهارة | | description | نعم | يخبر Claude متى يطبق هذه المهارة | | triggers | موصى به | كلمات مفتاحية وأنواع ملفات تنشّط المهارة | | version | اختياري | تتبع التغييرات عبر الزمن | | author | اختياري | نسب العمل |

حقل description أهم مما يبدو. يستخدمه Claude لتحديد ما إذا كانت هذه المهارة ذات صلة بمهمة معينة. اكتبه كجملة واضحة بصيغة "Use when...".

أين تحفظ المهارات

جميع المهارات تعيش في ~/.claude/skills/. يفحص Claude Code هذا الدليل عند بدء التشغيل ويحمّل جميع ملفات .md التي يجدها.

~/.claude/skills/
├── react-expert.md
├── typescript-pro.md
├── devops-engineer.md
└── my-custom-skill.md   # مهارتك الجديدة

يمكنك تنظيم المهارات في أدلة فرعية — يبحث Claude Code بشكل متكرر:

~/.claude/skills/
├── frontend/
│   ├── react-expert.md
│   └── vue-expert.md
└── backend/
    ├── fastapi-expert.md
    └── go-developer.md

بعد إضافة مهارة، أعد تشغيل Claude Code وستكون جاهزة. لا حاجة لتهيئة.

اتفاقيات التسمية

أسماء المهارات الجيدة تتبع نمطاً بسيطاً: domain-role.md أو technology-specialty.md.

أسماء جيدة:

• react-expert.md
• sql-optimizer.md
• code-reviewer.md
• api-designer.md

تجنب:

• my-stuff.md (غامض جداً)
• reactNextjsTypescriptFrontendMaster.md (واسع جداً، تنسيق خاطئ)
• skill1.md (بلا معنى)

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

كتابة قواعد فعّالة

جسم مهارتك هو المكان الذي تعيش فيه القيمة الحقيقية. إليك كيفية كتابة قواعد تغير فعلاً سلوك Claude.

كن محدداً، لا عاماً

القواعد الغامضة تنتج نتائج غامضة.

ضعيف: "اكتب كود TypeScript جيد."

قوي:

## القواعد

- فعّل دائماً الوضع الصارم (`"strict": true` في tsconfig)
- استخدم `unknown` بدلاً من `any` — لا تستخدم `any` إلا عند التعامل مع APIs خارجية غير مكتوبة
- فضّل `type` على `interface` لأنواع الاتحاد والأنواع المعيّنة
- استخدم branded types للمعرفات: `type UserId = string & { readonly __brand: 'UserId' }`
- أرجع tuples من نوع `Result<T, E>` للعمليات المعرّضة للأخطاء بدلاً من الإلقاء

أعطِ سياقاً، لا مجرد أوامر

اشرح لماذا خلف القواعد. Claude يستدل بشكل أفضل مع السياق.

## إدارة الحالة

استخدم Zustand للحالة العامة، وReact Query لحالة الخادم. احتفظ بهما منفصلين.

**المنطق:** يتعامل React Query مع التخزين المؤقت وإعادة الجلب والمزامنة تلقائياً —
لا تكرر هذا مع Zustand. Zustand مخصص لحالة UI (المودالات، الشريط الجانبي، المظهر)
التي لا تأتي من الخادم.

**النمط:**
- بيانات الخادم → React Query (`useQuery`, `useMutation`)
- حالة UI → مخزن Zustand
- حالة المكوّن → `useState` (لا ترفعها إلا إذا لزم الأمر)

أدرج الأنماط المضادة

أخبر Claude بما يجب ألا يفعله. هذا غالباً أكثر فائدة من قواعد ما يجب فعله.

## الأنماط المضادة — لا تفعل هذا أبداً

- لا تستخدم `useEffect` لمزامنة حالة مشتقة من حالة أخرى — استخدم `useMemo`
- لا تستدعِ `setState` في حلقة — اجمع التحديثات أو استخدم reducers
- لا تضع منطقاً غير متزامن مباشرة في معالجات الأحداث — استخرجه إلى hooks مخصصة
- لا تتجاهل تحذيرات ESLint — أصلحها أو عطّلها صراحةً مع تعليق يشرح السبب

اختبار مهارتك

قبل الاعتماد على مهارة للعمل الحقيقي، اختبرها:

1. ابدأ جلسة Claude Code جديدة بعد حفظ ملف المهارة
2. اطلب مهمة في نطاق المهارة — مثلاً، "ابنِ مكوّن مصادقة مستخدم"
3. تحقق من أن Claude يتبع قواعدك — ابحث عن الأنماط التي حددتها
4. كرر — إذا فاتت Claude نقطة ما، اجعل القاعدة أكثر تحديداً أو أضف مثالاً

اختبار مفيد: اطلب من Claude "صف القواعد التي تتبعها لهذه المهمة" — سيلخص المهارات التي تم تحميلها والتعليمات التي يطبقها.

مثال مهارة كامل 1: مصمم API

---
name: api-designer
description: Use when designing or reviewing REST APIs, defining endpoints, writing OpenAPI specs
triggers:
  - keywords: ["api", "endpoint", "rest", "openapi", "swagger"]
  - fileTypes: [".yaml", ".json"]
version: "1.0"
---

## قواعد تصميم REST API

- استخدم الأسماء للموارد، لا الأفعال: `/users` لا `/getUsers`
- استخدم أسماء الموارد بالجمع: `/orders` لا `/order`
- اجعل الموارد المتداخلة بعمق لا يتجاوز مستويين: `/users/{id}/orders` مناسب، أعمق من ذلك لا
- استخدم أساليب HTTP بشكل صحيح: GET (قراءة)، POST (إنشاء)، PUT (استبدال)، PATCH (تحديث)، DELETE (حذف)
- أرجع رموز الحالة المناسبة: 200، 201، 204، 400، 401، 403، 404، 422، 500

مثال مهارة كامل 2: مراجع الكود

---
name: code-reviewer
description: Use when reviewing code, providing feedback on pull requests, or auditing existing code
triggers:
  - keywords: ["review", "pr", "pull request", "audit", "feedback"]
version: "1.0"
---

## قائمة فحص المراجعة

تحقق دائماً من هذه بالترتيب:

### 1. الصحة
- هل الكود يفعل ما يدّعيه؟
- هل تمت معالجة الحالات الحدية (null، فارغ، overflow، وصول متزامن)؟
- هل يتم التقاط الأخطاء والتعامل معها بشكل مناسب؟

### 2. الأمان
- هل يتم التحقق من صحة مدخلات المستخدم وتطهيرها؟
- هل هناك مخاطر SQL injection أو XSS أو path traversal؟
- هل هناك أسرار مُضمَّنة في الكود؟

### 3. الأداء
- هل هناك مشاكل N+1 queries؟
- هل العمليات الثقيلة مخزَّنة مؤقتاً أو محدودة المعدل؟
- هل مجموعات البيانات الكبيرة مقسّمة إلى صفحات؟

## نبرة التغذية الراجعة

- ابدأ بما هو جيد قبل سرد المشاكل
- كن محدداً: "هذه الحلقة تعمل بـ O(n²) لأن..." لا "هذا بطيء"
- وفّر الحل، لا المشكلة فقط
- صنّف التغذية الراجعة: [BLOCKER]، [SUGGESTION]، [NITPICK]

الأنماط المتقدمة

الأقسام الشرطية

يمكنك هيكلة مهارتك بإرشادات شرطية باستخدام عناوين واضحة:

## عند العمل مع Next.js App Router

- استخدم Server Components بشكل افتراضي
- أضف `"use client"` فقط عندما تحتاج التفاعلية أو browser APIs
- ضع المكوّنات الخاصة بالصفحة في دليل المسار

## عند العمل مع Next.js Pages Router

- استخدم `getServerSideProps` فقط عندما تحتاج بيانات وقت الطلب
- فضّل `getStaticProps` مع `revalidate` لمعظم الصفحات
- استخدم API routes لمنطق الـ backend

سيطبق Claude القسم الذي يتناسب مع السياق الفعلي لمهمتك.

تضمين قوالب الكود

ضع الكود النمطي مباشرة في مهارتك حتى يستخدمه Claude كنقطة بداية:

## قالب المكوّن

ابدأ دائماً مكوّنات React الجديدة من هذا القالب:

```tsx
import type { FC } from 'react'

interface Props {
  // عرّف الخصائص هنا
}

const ComponentName: FC<Props> = ({ }) => {
  return (
    <div>
      {/* المحتوى */}
    </div>
  )
}

export default ComponentName

## الأخطاء الشائعة التي يجب تجنبها

**واسع جداً:** مهارة تغطي 10 نطاقات مختلفة ستخفف فعاليتها. حافظ على تركيز كل مهارة.

**بلا أمثلة:** القواعد بدون أمثلة أكواد تترك مجالاً للغموض. أظهر بالضبط ما تقصده.

**أنماط قديمة:** إذا أشارت مهارتك إلى API تغيّر، فقد يستمر Claude في اتباع المهارة. راجع وحدّث المهارات بشكل دوري.

**قواعد متضاربة:** إذا أعطت مهارتان محمّلتان نصائح متناقضة، سيحاول Claude التوفيق بينهما — غالباً بشكل غير متوقع. صمّم المهارات لتكون قابلة للتركيب.

## مهارتك الأولى في 10 دقائق

1. افتح `~/.claude/skills/my-first-skill.md`
2. أضف frontmatter باسم ووصف واضحَين
3. اكتب 5-10 قواعد محددة تهمك
4. أضف مثال كود كامل واحد
5. احفظ، أعد تشغيل Claude Code
6. اختبر بمهمة حقيقية

ابدأ صغيراً. مهارة مركّزة من 20 سطراً تتفوق على مهارة متشعبة من 200 سطر. بمجرد أن تعمل بشكل جيد، وسّعها.

---

*هل تريد 139 مهارات مجرّبة بدلاً من كتابتها من الصفر؟ [احصل على SuperSkills بـ $50](/pricing) — كل مهارة مصنوعة باحتراف وجاهزة للاستخدام.*