أنشئ مكونات إضافية لـ Copilot Cowork

ينطبق على: Microsoft Copilot

يدعم Microsoft Copilot Cowork قابلية التوسّع باستخدام حزم تطبيقات M365، وهي آلية التوزيع نفسها التي تستخدمها تطبيقات Teams ووكلاء Copilot والوظائف الإضافية لـ Office. يمكنك توسيع إمكانات Cowork من خلال:

المهارات: مهام سير العمل المستندة إلى الأوامر النصية التي تُكسب Cowork خبرات جديدة في مجالات محددة، مثل التحليل المالي أو البحث القانوني أو مهام سير عمل الموارد البشرية.
الموصلات: الخوادم البعيدة التي تُتيح لـ Cowork الوصول إلى مصادر البيانات الخارجية وواجهات برمجة التطبيقات.

يُحزَّم كلاهما معًا في حزمة تطبيق Microsoft 365 قياسية ويتم توزيعهما من خلال Microsoft 365 App Store.

مهم

لا يتم حاليا دعم حواجز معلومات Microsoft Purview (IB) لإدارة المكونات الإضافية أو المهارات ومشاركتها. في المستأجرين حيث تم تمكين IB، يتم حظر عمليات تحميل ملف المعرفة المضمن على مستوى المستأجر. وهذا يمنع تحميل المكونات الإضافية والمهارات المتأثرة أو نشرها.

لا تنشئ Microsoft ولا تحتفظ بأي فهرس دائم أو رسم بياني معرفي (بما في ذلك Microsoft Graph) أو قاعدة بيانات تتضمن محتوى مورّدي البرامج المستقلين (ISV)، سواء تم ذلك من خلال الزحف أو الكشط أو الحصاد أو التصدير المجمّع أو الاستيعاب أو أي طريقة أخرى (عبر API أو خادم MCP أو غير ذلك). قد تعالج Microsoft محتوى ISV مؤقتًا حسب الضرورة للاستجابة لاستعلام المستخدم في الوقت الفعلي، لكنها لا تحتفظ بمحتوى ISV بعد مدة جلسة العمل هذه. بناءً على طلبٍ كتابي من مورّد البرامج المستقل (ISV)، تحذف Microsoft أي محتوى خاص بمورّد البرامج المستقل (ISV) بحوزتها أو الخاضع لسيطرتها خلال 10 أيام عمل، وتُقدّم إقرارًا كتابيًا بهذا الحذف. تعرّف على المزيد في حماية بيانات المؤسسات في Microsoft Copilot وMicrosoft Copilot Chat.

ما ستقوم بإنشاءه

المكوّن الإضافي Cowork هو .zip حزمة تحتوي على:

my-extension.zip
├── manifest.json          # M365 Unified App Manifest (v1.28)
├── color.png              # 192×192 full-color app icon
├── outline.png            # 32×32 outline icon
└── skills/                # Agent Skills (SKILL.md files)
    ├── skill-one/
    │   ├── SKILL.md
    │   └── references/    # Optional deep-dive docs
    └── skill-two/
        └── SKILL.md

تستخدم المهارات المعيار المفتوح لمهارات الوكيل، وهو التنسيق نفسه الذي تدعمه Claude Code وتعليمة Visual Studio برمجية Copilot وGemini CLI وCursor وJetBrains Junie وأكثر من 30 أداة ذكاء اصطناعي أخرى.

اختر نقطة البداية

أنشئ المكوّن الإضافي الخاص بك باستخدام wiqd CLI. تُنشئ واجهة سطر الأوامر (CLI) هيكل الحزمة وتُبقي manifest.json ومجلدات مهاراتك متزامنة. كما تُشغِّل قواعد التحقق الخاصة بالمنصة قبل الرفع، ثم تُجهِّز النتيجة وتشاركها. واجهة سطر الأوامر (CLI) في مرحلة المعاينة، لذا قد تتغير أوامرها والمخرجات الناتجة عنها قبل الإتاحة العامة. كل ما ينشئه هو حزمة تطبيق Microsoft 365 عادية، بحيث لا يزال بإمكانك فتح الملفات وتحريرها وتتبع إصداراتها مباشرة.

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

نقطة البداية	قم بما يلي	الوقت حتى أول حزمة
أبدأ الآن من الصفر	أنشئ مكونًا إضافيًا باستخدام wiqd	حوالي 10 دقائق
لدي مكون إضافي موجود ل Claude Code	حوّله	حوالي 5 دقائق
لا يمكنني تثبيت أدوات التطوير، أو أكتب نصوصي البرمجية الخاصة لعملية الحزم	إنشاء حزمة يدويًا	حوالي 30 دقيقة

أنشئ مكونًا إضافيًا باستخدام wiqd

يقوم wiqd CLI بتشغيل نفس دورة الحياة التي تقوم بها يدويا - الإنشاء وإضافة القدرات والتحقق من الصحة والتوفير والحزم والمشاركة. تفي الحزمة التي تنتجها بالفعل بقواعد التحقق من الصحة الواردة في هذه المقالة.

قم بتثبيت واجهة سطر الأوامر لـ wiqd باتباع دليل تثبيت wiqd، الذي يغطي أنظمة Windows وmacOS وLinux. ثم سجل الدخول إلى مستأجر Microsoft 365 الذي تطوّر عليه، لأن عمليتَي التوفير والمشاركة تمسان المستأجر:

wiqd auth login --interactive

يسجل المثبت أيضًا المكون الإضافي لـ GitHub Copilot CLI، حتى تتمكن من قيادة نفس دورة الحياة عبر المحادثة. على سبيل المثال، يمكنك القول، قم بإنشاء مكون إضافي مستقل يسمى Triage Helper أو Validate my plugin. يقوم مسار المحادثة بتشغيل الأوامر نفسها الموجودة في هذا القسم. استخدم الأوامر مباشرة عندما تكتب برنامجًا نصيًا لخط معالجة أو عندما تريد التنفيذ التلقائي غير التفاعلي والقابل لإعادة الإنتاج.

الخطوة 2: سقالة المكون الإضافي وإضافة القدرات

قم بإنشاء حاوية المكون الإضافي، ثم أضف أي إمكانات تحتاجها، بأي تركيبة:

wiqd plugin create --name my-plugin
wiqd plugin add skill --name "Contract Analysis"
wiqd plugin add connector --name "Contoso Legal" --description "Case law and statutes over MCP" --url https://api.contoso.com/legal/mcp

add skill السقالات appPackage/skills/contract-analysis/SKILL.md وتسجيلها في agentSkills[]. add connector يكتب agentConnectors[] الإدخال. يفرض كلا الأمرين قواعد التسمية الخاصة بالنظام الأساسي والحدود القصوى للحجم قبل الكتابة، لذلك لا يصل عدم تطابق اسم المجلد أو اسم id المتجاوز للطول المسموح به إلى البيان.

اكتب منطق مهارتك في .SKILL.md حقول الجزء الأمامي ونموذج التحميل التدريجي وحدود الملفات المصاحبة هي نفسها الموضحة في الخطوة 1: إنشاء مهارتك الأولى والخطوة 2: إضافة المواد المرجعية (اختياري).

مهم

يثبّت wiqd plugin create الحزمة على manifestVersion: "1.29"، بينما تستخدم الأمثلة المكتوبة بخط اليد في هذه المقالة 1.28. الفرق مهمّ بالنسبة إلى الموصلات. عند 1.28، يكون mcpToolDescription مطلوبًا، ويجب أن يكون الملف الذي يسمّيه داخل ملف ZIP. في النسخة 1.29، تكون الإدخالات مقتصرة على عناوين URL فقط ويكون mcpToolDescription اختياريًا، لذلك لا تواجه الحزمة التي ينشئها wiqd فشل التحميل هذا. لا يدعم wiqd إعداد مصادقة الموصل تلقائيًا حتى الآن — قم بتكوينه مباشرة كما هو موضح في أنواع المصادقة المعتمدة.

الخطوة 3: التحقق أثناء الإنشاء

تحقق بشكل مستمر بدلاً من تجميع حزمة على أمل أن ينجح الرفع:

wiqd plugin validate
wiqd plugin validate --mode deep

validate هو الفحص الثابت غير المتصل بالإنترنت على سطح العامل التصريحي. يجتاز هذا الفحصَ المكوّنُ الإضافي الخاص بالمهارات فقط أو الخاص بالموصل فقط من دون وجود ما يلزم التحقق منه، وهذا أمر متوقع، لأنه فحصٌ لدورة البناء لديك، وليس فحصًا للتغطية الكاملة. validate --mode deep يقوم بحزم المكون الإضافي أولاً، ثم يتحقق من صحة النسخة المبنية .zip مقابل مكتبة التحقق من صحة التطبيق نفسها التي تستخدمها عملية الرفع. هذا هو المكان الذي تظهر فيه رموز ASKILL وقواعد الموصل.

