بناء حزمة مهارات وكيل متعددة الأدوات لفريقك الهندسي

عندما يكتب مطور واحد ملف SKILL.md واحداً يحصل على تحسين فوري في الإنتاجية. لكن التحول الحقيقي يحدث عندما يتشارك فريق هندسي كامل مكتبة منسقة من مهارات الوكلاء — سير عمل موحد ومراجعات كود متسقة وإجراءات نشر يتبعها كل وكيل ذكاء اصطناعي بشكل متطابق بغض النظر عن الأداة التي يفضلها كل مهندس.

يرشدك هذا الدليل خطوة بخطوة لبناء حزمة مهارات وكلاء بمستوى إنتاجي: من هندسة الدليل واتفاقيات التسمية إلى الإصدارات والحوكمة وسير عمل الاكتشاف على مستوى الفريق.

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

ما الذي ستبنيه

بنهاية هذا الدليل سيكون لدى فريقك:

1. دليل .agents/skills/ مشترك يحتوي أربع مهارات جاهزة للإنتاج
2. اتفاقية تسمية وإصدارات يتبعها الفريق بأكمله
3. سير عمل حوكمة لاقتراح ومراجعة والموافقة على المهارات الجديدة
4. آلية اكتشاف تمكن المهندسين من إيجاد واستخدام المهارات الموجودة
5. ضمانات أمنية للنشر المؤسسي

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

• معرفة بصيغة وبنية SKILL.md (اقرأ نظرة عامة على المواصفة)
• مستودع أحادي أو مستودع مشترك يتعاون فيه فريقك
• أداة برمجة بالذكاء الاصطناعي واحدة على الأقل مثبتة (Claude Code أو Codex أو Copilot أو Cursor أو Gemini CLI)
• نظام تحكم بالإصدارات Git مع قواعد حماية الفروع

الخطوة 1: تصميم هندسة دليل المهارات

تحتاج مكتبة مهارات الفريق إلى بنية أكثر تنظيماً من المكتبة الشخصية. إليك الهندسة التي نوصي بها للمؤسسات التي تضم من 5 إلى 200 مهندس:

your-org-repo/
├── .agents/
│   └── skills/
│       ├── README.md              # فهرس المهارات ودليل الاستخدام
│       ├── GOVERNANCE.md          # عملية الموافقة والملكية
│       ├── code-review/
│       │   ├── SKILL.md
│       │   ├── CHANGELOG.md
│       │   └── references/
│       │       └── style-guide.md
│       ├── deploy/
│       │   ├── SKILL.md
│       │   ├── CHANGELOG.md
│       │   └── scripts/
│       │       └── pre-deploy-check.sh
│       ├── test-runner/
│       │   ├── SKILL.md
│       │   ├── CHANGELOG.md
│       │   └── references/
│       │       └── coverage-thresholds.md
│       └── documentation/
│           ├── SKILL.md
│           ├── CHANGELOG.md
│           └── templates/
│               ├── api-doc.md
│               └── component-doc.md
├── src/
└── package.json

قرارات هندسية رئيسية

مهارة واحدة لكل دليل. كل مهارة مستقلة بذاتها مع ملف SKILL.md وسجل التغييرات والملفات المساعدة الخاصة بها. لا تضع أبداً مهارات متعددة في نفس المجلد.

README.md في الجذر يعمل كفهرس مقروء للمهارات. يفحصه المهندسون لاكتشاف المهارات الموجودة قبل كتابة مهارات جديدة.

GOVERNANCE.md يوثق من يملك مكتبة المهارات وكيفية اقتراح مهارات جديدة وسير عمل الموافقة.

CHANGELOG.md لكل مهارة يتتبع ما تغير ومتى. هذا ضروري عندما تبدأ مهارة في إنتاج سلوك غير متوقع من الوكيل — يمكنك تحديد الإصدار الذي أدخل التغيير.

أدلة references/ و scripts/ الفرعية تحافظ على نص SKILL.md مختصراً. يحمل الوكيل هذه الملفات فقط عندما تشير التعليمات إليها مما يوفر الرموز.

الخطوة 2: بناء مهارة مراجعة الكود

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

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

---
name: code-review
version: 2.1.0
description: >
  Reviews code changes for quality, security, performance, and adherence
  to team coding standards. Use when the user asks to 'review code',
  'check this PR', 'audit this change', 'look at my diff', 'review my
  changes', or 'code quality check'.
allowed-tools: Read, Grep, Glob, Bash
---
 
# Code Review
 
## Context
 
Read the project's linting rules and style guide from
`references/style-guide.md` before starting.
 
## Workflow
 