قم بتشغيل هذه الأوامر الثلاثة بالترتيب:

wiqd plugin provision
wiqd plugin package
wiqd plugin share --scope users --email you@contoso.com

شغّل provision أولًا لأنه يكتب ملف البيئة الذي يعتمد عليه كل من package وshare. استخدم --scope users للمشاركة مع الأشخاص الذين تدرجهم في القائمة، أو --scope tenant للمشاركة مع جميع الأشخاص في مؤسستك. في كلتا الحالتين، يظهر المكون الإضافي في تمت مشاركته معي ضمن Cowork>المصادر والمهارات>. لإدراجها بدلاً من ذلك في قسم "اكتشاف"، يقوم مسؤول بتحميل الحزمة. تعرّف على المزيد في الخطوة 8: النشر إلى المستأجر الخاص بك. لإزالة ما أنشأه provision، قم بتشغيل wiqd plugin delete --env local --yes.

ما زال إرسال التطبيق إلى المتجر العام عملية يدوية في Partner Center. تعرف على المزيد في الخطوة 9: النشر للجمهور.

خذ مكونًا إضافيًا إلى مضيف آخر

لاستخدام مهاراتك في Claude Code أو Cursor أو أي مضيف Agent Skills آخر، قم بتصدير المشروع بدلا من نسخ المجلدات يدويا:

wiqd plugin export --format claude-plugin

export يكون افتراضيًا --format open-plugin ويقبل أيضًا cursor-plugin. ينشئ دليلاً غير مضغوط تحت <path>/export/<format>.

استيراد مكون إضافي موجود

إذا كان لديك بالفعل مكون إضافي Claude Code مع خوادم المهارات و MCP ، فلديك طريقان للتحويل. يعتمد المسار الذي تختاره على ما إذا كنت تخطط لمواصلة تطوير المكون الإضافي أو مجرد إصدار ما لديك.

الهدف	استخدم
استمر في تطوير المكون الإضافي والتحقق من صحته وإصداره من Microsoft 365	`wiqd plugin import`
أنشئ مادة قابلة للنشر `.zip` من إضافة Claude موجودة الآن	البرنامج النصي للتحويل

الاستيراد باستخدام wiqd

wiqd plugin import يتعرّف على مصدر إضافة Open Plugin أو إضافة Claude أو إضافة Cursor، ويُنشئ منه مشروع إضافة wiqd. ينضم المكوّن الإضافي المستورد إلى نفس دورة حياة المكوّن الإضافي التي قمت بإنشائها باستخدام wiqd plugin create:

wiqd plugin import --path ./my-claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

--privacy-url و--terms-url مطلوبان فقط عند أول استيراد للمكوّن الإضافي. إذا جاء المصدر من عنصر سابق wiqd plugin export، فإن بيانات التعريف للرحلة ذهابًا وإيابًا تحملها بالفعل.

مهم

يدعم المشروع المستورد جزء القراءة فقط من دورة الحياة —wiqd plugin validate، showو list. لا يمكن حزمها أو إعدادها أو مشاركتها بعد، لأن عملية الاستيراد لا يُنشئ ملفات النشر المحلية اللازمة التي تحتاجها هذه الخطوات. هذه فجوة قيد التتبع. لمعرفة الحالة الحالية، تحقق من مرجع wiqd CLI. إذا كنت بحاجة إلى حزمة قابلة للنشر اليوم، فاستخدم البرنامج النصي الخاص بالتحويل.

حوّل باستخدام البرنامج النصي للتحويل

يترجم البرنامج النصي للتحويل مكون Claude الإضافي مباشرة إلى حزمة M365 قابلة للنشر:

تثبيت واجهة سطر الأوامر (تتطلب الإصدار 1.1.12 أو إصدار أحدث):
```
npm install -g @microsoft/m365agentstoolkit-cli
```
تحقق من الإصدار:
```
atk --version
```

استورد المكون الإضافي:

atk import openplugin --path ./my-claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

يقرأ الأمر المكون .claude-plugin/plugin.json الإضافي (أو.cursor-plugin/plugin.json) والدليل .mcp.jsonskills/ ، ثم يقوم بسقالات مشروع مجموعة أدوات الوكلاء الذي يحتوي على appPackage/manifest.jsonمهاراتك والأيقونات التي تم إنشاؤها.

يجب عليك تضمين --privacy-url بيانات المكون الإضافي ولأن --terms-url بيانات المكون الإضافي لا تحتوي على حقول متكافئة، ويتطلب بيان Microsoft 365 كليهما.

Note

atk import openpluginتحديد موقع بيان مكون إضافي في دليل ببادئة نقطة—.claude-plugin/plugin.json, .cursor-plugin/plugin.json, أو .plugin/plugin.json—إلى جانب ..mcp.json تضع مواصفات Agent Plugins 1.0.0 ملف البيان على المستوى plugin.json الأعلى وتكوين MCP في mcp.json. لاستيراد مكون إضافي يتبع التخطيط 1.0.0، انقل ملف البيان الخاص به إلى .plugin/plugin.json وأعد تسمية mcp.json إلى .mcp.json.

قم بتجميع الناتج في ملف قابل .zipللرفع:

cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
  --output-package-file ./appPackage/build/appPackage.zip \
  --output-folder ./appPackage/build

Note

atk import openplugin يُنشئ ملف بيان devPreview. تستهدف أمثلة البيان الواردة في مواضع أخرى من هذه المقالة الإصدار v1.28 من المخطط. إذا كنت تقوم بالنشر من خلال قناة تتطلب الإصدار 1.28، فقم بتحديث manifestVersion و$schema في appPackage/manifest.json الذي تم إنشاؤه.

ما يتم استيراده

حزمة المكون الإضافي	مكافئ M365	الملاحظات
`.claude-plugin/plugin.json`	`manifest.json`	تم تعيين حقول الاسم والوصف والمطور؛ معرف GUID المنشأ تلقائيا (UUID v5 المحدد)
`skills/*/SKILL.md`	`agentSkills[]` إدخالات + `skills/` مجلد	تم النسخ حرفيا - تنسيق متطابق
`.mcp.json` الخوادم	`agentConnectors[]` إدخالات	تم الكشف التلقائي عن عنوان URL ونوع المصادقة
`color.png` / `outline.png`	الأيقونات في الحزمة	تستخدم إن وجدت؛ عناصر نائبة يتم إنشاؤها إذا كانت مفقودة

مهم

لكل موصل يتم استيراده من .mcp.json، يكون authorization.referenceId المُنشأ عنصر نائب مشتقًا من اسم المكون الإضافي واسم الخادم. استبدله بمعرف تسجيل عميل OAuth الفعلي قبل النشر. تعرف على المزيد حول أنواع المصادقة المعتمدة.

الأمور التي لم يتم تحويلها

ميزات مكون Claude الإضافي التالية غير مدعومة بعد في بيان Microsoft 365:

ميزة المكون الإضافي Claude	Status
`commands/` (أوامر الشرطة المائلة للأمام)	غير مدعوم حتى الآن
`agents/` (الوكلاء الفرعيون)	غير مدعوم حتى الآن
`hooks/` (معالجات الأحداث)	غير مدعوم حتى الآن
`settings.json`	غير قابل للتطبيق
`bin/` (العناصر التنفيذية)	غير قابل للتطبيق

خيارات الاستيراد

خيار	Description
`--path`، `-p`	Required. دليل المكون الإضافي الذي يحتوي على `.claude-plugin/plugin.json`، `.cursor-plugin/plugin.json`، أو `.plugin/plugin.json`
`--output`، `-o`	مجلد مشروع الوجهة (الافتراضي: `./<plugin-name>`)
`--privacy-url`	`developer.privacyUrl` للبيان الذي تم إنشاؤه
`--terms-url`	`developer.termsOfUseUrl` للبيان المُنشأ
`--website-url`	. يعود إلى `homepage`، ثم `author.url`
`--app-id`	استبدل UUID v5 الحتمي الذي تم إنشاؤه للبيان `id`
`--default-auth-type`	`Auto`(افتراضي) أو `None`أو `OAuthPluginVaultApiKeyPluginVault`

الكشف التلقائي لنوع المصادقة:

المصدر	نوع المصادقة الافتراضي	Reason
عناوين URL الخارجية لـ HTTPS	`OAuthPluginVault`	تحتاج معظم واجهات برمجة التطبيقات البعيدة إلى المصادقة
`localhost` وعناوين URL غير HTTPS	`None`	خوادم التطوير المحلية

إذا لم يتطابق الكشف التلقائي مع الإعداد، فاستخدمه --default-auth-type لتجاوزه.

الرجوع بالتصدير إلى دليل مكون إضافي

لنقل مشروع Agents Toolkit مرة أخرى إلى دليل مكون إضافي - على سبيل المثال ، للاحتفاظ بالمكون الإضافي Claude Code وحزمة Cowork في حالة المزامنة - استخدمatk export openplugin:

atk export openplugin --path ./my-plugin-project \
  --output ./my-claude-plugin --manifest-kind claude-plugin

خيار	Description
`--path`، `-p`	Required. يحتوي مجلد مشروع مجموعة أدوات الوكلاء على `appPackage/manifest.json`
`--output`، `-o`	دليل المكون الإضافي الوجهة (افتراضي: `./<plugin-name>-openplugin`)
`--manifest-kind`	`open-plugin`(افتراضي، `.plugin/plugin.json`يكتب) أو `claude-plugincursor-plugin`

يكتب التصدير كتلة x-microsoft-365-agents-toolkit في العنصر الذي تم إنشاؤه plugin.json. تحمل هذه الكتلة البيان idوعناوين URL للمطور وإعدادات الموصل، لذلك في وقت لاحق atk import openplugin ذهابا وإيابا دون الحاجة --privacy-url أو --terms-url مرة أخرى.

Note

الكتلة x-microsoft-365-agents-toolkit خاصة بمجموعة أدوات الوكلاء، والنوع الافتراضي open-plugin يكتب البيان إلى .plugin/plugin.json. يستخدم Agent Plugins 1.0.0 عنصر plugin.json على المستوى الأعلى ويحمل البيانات الخاصة بالعميل ضمن مفتاح extensions بمساحة اسم ذات مجال عكسي، لذلك يتجاهل العملاء الآخرون هذه الكتلة بدلاً من التصرف بناءً عليها. عندما يكون هدفك هو Claude Code أو Cursor، استخدم --manifest-kind claude-plugin أو cursor-plugin.

إصدار قديم: برنامج نصي لتحويل PowerShell

قبل atk، كان التحويل يستخدم برنامج PowerShell النصي المخصص لنظام Windows فقط، والذي يظل متاحًا كبرنامج نصي للتحويل:

.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output

استخدم atk import openplugin بدلا من ذلك. إنه متعدد الأنظمة الأساسية، ويدعم مصادر Cursor بالإضافة إلى Claude Code، ويمكنه التصدير مرة أخرى إلى مجلد المكون الإضافي.

جمّع حزمة يدويًا

هذا القسم هو مرجع تنسيق الحزمة: يصف بالضبط ما Build a plugin with wiqd يولده، حقلًا تلو الآخر. اتبعها من طرف إلى طرف عندما يتعذر عليك تثبيت الأدوات أو عندما تقوم بإنشاء مسار معالجة الحزم الخاص بك. استخدمه كمرجع عندما تحتاج إلى فهم الحزمة التي تم إنشاؤها أو تصحيح الأخطاء فيها.

الخطوة 1: إنشاء مهارتك الأولى

المهارة عبارة عن مجلد يحتوي على ملف SKILL.md. قم بإنشاء بنية المجلد التالية:

my-extension/
└── skills/
    └── contract-analysis/
        └── SKILL.md

اكتب SKILL.md باستخدام ترويسة YAML ونص Markdown:

---
name: contract-analysis
description: |
  Analyzes contracts for key terms, risks, and obligations.
  Use when user asks to "review this contract", "find the liability clause",
  "summarize the key terms", or "compare these two agreements".
license: MIT
metadata:
  author: Contoso Legal Tech
  version: "1.0"
---

# Contract Analysis

## What This Skill Does

Guides Cowork through systematic contract review, identifying:
- Key commercial terms (pricing, payment, renewal)
- Risk clauses (indemnification, limitation of liability, IP)
- Obligations and deadlines
- Non-standard or unusual provisions

## Workflow

1. Read the uploaded contract document
2. Extract and categorize all clauses
3. Flag risk areas with severity ratings
4. Generate a structured summary with recommendations

## Output Format

Present findings in a structured table:

| Clause | Category | Risk Level | Summary |
|--------|----------|------------|---------|
| Section 4.2-Indemnification | Risk | High | Unlimited indemnification for IP claims |
| Section 7.1-Term | Commercial | Low | 12-month auto-renewal with 30-day notice |

حقول frontmatter في SKILL.md

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

الحقل	Constraints	Description
`name`	من 1 إلى 64 حرفًا، بنمط kebab-case	معرف المهارة - يجب أن يتطابق مع اسم المجلد تماما
`description`	من 1 إلى 1024 حرفًا	متى تستخدم هذه المهارة - قم بتضمين عبارات المشغل

مهم

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

مسار المجلد	`name` حقل	صالح؟	لماذا
`skills/contract-analysis/SKILL.md`	`contract-analysis`	‏‏نعم‬	تطابق المجلد والاسم
`skills/contract-analysis/SKILL.md`	`ContractAnalysis`	No	يستخدم الاسم PascalCase بدلاً من مطابقة اسم المجلد
`skills/my-skill/SKILL.md`	`contract-analysis`	No	المجلد `my-skill` لكن الاسم `contract-analysis`

قواعد التسمية (kebab-case): استخدم فقط الأحرف الأبجدية الرقمية الصغيرة والواصلات. لا تستخدم واصلات متتالية، ولا تستخدم واصلات بادئة أو لاحقة.

مثال	صحيح؟	مشكلة
`bond-relative-value`	‏‏نعم‬	أحرف صغيرة مع واصلات
`fx-carry-trade`	‏‏نعم‬	أحرف صغيرة مع شرطات
`email`	‏‏نعم‬	كلمة واحدة، لا حاجة لشرطات الوصل
`Bond_Relative_Value`	No	التسطير السفلي والأحرف الكبيرة
`--my-skill--`	No	شرطات بادئة ولاحقة
`my--skill`	No	شرطات متتالية

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

بالنسبة إلى المهارات المعقدة، أبقِ SKILL.md الرئيسي مختصرًا وانقل المحتوى التفصيلي إلى الأدلة الفرعية. هذه الملفات الإضافية هي ملفات مصاحبة. المهارة تحمّلها عند الحاجة.

skills/
└── contract-analysis/
    ├── SKILL.md               # Core workflow (~1,500-2,000 words ideal)
    ├── references/            # Deep-dive docs loaded on demand
    │   ├── clause-taxonomy.md
    │   └── risk-scoring.md
    └── scripts/               # Executable utilities
        └── extract-clauses.py

حدود الملفات المصاحبة

يمكن أن تتضمن كل مهارة ما يصل إلى 20 ملفا مصاحبا (أي ملف آخر غير SKILL.md). تنطبق الحدود التالية لكل مهارة:

Limit	Value
الحد الأقصى لعدد الملفات المصاحبة	20
الحد الأقصى لحجم كل ملف مصاحب	5 ميغابايت
الحد الأقصى لإجمالي حجم Companion	10 ميغابايت
انتهاء مهلة التنزيل (كل الأجهزة المصاحبة)	15 ثانية

قواعد الملف المصاحب

يجب أن تتبع مسارات الملفات المصاحبة هذه القواعد:

استخدم المسارات النسبية فقط (بدون مسارات مطلقة).
لا يوجد اجتياز مسار (.. أجزاء).
لا توجد خطوط مائلة عكسية أو وحدات بايت خالية في أسماء الملفات.
لا توجد ملفات مخفية (الأسماء التي تبدأ ب .).
لا توجد أسماء Windows محجوزة (CON, AUX, PRN, COM1, NUL–COM9, LPT1–LPT9).
لا يتم احتساب الملف SKILL.md نفسه كملف مصاحب.
يجب أن تستخدم أسماء الملفات أحرفًا آمنة: الأحرف الأبجدية الرقمية والواصلات والتسطير السفلي والنقاط والمسافات وعلامة !.

للحفاظ على كفاءة نافذة السياق، يقوم النظام بتحميل المهارات في ثلاث طبقات:

الطبقة	عند التحميل	الحجم المستهدف
المحتوى التمهيدي (`name` + `description`)	دائما - عند بدء التشغيل	~100 رموز مميزة
`SKILL.md` المتن	عند تشغيل المهارة	أقل من 5000 رموز (1500-2000 كلمة)
المراجع (`references/`)	عند الطلب من قبل الوكيل	Unlimited
البرامج النصية (`scripts/`)	مُنفَّذ، ولم يتم تحميله في السياق	N/A

أشر إلى الدلائل الفرعية بشكل صريح حتى يعرف SKILL.md الوكيل وجودها:

## Additional Resources