1. Identify the scope: run `git diff --name-only` to see changed files
2. Read each changed file fully
3. Check against the team style guide
4. Run static analysis: `npm run lint -- --quiet`
5. Check for security issues against OWASP Top 10
6. Verify error handling — no empty catch blocks
7. Look for performance regressions
8. Verify test coverage for new public APIs
9. Output structured feedback
 
## Output Format
 
### Critical (blocks merge)
- Security vulnerabilities
- Data loss risks
- Breaking API changes without migration
 
### Warning (should fix)
- Missing error handling
- Performance concerns
- Incomplete test coverage
 
### Suggestion (optional)
- Readability improvements
- Documentation gaps
- Refactoring opportunities
 
## Rules
 
- Reference file paths and line numbers in all feedback
- Provide a fix suggestion for every issue
- If the code is clean, say so
- Never approve code with known security vulnerabilities

لماذا الإصدار مهم

حقل version: 2.1.0 يستخدم الإصدار الدلالي:

• رئيسي (2.x.x): تغييرات جذرية في سلوك المهارة أو تنسيق المخرجات
• ثانوي (x.1.x): فحوصات أو قدرات جديدة مضافة
• تصحيحي (x.x.0): إصلاحات أخطاء أو تحسينات الوصف

الخطوة 3: بناء مهارة النشر

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

---
name: deploy
version: 1.0.0
description: >
  Validates deployment readiness and guides the deployment process.
  Use when the user says 'deploy', 'ship to production', 'release',
  'pre-deploy check', 'is this ready to deploy', or 'push to staging'.
allowed-tools: Read, Grep, Glob, Bash
---
 
# Deployment
 
## Pre-Deploy Checklist
 
Run the automated check first:
 