- **`references/clause-taxonomy.md`**-Full taxonomy of contract clause types
- **`references/risk-scoring.md`**-Risk scoring methodology and thresholds
- **`scripts/extract-clauses.py`**-Automated clause extraction utility

الخطوة 3: إضافة موصل (اختياري)

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

نصيحة

إذا كان الخادم يقيّد ظهور الأداة حسب العميل أو يعزو حركة المرور الواردة، فانتقل إلى تحديد حركة مرور Cowork إلى الخادم الخاص بك لهوية العميل التي يقدمها Cowork.

Note

المكونات الإضافية المخصصة غير مدعومة في Cowork على الهاتف المحمول.

متطلبات الموصل

Requirement	تفاصيل
النقل	HTTP القابل للتدفق (HTTPS مطلوب، TLS 1.2+)
Protocol	تنسيق رسالة JSON-RPC 2.0
اكتشاف الأدوات	دعم `tools/list` الاكتشاف الديناميكي (مستحسن)
تنفيذ الأدوات	دعم `tools/call` الاستدعاء
Availability	التوصية باتفاقية مستوى الخدمة (SLA) وقت التشغيل بنسبة 99.9٪ للتطبيقات المنشورة في المتجر
وقت الاستجابة	أقل من 30 ثانية لكل استدعاء أداة

إرشادات تصميم الأداة

أداة واحدة لكل إجراء لواجهات برمجة التطبيقات الصغيرة (أقل من 15 عملية): search_case_law، get_ruling، cite_precedent
البحث + التنفيذ لواجهات برمجة التطبيقات الكبيرة (50+ عملية): search_actions + execute_action
الأسماء الوصفية: get_bond_price وليست getData
مخططات الإدخال الغنية: قم بتضمين وصف لكل معلمة - هذا ما يقرأه الوكيل
الإخراج المنظم: إرجاع JSON الذي يمكن للوكيل تنسيقه للمستخدم
إدخالات الملف: لقبول ملف من مساحة عمل المستخدم، أعلن المعلمة باستخدام contentEncoding: base64. تعرف على المزيد في قبول الملفات من مساحة عمل Cowork.

صِف أدوات أداة الربط الخاصة بك (`mcpToolDescription`)

يمكن أن يتضمن mcpToolDescription الموصل remoteMcpServer كائنا بشكل اختياري. عند توفيرها، تشير الخاصية المتداخلة file إلى ملف JSON لوصف الأداة الذي تحزمه بداخلك .zip وتشير إليه بمسار نسبي من جذر الحزمة. يكتشف Cowork الأدوات بشكل ديناميكي من خادم MCP لديك ولا يستخدم هذا الملف، حتى عندما يكون موجودًا.

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp",
  "mcpToolDescription": {
    "file": "./tools/contoso-legal-tools.json"
  },
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
  }
}

إذا قمت بتضمين mcpToolDescription، فإن الملف المشار إليه (على سبيل المثال، tools/contoso-legal-tools.json) يصف الأدوات التي يعرضها الموصل ويجب أن يكون موجودًا في حزمة ZIP. قم بتضمينه جنبًا إلى جنب مع المجلد manifest.json والمجلد skills/ عند حزم المكون الإضافي.

نصيحة

ينطبق هذا الشرط على إصدار manifest 1.28. الحزم التي يُنشئها wiqd plugin create تستهدف الإصدار 1.29، حيث تكون إدخالات agentConnectors[] عناوين URL فقط، ويكون mcpToolDescription اختياريًا، ولا يوجد ملف لوصف الأداة يمكن نسيانه.

أنواع المصادقة المعتمدة

نوع المصادقة	وقت الاستخدام	تجربة المستخدم
`None`	واجهات برمجة التطبيقات العامة أو مجهولة الهوية، والخدمات الداخلية	شفاف - لا توجد مطالبة مصادقة
`OAuthPluginVault`	واجهات برمجة تطبيقات OAuth 2.0 (مستحسن للإنتاج)	يُكمل المستخدم الموافقة على OAuth مرة واحدة فقط
`ApiKeyPluginVault`	الخدمات المستندة إلى مفتاح API	يقدم المستخدم المفتاح مرة واحدة

Note

لا يتوفر دعم مصادقة مفتاح واجهة برمجة التطبيقات في Cowork حتى الآن.
إذا كان خادم MCP الخاص بك يتطلب مفتاح واجهة برمجة التطبيقات، فاستخدم OAuthPluginVault أو التسجيل الديناميكي للعميل بدلًا من ذلك، أو اعرض نقطة نهاية تقبل None.

بالنسبة إلى OAuthPluginVault وApiKeyPluginVault، يشير referenceId إلى بيانات الاعتماد المخزنة في Microsoft Enterprise Token Store - لا تظهر الأسرار أبدا في ملفات البيان أو المهارات. القيمة referenceId هي معرّف تسجيل عميل OAuth الذي تنشئه عند تسجيل عميل OAuth باستخدام Agents Toolkit.

مهم

عند تسجيل عميل OAuth، قم بتعيين الاستخدام حسب المؤسسة إلى أي مؤسسة Microsoft Entra ID متعددة المستأجرين ودليل Microsoft الشخصي لضمان عمل المكون الإضافي الخاص بك عبر المستأجرين.

مصادقة MCP

لاستخدام OAuth أو ApiKey للمصادقة، راجع تكوين المصادقة للمكونات الإضافية MCP وAPI في الوكلاء في Microsoft 365 Copilot للحصول على تفاصيل الإعداد والتكوين.

تسجيل العميل الديناميكي

إذا كان خادم MCP لديك يدعم التسجيل الديناميكي للعميل (DCR)، فيمكنك الاستغناء عن تكوين authentication في تعريف أداة الربط، وسينشئ Cowork تلقائيًا عميل OAuth نيابةً عن المكوّن الإضافي الخاص بك.

Note

عدم تضمين التكوين authentication مدعوم فقط في Cowork. إنه غير مدعوم في Copilot Chat. إذا كان المكون الإضافي يحتاج أيضا إلى العمل في Copilot Chat، فقم بتكوين OAuthPluginVault المصادقة كما هو موضح في أنواع المصادقة المدعومة.

يمكنك حذف الكائن authorization بالكامل. قم بتكوين عنوان URL لخادم MCP الخاص بك، وسيتولى Cowork إعداد عميل OAuth:

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp"
}

الخطوة 4: إنشاء الملف التعريفي

أنشئ manifest.json في جذر الحزمة. يستخدم المثال إصدار البيان 1.28؛ wiqd plugin create يثبّت 1.29 بدلاً من ذلك، حيث تتكون إدخالات الموصل من عناوين URL فقط.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
  "manifestVersion": "1.28",
  "version": "1.0.0",
  "id": "YOUR-GUID-HERE",
  "developer": {
    "name": "Contoso Legal Tech",
    "websiteUrl": "https://contoso.com",
    "privacyUrl": "https://contoso.com/privacy",
    "termsOfUseUrl": "https://contoso.com/terms"
  },
  "name": {
    "short": "Contoso Legal Tools",
    "full": "Contoso Legal Tools for Copilot Cowork"
  },
  "description": {
    "short": "Contract analysis, clause extraction, and legal research",
    "full": "Comprehensive legal tools for Copilot Cowork including contract analysis, clause extraction, risk assessment, and legal research capabilities."
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "accentColor": "#2B579A",
  "agentSkills": [
    { "folder": "./skills/contract-analysis" }
  ]
}

لإضافة موصل، قم بتضمين agentConnectors:

{
  "agentConnectors": [
    {
      "id": "contoso-legal-api",
      "displayName": "Contoso Legal Database",
      "description": "Access to case law, statutes, and regulatory databases",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "https://api.contoso.com/legal/mcp",
          "mcpToolDescription": {
            "file": "./tools/contoso-legal-tools.json"
          },
          "authorization": {
            "type": "OAuthPluginVault",
            "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
          }
        }
      }
    }
  ]
}

في إعدادات الموصل، يجب أن يكون referenceId معرّف تسجيل OAuth. إذا قمت بتضمين mcpToolDescription، فيجب أن يشير file إلى ملف JSON لوصف الأداة المضمَّن في حزمة ZIP.

مهم

مخطط البيان للإصدار v1.28 صارم: إذ يعيّن additionalProperties: false في العنصر الجذر، لذلك يُرفض أي حقل غير معرّف في المخطط. تتسبب الحقول الصالحة في بيانات تطبيق Teams القياسية - مثل packageName— في فشل التحميل مع ظهور خطأ مثل Property 'packageName' has not been defined and the schema does not allow additional properties. ضمّن فقط الحقول المعروضة هنا.

الخطوة 5: إضافة أيقونات

قم بإنشاء أيقونتين بصيغة PNG:

Icon	Size	الغرض
`color.png`	192×192 بكسل	أيقونة التطبيق بالألوان الكاملة معروضة في قائمة التطبيقات والمتجر
`outline.png`	32×32 بكسل	أيقونة خطية أحادية اللون لطرق عرض مدمجة

إذا لم يكن لديك أيقونات حتى الآن، atk import openplugin فسينشئ عناصر نائبة بلون خالص. استبدلها قبل إرسال التطبيق إلى المتجر.

الخطوة 6: التغليف

قم بإنشاء ملف ZIP مع جميع المحتويات في مستوى الجذر. (wiqd plugin package ينتج نفس الهيكل بعد wiqd plugin provision.)

contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│   └── contoso-legal-tools.json   # Referenced by mcpToolDescription (optional, connectors only)
└── skills/
    └── contract-analysis/
        ├── SKILL.md
        └── references/
            └── clause-taxonomy.md

إذا كان الموصل يتضمن mcpToolDescription، فقم بتضمين ملف JSON لوصف الأداة الذي يشير إليه. لا تحتاج الحزم التي لا تستخدم mcpToolDescription، بما في ذلك الحزم المخصصة للمهارات فقط، إلى مجلد tools/.

Windows (PowerShell):

Compress-Archive -Path manifest.json, color.png, outline.png, tools, skills -DestinationPath contoso-legal-tools.zip

macOS/Linux:

zip -r contoso-legal-tools.zip manifest.json color.png outline.png tools/ skills/

استخدام مجموعة أدوات Microsoft 365 Agents

 atk package --manifest-file ./appPackage/manifest.json \
       --output-package-file ./appPackage/build/appPackage.zip \
       --output-folder ./appPackage/build

الخطوة 7: اختبر

لاختبار تطبيقك، قم بتحميل حزمة التطبيق إلى Teams كما هو موضح في تحميل التطبيق الخاص بك إلى Teams.

إذا أنشأت المكوّن الإضافي باستخدام wiqd، فشغّل wiqd plugin provision بدلًا من ذلك، إذ يسجّل المكوّن الإضافي في المستأجر الخاص بك نيابةً عنك. للاختبار الشخصي لحزمة مُجمَّعة يدويًا، ثبّت التطبيق تحميلًا جانبيًا من خلال واجهة سطر الأوامر لمجموعة أدوات Microsoft 365 Agents Toolkit:

ثبّت @microsoft/m365agentstoolkit-cli من npm:

npm install -g @microsoft/m365agentstoolkit-cli

تحقق من التثبيت عن طريق تشغيل:
```
atk --version
```
المصادقة باستخدام حساب العمل في Microsoft 365:
```
atk auth login
```
سجّل الدخول إلى حسابك الخاص بالعمل وثبّت حزمة الوكيل. استبدل مسار الملف بمسار حزمة ZIP لديك:
```
atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal
```
يرجع التثبيت الناجح الإخراج الذي يتضمن TitleId وAppId لحسابك.
احفظ هذه المعرفات لاستخدامها لاحقا عند التحديث أو إلغاء التثبيت.

الخطوة 8: النشر إلى التينانت

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

فتح >إدارة التطبيقات>رفع تطبيق مخصص.
حدد زر علامة الحذف (...)، ثم >إضافة وكيل.
قم بتحميل حزمتك .zip .
افتح Cowork>المصادر والمهارات>. يظهر المكون الإضافي في قسم اكتشاف.

wiqd plugin share يضع المكوّن الإضافي ضمن تمت مشاركته معي بدلاً من استكشاف. استخدمه للاختبار وللطرح الموجّه لأشخاص محددين. إن رفع المكون الإضافي في مركز الإدارة هو ما يدرج المكون الإضافي بحيث يمكن اكتشافه.

الخطوة 9: النشر للعامة

بالنسبة إلى المكونات الإضافية المُعدّة للتوزيع العام، قدّم المكون الإضافي إلى متجر تطبيقات Microsoft 365 عبر مركز الشركاء. تعرف على المزيد في نشر العوامل ل Microsoft 365 Copilot.

اختبر موصّلًا باستخدام خادم MCP محلي

تتطلب الموصلات اتصال HTTPS mcpServerUrl. لاختبار خادم يعمل على جهازك، تحتاج إلى عرضه عبر عنوان URL HTTPS عام. توفر أنفاق التطوير خدمة ترحيل تتولى إنهاء اتصال TLS نيابةً عنك.

devtunnel port create <tunnel> -p <port> --protocol http

مهم

استخدم --protocol http، وليس https. تصف العلامة --protocol الخدمة المحلية التي يوجِّه النفق إليها، وليس عنوان URL العام للنفق. تتحدث معظم خوادم MCP المحلية بتنسيق HTTP العادي، لذلك إذا قمت بالتعيين --protocol https أثناء قيام الخادم الخاص بك بخدمة HTTP، فإن كل طلب عبر النفق يرجع خطأ 502 . يقوم المرحل بإنهاء TLS ويخدم عنوان URL العام عبر HTTPS بغض النظر عن هذه العلامة.

Troubleshooting

عَرَض	السبب	إصلاح
يُرجع كل طلب مُمرَّر عبر نفق `502` ويتحدث الخادم المحلي بروتوكول HTTP	`devtunnel port create` تم تشغيله باستخدام `--protocol https`	أعد إنشاء المنفذ باستخدام `--protocol http`
تُرجِع الطلبات المُمرَّرة عبر نفق `502` على macOS على الرغم من تشغيل الخادم المحلي	يكون الخادم مرتبطًا بـ `0.0.0.0` (IPv4 فقط)، ولكن النفق يتصل بـ `localhost`، الذي يُحل إلى `::1` (IPv6) أولًا	ربط الخادم ب `::` بحيث يقبل اتصالات IPv4 وIPv6 على حد سواء
يفشل التحميل مع `Property '<field>' has not been defined and the schema does not allow additional properties`	يتضمن البيان حقلا لا يسمح به مخطط v1.28 (على سبيل المثال، `packageName`)	أزل الحقل؛ إذ يستخدم مخطط v1.28 `additionalProperties: false`

أنماط التعبئة والتغليف

اختر النمط الذي يناسب ملحقك:

المهارات فقط (بدون الموصل)

الأفضل لمهام سير العمل المستندة إلى المطالبة وتحليل المستندات والمساعدة في الكتابة.

my-skills-pack.zip
├── manifest.json          # agentSkills only, no agentConnectors
├── color.png
├── outline.png
└── skills/
    ├── skill-one/SKILL.md
    └── skill-two/SKILL.md

المهارات + موصل الاتصال عن بُعد

الأفضل لتحليل البيانات وعمليات تكامل واجهة برمجة التطبيقات وأنظمة المؤسسات.

my-data-skills.zip
├── manifest.json          # agentSkills + agentConnectors
├── color.png
├── outline.png
├── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
│   └── my-connector.json
└── skills/
    ├── analysis-workflow/SKILL.md
    └── reporting-workflow/SKILL.md

أداة الربط فقط (بدون مهارات مخصصة)

استخدم هذا الخيار لمصادر البيانات التي يمكن للمهارات المضمّنة في Cowork استخدامها بالفعل.

my-connector.zip
├── manifest.json          # agentConnectors only, no agentSkills
├── color.png
├── outline.png
└── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
    └── my-connector.json

Claude Code المستورد أو المكون الإضافي لـ Cursor

استخدم هذا الخيار للمكونات الإضافية الحالية لنظام Claude البيئي التي تستهدف Cowork. لمتابعة تطوير المكون الإضافي في Microsoft 365، قم باستيراده:

wiqd plugin import --path ./claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

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

atk import openplugin --path ./claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

أفضل ممارسات تأليف المهارات

اتبع هذه الإرشادات لإنشاء مهارات يتم تنشيطها بشكل موثوق وتحقق نتائج متسقة.

اكتب أوصافًا فعّالة

يحدد description الحقل متى ينشط الوكيل مهارتك. كن محددا:

# Good-specific trigger phrases, concrete scenarios
description: |
  Analyzes bond relative value using Z-spreads, ASW spreads, and butterfly analysis.
  Use when user asks to "analyze bond spreads", "compare bonds",
  "rich-cheap analysis", "relative value", or "Z-spread calculation".

# Bad-vague, no trigger phrases
description: Provides bond analytics capabilities.

اكتب سير عمل فعال