\`\`\`bash
bash .agents/skills/deploy/scripts/pre-deploy-check.sh
\`\`\`
 
## Manual Verification
 
1. All CI checks are green
2. Database migrations are backward-compatible
3. Environment variables are set for target environment
4. Feature flags are configured correctly
5. Rollback plan is documented
 
## Deployment Steps
 
### Staging
1. Create a release branch: `git checkout -b release/vX.Y.Z`
2. Run the full test suite: `npm run test:ci`
3. Build and deploy: `npm run deploy:staging`
4. Verify smoke tests pass
 
### Production
1. Ensure staging verification is complete
2. Tag the release: `git tag vX.Y.Z`
3. Deploy: `npm run deploy:production`
4. Monitor error rates for 30 minutes
5. If error rate exceeds 1%, initiate rollback
 
## Rules
 
- Never deploy on Fridays after 3 PM
- Always deploy to staging before production
- Tag every production release with a semantic version

الخطوة 4: بناء مهارة تشغيل الاختبارات

أنشئ .agents/skills/test-runner/SKILL.md:

---
name: test-runner
version: 1.2.0
description: >
  Runs tests, analyzes failures, and helps improve test coverage.
  Use when the user says 'run tests', 'fix failing tests', 'add tests',
  'test coverage', 'write unit tests', or 'why is this test failing'.
allowed-tools: Read, Grep, Glob, Bash
---
 
# Test Runner
 
## Workflow
 
### Running Tests
1. Identify scope: unit, integration, or e2e
2. Run the appropriate command:
   - Unit: `npm run test:unit`
   - Integration: `npm run test:integration`
   - E2E: `npm run test:e2e`
   - All: `npm test`
 
### Analyzing Failures
1. Read the full error output
2. Identify whether the failure is in the test or the code
3. Check for flaky test patterns
4. Suggest a specific fix with code
 
### Improving Coverage
1. Read thresholds from `references/coverage-thresholds.md`
2. Run `npm run test:coverage`
3. Identify uncovered lines in changed files
4. Write tests for critical uncovered paths
 
## Rules
 
- Never mark a failing test as skipped without documenting why
- If a test is flaky, fix the flakiness
- Write tests that would catch the bug if it regressed

الخطوة 5: بناء مهارة التوثيق

أنشئ .agents/skills/documentation/SKILL.md:

---
name: documentation
version: 1.0.0
description: >
  Generates and updates project documentation. Use when the user says
  'document this', 'write docs', 'update the README', 'API documentation',
  'add JSDoc', or 'generate changelog'.
allowed-tools: Read, Grep, Glob, Write
---
 
# Documentation
 
## Workflow
 
1. Identify what needs documentation
2. Read the existing code thoroughly
3. Use the appropriate template from `templates/`
4. Write documentation that answers: What, Why, How, When
 
## Standards
 
### API Documentation
- Method, path, and description
- Request parameters with types
- Response schema with example
- Error codes and meanings
 
### Code Comments
- JSDoc for all public functions
- Explain WHY, not WHAT
- Document non-obvious side effects
- Mark TODO items with ticket references
 
## Rules
 
- Match the existing documentation style
- Never document implementation details that change frequently
- Keep examples runnable

الخطوة 6: وضع اتفاقيات التسمية

التسمية المتسقة تمنع التكرار وتسهل الاكتشاف. اعتمد هذه الاتفاقيات على مستوى الفريق:

أسماء أدلة المهارات

قواعد التسمية

1. استخدم kebab-case لأسماء الأدلة
2. حافظ على الأسماء أقل من 30 حرفاً
3. استخدم الأفعال أو أزواج فعل-اسم: code-review وليس reviewer
4. تجنب الأسماء العامة: helper، utils، misc
5. طابق حقل name في SKILL.md مع اسم الدليل

سجل المهارات

حافظ على جدول في .agents/skills/README.md:

# فهرس مهارات الوكلاء
 
| المهارة | الإصدار | المالك | الوصف |
|---------|---------|--------|-------|
| code-review | 2.1.0 | @backend-team | مراجعة الكود مع فحوصات الأمان والأسلوب |
| deploy | 1.0.0 | @devops-team | جاهزية النشر ودليل العملية |
| test-runner | 1.2.0 | @qa-team | تنفيذ الاختبارات والتحليل والتغطية |
| documentation | 1.0.0 | @docs-team | إنشاء وتحديث التوثيق |

الخطوة 7: إعداد سير عمل الحوكمة

للفرق الأكبر من خمسة مهندسين، تؤدي تغييرات المهارات غير المحوكمة إلى الفوضى. إليك إطار حوكمة خفيف:

عملية اقتراح المهارات

1. افتح قضية بعنوان Skill Proposal: {skill-name} تصف ما تفعله المهارة ولماذا هي مطلوبة
2. تحقق من التكرارات في فهرس المهارات README
3. صمم SKILL.md في فرع ميزة
4. اطلب مراجعة من مالك مكتبة المهارات
5. اختبر التفعيل — أثبت أن المهارة تتفعل على المطالبات المتوقعة ولا تتفعل على غير المتعلقة
6. ادمج بعد الموافقة من مراجعَين على الأقل

إدارة التغييرات

عامل تغييرات المهارات كتغييرات الكود:

• زيادات الإصدار الرئيسية تتطلب نقاش الفريق
• زيادات الإصدار الثانوية تتطلب مراجعاً واحداً من الفريق المالك
• زيادات الإصدار التصحيحية يمكن دمجها ذاتياً بعد نجاح CI

تكامل CODEOWNERS

أضف ملكية المهارات إلى ملف CODEOWNERS في مستودعك:

# ملكية مهارات الوكلاء
.agents/skills/code-review/    @backend-team
.agents/skills/deploy/         @devops-team
.agents/skills/test-runner/    @qa-team
.agents/skills/documentation/  @docs-team
.agents/skills/GOVERNANCE.md   @engineering-leads
.agents/skills/README.md       @engineering-leads

متطلبات المراجعة الأمنية

المهارات التي تحتوي Bash في allowed-tools تتطلب مراجعة أمنية لأنها تستطيع تنفيذ أوامر عشوائية. أنشئ فحص CI:

name: Skill Security Check
on:
  pull_request:
    paths: ['.agents/skills/**']
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check for dangerous patterns
        run: |
          for skill in .agents/skills/*/SKILL.md; do
            if grep -q "Bash" "$skill"; then
              echo "REVIEW REQUIRED: $skill has Bash access"
              dir=$(dirname "$skill")
              if find "$dir" -name "*.sh" -exec grep -l "rm -rf\|curl\|wget\|eval" {} \;; then
                echo "WARNING: Potentially dangerous commands found"
              fi
            fi
          done

الخطوة 8: تمكين اكتشاف المهارات

لن يستخدم المهندسون مهارات لا يعرفون بوجودها. أنشئ ثلاث قنوات اكتشاف:

1. توثيق التأهيل

أضف قسماً إلى دليل تأهيل المهندسين:

## مهارات وكلاء البرمجة بالذكاء الاصطناعي
 
نحتفظ بمكتبة مشتركة من مهارات الوكلاء في `.agents/skills/`.
تعمل مع Claude Code و Codex و Copilot و Cursor وأدوات أخرى.
 
قبل أول طلب سحب، استكشف دليل المهارات وجرب:
- "Review my code" ← تفعل مهارة مراجعة الكود
- "Is this ready to deploy?" ← تفعل مهارة النشر
- "Run tests and check coverage" ← تفعل مهارة تشغيل الاختبارات

2. إعلانات المهارات الدورية

عند دمج مهارات جديدة أعلن عنها في قناة الهندسة مع مثال موجز لكيفية تفعيلها.

3. مهارة البحث عن المهارات

أنشئ مهارة وصفية تساعد المهندسين على اكتشاف المهارات الأخرى:

---
name: skill-search
version: 1.0.0
description: >
  Lists and describes available agent skills. Use when the user asks
  'what skills are available', 'list skills', 'find a skill for',
  or 'show available workflows'.
allowed-tools: Read, Grep, Glob
---
 
# Skill Discovery
 
1. Read `.agents/skills/README.md` for the complete catalog
2. Search all SKILL.md files for matching keywords
3. Present matching skills with name, version, and description
4. Suggest the trigger phrase to activate each skill

الخطوة 9: التعامل مع مشاركة المهارات عبر المستودعات المتعددة

إذا كانت مؤسستك تستخدم مستودعات متعددة تحتاج استراتيجية لمشاركة المهارات عبرها.

الخيار أ: Git Submodule

git submodule add git@github.com:your-org/agent-skills.git .agents/skills

المميزات: مقفل على إصدار محدد، سير عمل مألوف. العيوب: احتكاك تحديث الوحدة الفرعية، تعارضات الدمج.

الخيار ب: حزمة مشتركة

انشر المهارات كحزمة npm وثبتها في كل مستودع:

npm install --save-dev @your-org/agent-skills

المميزات: إصدار دلالي، تحديثات تلقائية. العيوب: تتطلب بنية تحتية للحزم.

الخيار ج: دليل مهارات المستودع الأحادي

احتفظ بجميع المهارات في مستودع أحادي يساهم فيه جميع الفرق:

org-mono/
├── .agents/skills/      # مشتركة عبر جميع الحزم
├── packages/
│   ├── api/
│   ├── web/
│   └── mobile/

المميزات: مصدر حقيقة واحد، اكتشاف سهل. العيوب: يجب أن تستخدم جميع الفرق المستودع الأحادي.

التوصية

لمعظم المؤسسات الخيار ج (المستودع الأحادي) هو الأبسط. إذا كنت تستخدم مستودعات متعددة فإن الخيار أ (submodule) يوفر أفضل تحكم في إصدار المهارات.

الخطوة 10: القياس والتكرار

تتبع هذه المقاييس لتقييم تأثير مكتبة المهارات:

مقاييس التبني

• تكرار تفعيل المهارات: كم مرة يتم تفعيل كل مهارة أسبوعياً؟
• التغطية: ما نسبة المهندسين الذين استخدموا مهارة واحدة على الأقل؟
• اقتراحات المهارات الجديدة: كم مهارة جديدة تُقترح في كل سبرنت؟

مقاييس الجودة

• معدل التفعيل الخاطئ: كم مرة تتفعل مهارة على مطالبات غير متعلقة؟
• الالتزام بالتعليمات: هل يتبع الوكيل تعليمات المهارة باستمرار؟
• معدل التجاوز: كم مرة يتجاوز المهندسون أو يعارضون مخرجات المهارة؟

طريقة الجمع

معظم أدوات البرمجة بالذكاء الاصطناعي تسجل تفعيلات المهارات. راجع هذه السجلات شهرياً و:

1. أوقف المهارات التي لم يتم تفعيلها خلال 60 يوماً
2. حسّن أوصاف المهارات ذات معدل التفعيل الخاطئ العالي
3. قسّم المهارات الواسعة جداً
4. ادمج المهارات التي يستخدمها المهندسون متتالياً باستمرار

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

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

• اقرأ نظرة عامة على مواصفة مهارات الوكلاء للمعيار الأساسي
• اتبع دليل كتابة SKILL.md لإنشاء المهارات الفردية
• استكشف مهارات الوكلاء للفرق التجارية لفهم التأثير المؤسسي
• راجع عروض خدماتنا لهندسة مكتبات المهارات الاحترافية
• تحقق من خطط التسعير لحزم حوكمة المهارات المؤسسية

الخلاصة

مكتبة مهارات الوكلاء المشتركة ليست مجرد مجموعة من ملفات markdown — إنها المعرفة المؤسسية لفريقك الهندسي مشفرة بتنسيق تفهمه كل أداة برمجة بالذكاء الاصطناعي. عندما ينضم مهندس جديد يرث أفضل ممارسات الفريق فوراً. وعندما تتغير عملية ما تحدث ملف SKILL.md واحد ويتبع وكيل الذكاء الاصطناعي لكل مهندس الإجراء الجديد.

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

الاستثمار صغير — بضع ساعات لإعداد المكتبة الأولية — لكن العوائد المتراكمة كبيرة. كل مهارة تضيفها تجعل التالية أسهل في الكتابة والاكتشاف والحوكمة.

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