كن محددا في الوصف. تضمين عبارات التشغيل: "استخدم عندما يطلب المستخدم من..." هذا الوصف هو الطريقة التي يقرر بها العامل المهارة التي يجب تنشيطها.
الهيكلة كسير عمل. رقّم الخطوات. يجب تعيين كل خطوة إلى إجراء ملموس (قراءة ملف ، استدعاء أداة ، إنشاء إخراج).
حدّد تنسيق الإخراج. اعرض الجدول أو القائمة أو بنية المستند التي يجب أن يتوقعها المستخدمون بالضبط. هذا التعريف يحسن الاتساق بشكل كبير.
أدوات مرجعية حسب الاسم. إذا كانت مهارتك تعتمد على أدوات الربط، فقم بتسميتها صراحة: "استخدم أداة search_case_law من أجل..."
حافظ على SKILL.md الرئيسي موجزًا. نقل المواد المرجعية المفصلة إلى الدليل الفرعي references/ . يجب أن يكون محتوى المهارة هو سير العمل، وليس موسوعة.

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

لا تقم بتضمين الأسرار في SKILL.md الملفات. استخدم agentConnectors مع المصادقة لبيانات اعتماد API.
لا تكرر المهارات المضمنة. تحقق من قائمة المهارات المضمنة قبل الإنشاء.
لا تجعل المهارات واسعة جدا. "القيام بكل شيء باستخدام المستندات القانونية" أسوأ من المهارات المحددة لـ "تحليل العقود" و"استخراج البنود" و"البحث القانوني".
لا تقم بترميز مسارات الملفات أو أوامر النظام بشكل ثابت. يجب أن تكون المهارات محمولة عبر البيئات.
لا تضع كل شيء في SKILL.md. إذا تجاوز جسمك ~3000 كلمة، فانقل المحتوى التفصيلي إلى references/.

قواعد التحقق من الصحة

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

للتقاطها أثناء الإنشاء بدلا من وقت التحميل، قم بتشغيل wiqd plugin validate --mode deep. يقوم هذا الأمر بحزم المكون الإضافي وتشغيل نفس القواعد محليا. تعرف على المزيد في الخطوة 3: التحقق أثناء الإنشاء.

التحقق من صحة على مستوى البيان

Code	‏‏قاعدة	Severity
ASKILL-M001	`folder` مطلوب على كل `agentSkills` إدخال	خطأ
ASKILL-M002	`agentSkills` يمكن أن يحتوي الصفيف على ما يصل إلى 20 عنصرا	خطأ
ASKILL-M003	`folder` يمكن أن يصل المسار إلى 256 حرفا	خطأ

التحقق من الصحة على مستوى الحزمة

Code	‏‏قاعدة	الإصلاح الشائع	Severity
ASKILL-P001	المجلد المشار إليه في بيان البيانات موجود في ZIP	التحقق من بنية ZIP	خطأ
ASKILL-P002	يحتوي المجلد على `SKILL.md` ملف	أضف العنصر المفقود `SKILL.md`	خطأ
ASKILL-P003	`SKILL.md` يحتوي على ترويسة YAML الأمامية الصالحة بين فواصل `---`	إصلاح بناء جملة YAML	خطأ
ASKILL-P004	تتضمن Frontmatter `name` حقل	إضافة `name:` إلى الفرونت ماتر	خطأ
ASKILL-P005	تتضمن Frontmatter `description` حقلا	إضافة `description:` إلى frontmatter	خطأ
ASKILL-P006	`name` يتطابق مع اسم المجلد (مقطع المسار الأخير)	إعادة تسمية مجلد أو إصلاح `name:`	خطأ
ASKILL-P007	`name` هو بصيغة kebab-case	استخدم `my-skill` وليس `MySkill` أو `my_skill`	خطأ
ASKILL-P008	لا توجد قيم مكررة `folder` في الصفيف	إزالة التكرارات	خطأ

التحقق من صحة المُوصِّل

‏‏قاعدة	Severity
يتطلب كل موصل `id` و`displayName`	خطأ
يجب أن تكون كل قيم الموصل `id` فريدة داخل ملف البيان	خطأ
واحد بالضبط من `plugin` أو `remoteMcpServer`	خطأ
`mcpServerUrl` يجب أن يكون عنوان URL صالحًا لبروتوكول HTTPS	خطأ
إذا `mcpToolDescription` كان موجودًا، فيجب أن يكون `file` الخاص به موجودًا في ملف ZIP	خطأ
`authorization.referenceId` مطلوب إلا إذا كان النوع `None`	خطأ
`authorization.referenceId` يجب ألا يكون موجودا عندما يكون النوع `None`	خطأ

التحقق من صحة الملف المصاحب

تتحقق البوابة من صحة الملفات المصاحبة (المواد المرجعية والبرامج النصية والملفات الأخرى الموجودة إلى جانب SKILL.md) في وقت التحميل والمزامنة:

‏‏قاعدة	Severity
20 ملفا مصاحبا كحد أقصى لكل مهارة (باستثناء `SKILL.md`)	خطأ
يجب أن يكون حجم كل ملف مصاحب 5 ميغابايت أو أقل	خطأ
يجب أن يكون إجمالي حجم الملفات المصاحبة 10 ميغابايت أو أقل لكل مهارة	خطأ
يجب أن تكون مسارات الملفات نسبية (بدون مسارات مطلقة)	خطأ
لا توجد مقاطع لاجتياز المسار (`..`)	خطأ
لا توجد خطوط مائلة عكسية أو بايتات فارغة في أسماء الملفات	خطأ
لا توجد ملفات مخفية (أسماء تبدأ ب `.`)	خطأ
لا توجد أسماء Windows محجوزة (`CON`، `PRN`، `AUX`، `COM1`، `NUL`–`COM9`، `LPT1`–`LPT9`)	خطأ
يجب أن تستخدم أسماء الملفات أحرفًا آمنة فقط (الأبجدية الرقمية والواصلات والتسطير السفلي والنقاط والمسافات و`!`)	خطأ

التوافق عبر الأنظمة الأساسية

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

Platform	التوافق
شيفرة كلود	تنسيق مطابق تمامًا `SKILL.md`
مشاريع Claude.ai	يمكن تحميل Full-skills كملفات مشروع
VS Code / GitHub Copilot	المهارات المدعومة لـ Full-Agent في وضع الوكيل
Gemini CLI	المهارات التي يدعمها Full-Agent
JetBrains Junie	المهارات التي يدعمها Full-Agent
OpenAI Codex	المهارات التي يدعمها Full-Agent
المؤشر	المهارات التي يدعمها Full-Agent

إذا كنت تعمل على تطوير مهارات لكل من Claude Code و Copilot Cowork ، فقم بتأليف المكون الإضافي باستخدام wiqd. ثم قم بتشغيل wiqd plugin export --format claude-plugin لإنتاج تخطيط Claude Code. إذا كنت تفضل البدء من بنية المكون الإضافي Claude Code — وهي البنية الأشمل — فإن التخطيط هو:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Claude plugin manifest
├── skills/
│   ├── skill-one/
│   │   ├── SKILL.md       # Works in both Claude Code AND M365
│   │   └── references/
│   └── skill-two/
│       └── SKILL.md
└── .mcp.json              # MCP server config (optional)

ثم أحضره إلى Microsoft 365 عندما تكون جاهزًا للنشر إلى Microsoft 365 App Store، إما باستخدام wiqd plugin import أو باستخدام البرنامج النصي للتحويل:

atk import openplugin --path ./my-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

إدارة التعليقات التوضيحية والتأكيد في MCP

يقرأ Copilot Cowork كائن MCP annotations القياسي المرتبط بالأدوات التي يعيدها الخادم من tools/list، ويستخدمه لتحديد ما إذا كان استدعاء الأداة يحتاج إلى تأكيد من المستخدم وما التسمية التي يجب إظهارها في المطالبة.

الحقول المتوفرة

الحقل	النوع	التأثير
`readOnlyHint`	bool	`false`: التأكيد مطلوب قبل تشغيل الأداة.
`destructiveHint`	bool	`true`: التأكيد مطلوب قبل تشغيل الأداة.
`title`	string	تسمية واضحة للمستخدم معروضة في مربع حوار التأكيد. يستخدم اسم الأداة كخيار احتياطي عند عدم وجوده.

قواعد التحقق

يكون التأكيد مطلوبًا إذا كان readOnlyHint == false أو destructiveHint == true.

يجب أن تحتوي جميع الأدوات على وسوم السلامة المنصوص عليها. يتم التعامل مع الأدوات التي لا تحتوي على تعليقات توضيحية على أنها مدمرة وتتطلب تأكيدا. اطّلِع على المزيد في مرجع مخطط MCP.

أمثلة MCP

عمل مدمر مع تسمية ودية:

{
  "name": "send_email",
  "description": "Send an email message.",
  "annotations": {
    "title": "Send Email",
    "destructiveHint": true
  },
  "inputSchema": { ... }
}

قرص آمن يتم تشغيله تلقائيا:

{
  "name": "search_docs",
  "annotations": {
    "title": "Search Documents",
    "readOnlyHint": true
  }
}

ما المتوفر الآن

أدوات Microsoft ‏(Graph وDataverse وغيرها) تخضع لنهج Cowork المضمن بغض النظر عن التعليقات التوضيحية.
بالنسبة إلى الخوادم غير التابعة ل Microsoft MCP، يتم نشر التأكيد القائم على التعليقات التوضيحية بشكل تدريجي. إن إعداد التلميحات الآن متوافقًا مستقبليًا، وتظهر مطالبات التأكيد مع اتساع نطاق الطرح من دون الحاجة إلى أي تغيير من المطوّر.

قبول الملفات من مساحة عمل Cowork

يمكن أن تأخذ أداة الموصل ملفًا من جلسة Cowork الخاصة بالمستخدم كإدخال - مستند قام المستخدم بإرفاقه أو مرفق بريد إلكتروني قام Cowork بحفظه أو ملف تم إنشاؤه في خطوة سابقة. صرّح بالمعلمة باستخدام الكلمة الأساسية القياسية contentEncoding: base64 في مخطط JSON، وسيتولى Cowork معالجة الباقي. لا يوجد ملحق مخطط خاص ب Microsoft، ولا يتغير سطح واجهة برمجة التطبيقات الخاصة بالخادم.

يقوم Cowork بحل ملف مساحة العمل وترميزه base64 قبل استدعاء الخادم الخاص بك، لذلك لا تدخل وحدات بايت الملف في سياق العامل أبدا. لا يرى الوكيل ولا يُخرِج إلا مسارات ملفات مساحة العمل.

Note

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

تعريف معلمة ملف

يتم التعرّف على خاصية نصية تحتوي على contentEncoding: base64 على أنها حقل إدخال ملف:

{
  "name": "analyze_contract",
  "description": "Extract key terms from a contract document.",
  "annotations": {
    "title": "Analyze Contract",
    "readOnlyHint": true
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "document": {
        "type": "string",
        "contentEncoding": "base64",
        "description": "The contract file to analyze."
      },
      "jurisdiction": {
        "type": "string",
        "description": "Two-letter country code governing the contract."
      }
    },
    "required": ["document"]
  }
}

يُتعرَّف أيضًا على مصفوفة من هذه السلاسل، لأدوات تقبل عدة ملفات:

"attachments": {
  "type": "array",
  "items": { "type": "string", "contentEncoding": "base64" },
  "description": "Receipt images to attach to the expense line."
}

ما يراه الوكيل

بالنسبة لمعلمات الملفات المعلنة في المستوى الأعلى من inputSchema.properties، يستبدلها Cowork في المخطط المواجه للنموذج بصفيف واحد direct_attachment_file_paths - وهي نفس المعلمة التي تستخدمها الأدوات المضمنة في Cowork، بحيث يعرف الوكيل بالفعل كيفية ملئها. يتم تقديم المخطط أعلاه للوكيل على النحو التالي:

{
  "type": "object",
  "properties": {
    "direct_attachment_file_paths": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Workspace file paths to attach."
    },
    "jurisdiction": { "type": "string" }
  }
}

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

معلمات الملفات المتداخلة

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

"line_items": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "amount": { "type": "number" },
      "receipt": { "type": "string", "contentEncoding": "base64" }
    }
  }
}

يملأ الوكيل line_items[].receipt بمسار مساحة عمل، ويبدل Cowork كل مسار بمحتوى base64 في مكانه قبل إعادة توجيه المكالمة.

يتم اجتياز التعشيش إلى عمق أربعة مستويات أسفل الجزء العلوي من inputSchema. $ref لا تتم متابعة المؤشرات—عرّف معلمات الملف ضمن السطر بدلًا من وضعها خلف $ref.

ما يتلقاه الخادم الخاص بك

يتلقى الخادم الخاص بك طلبًا عاديًا tools/call بأسماء المعلمات الأصلية التي يتم تعبئتها بمحتوى مرمز بـbase64:

{
  "method": "tools/call",
  "params": {
    "name": "analyze_contract",
    "arguments": {
      "document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
      "jurisdiction": "US"
    }
  }
}

لا يحتاج الخادم إلى معرفة أن العامل استخدم واجهة مستندة إلى مسار، وأن الأدوات التي لا تعلن عن المعلمات contentEncoding: base64 لا تتأثر.

Limits

Limit	Value
الملفات لكل استدعاء أداة	8
الحجم لكل ملف	150 ميبيبايت
الحجم الإجمالي لكل استدعاء أداة	150 ميبيبايت
معلمات ملف المصفوفة لكل أداة	1 (أدمجها مع أي عدد من معلمات الملفات القياسية scalar)
الحد الأقصى لعمق التداخل	4 مستويات أسفل أعلى `inputSchema`

يفشل استدعاء يتجاوز عدد الملفات أو الحد الأقصى للحجم مع حدوث خطأ في الأداة ولا يصل إلى الخادم الخاص بك. اضبط حجم واجهة برمجة التطبيقات ومهلاتها مع وضع سقف 150 MiB في الاعتبار: يعمل ترميز Base64 على تضخيم الحمولة بمقدار الثلث تقريبًا مقارنةً بحجم الملف الخام، ويتم إرسال المحتوى المُرمَّز في نص طلب JSON-RPC.

التوصيات

صِف المعامل لقارئ بشري. يستخدم الوكيل الوصف لتحديد الملف الذي ينتمي إلى أي معامل. على سبيل المثال، "The signed contract PDF to analyze" يعمل بشكل أفضل من "file".
اذكر التنسيقات التي تقبلها في وصف المعلمة. يمرر Cowork كل ما يرفقه المستخدم. تحقّق من نوع المحتوى لديك، وأعِد رسالة خطأ واضحة من الأداة إذا لم يكن قابلًا للاستخدام.
ضبط التعليقات التوضيحية. عادة ما لا تكون الأداة التي تتلقى ملفا وتعمل عليه للقراءة فقط، لذا فهي تتطلب تأكيدا. تعرّف على المزيد حول التعليقات التوضيحية لـ MCP وإدارة عمليات التأكيد.
احتفظ بمعلمات الملف مضمنة. لا يُعاد كتابة أي معلمة تقع خلف $ref أو تكون متداخلة لأكثر من أربعة مستويات. سيتلقى الخادم سلسلة مسار حيث يتوقع المحتوى.
صرّح بمعلمة ملف صفيف واحدة على الأكثر لكل أداة. عند وجود ملفين أو أكثر، لا يستطيع Cowork معرفة الملف الذي ينتمي إلى أي صفيف، ويفشل الاستدعاء مع حدوث خطأ في الأداة. استخدم صفيفًا واحدًا، أو عدة معلمات قيمية، أو مزيجًا من القيم وصفيفًا واحدًا.
توقّع عدًّا دقيقًا في الأدوات المخصّصة للقيم القياسية فقط. إذا كانت أداتك تُصرّح فقط بمعلمات ملفات إفرادية، فيجب أن يتطابق عدد الملفات التي يمرّرها الوكيل مع العدد المُصرَّح به. ضع علامة على معلمات الملفات الاختيارية بوضوح في أوصافها حتى لا يزوّد الوكيل أقل أو أكثر من اللازم.

Note

سبقت هذه الآلية العملَ الخاص بإدخال الملفات في بروتوكول سياق النموذج نفسه، والذي تعمل مجموعة عمل تحميل ملفات MCP على توحيد معاييره. قد يضيف Cowork دعماً للنموذج القياسي لإدخالات الملفات التصريحية بمجرد وصوله. ولا يزال العقد contentEncoding: base64 الموصوف هنا ساريا.

تحديد حركة مرور Cowork إلى الخادم

إذا كان خادم MCP يقيّد ظهور الأداة حسب العميل، أو إذا كنت تريد أن تنسب حركة المرور التي يتلقاها الخادم، فيمكنك التعرّف على الطلبات التي تأتي من Cowork. يقدم Cowork هوية برمجية ثابتة على قناتين:

القناة	المكان الذي يظهر فيه	Value
`User-Agent` ترويسة الطلب	كل طلب صادر يرسله Cowork إلى الخادم الخاص بك	`copilot-cowork/1.0`
`clientInfo`في المصافحة الخاصة بـ MCP `initialize`	الطلب `initialize` فقط	`{ "name": "copilot-cowork", "version": "<version>" }`

المطابقة حسب البادئة `copilot-cowork`

تطابق البادئةcopilot-cowork، غير حساسة لحالة الأحرف، على أي قناة. لا تتطابق مع السلسلة الصحيحة copilot-cowork/1.0 أو مع سلسلة معينة clientInfo.version. يتتبع الإصدار عقد هوية العميل ومن المتوقع أن يتغير. يحافظ تطابق البادئة على عمل بوابتك عبر زيادات أرقام الإصدارات.

# Correct: case-insensitive prefix match
copilot-cowork

# Incorrect: exact match breaks when the version changes
copilot-cowork/1.0

اختر القناة المناسبة لبوابتك

للقناتين نطاقات مختلفة، لذا اضغط على النطاق الذي يتطابق مع كيفية فرض الخادم الخاص به:

User-Agent الرأس موجود على كل طلب، بما في ذلك tools/list وtools/call. إذا قمت ببوابة أو سمة لكل طلب، فاضغط على المفتاح على رأس الصفحة هذا.
clientInfoعند المصافحة initializeفقط. إذا قمت بالبوابة لكل جلسة عمل في وقت الاتصال، يمكنك قراءتها هناك، ولكن لا تتكرر في الطلبات لاحقا.

ما تتضمنه الهوية وما لا تتضمنه

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

تتضمن الهوية ما يلي	لا تتضمن الهوية
اسم برنامج ثابت (`copilot-cowork`) وإصدار العقد	أي مستأجر أو مستخدم أو جلسة أو معرف محادثة
القيمة نفسها لكل طلب وكل اتصال	مُحدِّد خاص بكل موصل

نظرا لعدم وجود مؤهل لكل موصل، لا يمكنك حاليا استخدام هذه الهوية لمعرفة الموصل الذي أجرى مكالمة، أو لفصل مكون Microsoft الإضافي المنشور عن خادم التحميل الجانبي الموجه إلى نفس عنوان URL. إذا كنت بحاجة إلى هذا التمييز، فارضه من خلال تكوين تخويل الموصل بدلا من هوية العميل.

الأسئلة الشائعة

هل يمكنني استخدام المهارات من حزمة M365 في Claude Code؟

Yes. تحتوي مجلدات المهارات على "مهارات الوكيل" القياسية. قم بتشغيل wiqd plugin export --format claude-plugin لإنتاج تخطيط Claude Code، أو انسخ مجلدات المهارات إلى .claude/skills/ في أي مشروع Claude Code.

هل أحتاج إلى الموصل البعيد؟

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

كيف تختلف مهارات المكونات الإضافية عن المهارات المضمنة؟

تظهر مهارات المكون الإضافي مع المصدر "package" في واجهة برمجة التطبيقات. لا يمكنهم تجاوز المهارات المضمنة التي تحمل الاسم نفسه. الحزم التي نشرها المسؤول تُظهر isAdminDeployed: true.

هل يمكن لمسؤولي تكنولوجيا المعلومات التحكم في المكونات الإضافية المتوفرة؟

Yes. تنطبق عناصر تحكم مسؤول Standard M365: قوائم السماح/الحظر على مستوى المستأجر، وعمليات التوزيع المدارة من قبل المسؤول، ونهج التوافق.

ماذا يحدث إذا تم إبطال مكون إضافي؟

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

ما هو الحد الأقصى لعدد المهارات لكل حزمة؟

عشرون (20) مهارة (وفقًا لـ ASKILL-M002). بالنسبة للموصلات، الحد الأقصى هو 10 لكل حزمة.

هل يمكن للمهارات الرجوع إلى أدوات الموصل من نفس الحزمة؟

نعم، ويجب عليهم ذلك. قم بتسمية الأدوات بشكل واضح في سير العمل SKILL.md (على سبيل المثال، "استخدم الأداة search_case_law ل..."). يقوم الوكيل بتوصيلها في وقت التشغيل.

هل يمكن لأدوات المكون الإضافي قبول الملفات من مساحة عمل Cowork؟

Yes. أعلن عن معلمة الأداة باستخدام contentEncoding: base64، ويقوم Cowork بحل ملف مساحة عمل المستخدم لمحتوى base64 قبل استدعاء الخادم. يمرر النموذج مسارات الملفات، وليس محتوى الملف، بحيث لا تستهلك الملفات الكبيرة سياق النموذج. للحصول على تفاصيل البيان وحدوده، تعرف على المزيد في قبول الملفات من مساحة عمل Cowork.

كيف أعمل إنشاء معرف فريد عمومي حتمي لحزمتي؟

wiqd plugin create ينشئ ويثبّت معرف التطبيق نيابة عنك. يستخدم البرنامج النصي للتحويل UUID v5 (استنادا إلى SHA-1) من اسم المكون الإضافي، لذا فإن تشغيل التحويل مرتين ينتج عن نفس GUID. للحزم اليدوي، استخدم أي مولد GUID. تأكد من إبقائها مستقرة عبر الإصدارات.

أي إصدار من البيان يجب أن أستهدفه؟

استهدف الإصدار 1.29 إذا كنت تقوم بالإنشاء باستخدام wiqd، الذي يثبّت الإصدار لك. في الإصدار 1.29، تكون الإدخالات agentConnectors[] على عنوان URL فقط، ويكون mcpToolDescription اختياريًا. تستخدم الأمثلة المكتوبة يدويًا في هذه المقالة الإصدار 1.28، وعندما يكون mcpToolDescription مطلوبًا، يجب أن يكون الملف الذي يحدده داخل ملف ZIP. atk import openplugin يستخدم UUID v5 (استنادا إلى SHA-1) من اسم المكون الإضافي. يؤدي تشغيل الاستيراد مرتين إلى الحصول على نفس GUID. لتعيين الاشتراك الخاص بك، مرّر --app-id. للتغليف اليدوي ، استخدم أي مولد GUID. تأكد من إبقائها مستقرة عبر الإصدارات.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

تاريخ آخر تحديث في 2026-10-22

أنشئ مكونات إضافية لـ Copilot Cowork

ما ستقوم بإنشاءه

اختر نقطة البداية

أنشئ مكونًا إضافيًا باستخدام wiqd

الخطوة 1: تثبيت wiqd وتسجيل الدخول

الخطوة 2: سقالة المكون الإضافي وإضافة القدرات

الخطوة 3: التحقق أثناء الإنشاء

الخطوة 4: التزويد والحزم والمشاركة

خذ مكونًا إضافيًا إلى مضيف آخر

استيراد مكون إضافي موجود

الاستيراد باستخدام wiqd

حوّل باستخدام البرنامج النصي للتحويل

ما يتم استيراده

الأمور التي لم يتم تحويلها

خيارات الاستيراد

الرجوع بالتصدير إلى دليل مكون إضافي

إصدار قديم: برنامج نصي لتحويل PowerShell

جمّع حزمة يدويًا

الخطوة 1: إنشاء مهارتك الأولى

حقول frontmatter في SKILL.md

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

حدود الملفات المصاحبة

قواعد الملف المصاحب

الخطوة 3: إضافة موصل (اختياري)

متطلبات الموصل

إرشادات تصميم الأداة

صِف أدوات أداة الربط الخاصة بك (mcpToolDescription)

أنواع المصادقة المعتمدة

مصادقة MCP

تسجيل العميل الديناميكي

الخطوة 4: إنشاء الملف التعريفي

الخطوة 5: إضافة أيقونات

الخطوة 6: التغليف

الخطوة 7: اختبر

الخطوة 8: النشر إلى التينانت

الخطوة 9: النشر للعامة

اختبر موصّلًا باستخدام خادم MCP محلي

Troubleshooting

أنماط التعبئة والتغليف

المهارات فقط (بدون الموصل)

المهارات + موصل الاتصال عن بُعد

أداة الربط فقط (بدون مهارات مخصصة)

Claude Code المستورد أو المكون الإضافي لـ Cursor

أفضل ممارسات تأليف المهارات

اكتب أوصافًا فعّالة

اكتب سير عمل فعال

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

قواعد التحقق من الصحة

التحقق من صحة على مستوى البيان

التحقق من الصحة على مستوى الحزمة

التحقق من صحة المُوصِّل

التحقق من صحة الملف المصاحب

التوافق عبر الأنظمة الأساسية

إدارة التعليقات التوضيحية والتأكيد في MCP

الحقول المتوفرة

قواعد التحقق

أمثلة MCP

ما المتوفر الآن

قبول الملفات من مساحة عمل Cowork

تعريف معلمة ملف

ما يراه الوكيل

معلمات الملفات المتداخلة

ما يتلقاه الخادم الخاص بك

Limits

التوصيات

تحديد حركة مرور Cowork إلى الخادم

المطابقة حسب البادئة copilot-cowork

اختر القناة المناسبة لبوابتك

ما تتضمنه الهوية وما لا تتضمنه

الأسئلة الشائعة

المحتوى ذو الصلة

الملاحظات

الموارد الإضافية

صِف أدوات أداة الربط الخاصة بك (`mcpToolDescription`)

المطابقة حسب البادئة `copilot-cowork`