API مهارات كلود يصل للإصدار العام: أبرز التغييرات وكيفية الاستخدام

واجهة برمجة تطبيقات Claude Skills متاحة بشكل عام اعتبارًا من 20 أغسطس 2026. يمكنك الآن إنشاء المهارات المخصصة وإصدارها وإدارتها عبر https://api.anthropic.com/v1/skills باستخدام رؤوس HTTP قياسية، دون الحاجة إلى علامة تجريبية، وتشغيلها داخل بيئة Claude's code sandbox دون الحاجة إلى استضافة أي شيء بنفسك. أطلقت Anthropic هذا الإصدار العام (GA) في دفعة واحدة مع ميزة "استخدام الكمبيوتر" (computer use)، وأداة المتصفح الجديدة، وواجهة برمجة تطبيقات الملفات (Files API)، وتم تأطيرها في الإعلان كحزمة الإنتاج لبناء العملاء (agents) على منصة Claude.

إذا كان مفهوم المهارات جديدًا بالنسبة لك، فإن دليلنا لمهارات Claude يغطي الفكرة من الألف إلى الياء. تتناول هذه المقالة طبقة واجهة برمجة التطبيقات: نقاط النهاية، ونموذج الإصدارات، وشكل الطلب الذي يحمل المهارات إلى مكالمة الرسائل (Messages call)، والجوانب الصعبة (تحديد نطاق مساحة العمل، وإصدار اللقطات) التي لم يتم تليينها في الإصدار العام. بما أن كل هذا يعتمد على HTTP عادي، يمكن بناء كل مكالمة هنا واختبار الانحدار لها في Apidog بينما تتابع.

زر

مراجعة سريعة في 30 ثانية: ما هي المهارة؟

المهارة هي مجلد. في مستواه العلوي يوجد ملف SKILL.md مع بيانات وصفية YAML (frontmatter) تحمل name و description؛ وحوله توضع أي نصوص برمجية وقوالب وملفات مرجعية تحتاجها المهمة. عندما يتضمن الطلب المهارة، يقوم Claude بتحميل التعليمات فقط عندما تتطلب المهمة ذلك، وينفذ أي نصوص برمجية مجمعة في بيئة التعليمات البرمجية المعزولة (sandboxed) الخاصة به.

تحتوي البيانات الوصفية (frontmatter) على قواعد تحقق حقيقية:

name: 64 حرفًا كحد أقصى، أحرف صغيرة وأرقام وواصلات فقط. لا توجد علامات XML، ويتم رفض الكلمات المحجوزة "anthropic" و "claude".
description: غير فارغة، 1024 حرفًا كحد أقصى.
يمكن أن يكون display_name اختياريًا (حتى 255 حرفًا) سهل الاستخدام البشري.
يجب أن يظل حجم التحميل الكلي أقل من 30 ميغابايت غير مضغوط.

تأتي المهارات من مصدرين. المهارات التي تديرها Anthropic (type: "anthropic") تأتي مبنية مسبقًا بمعرفات قصيرة مثل pptx و xlsx و docx و pdf، وتستخدم إصدارات تعتمد على التاريخ مثل 20251013. المهارات المخصصة (type: "custom") هي ملكك: يتم تحميلها عبر واجهة برمجة التطبيقات، وهي خاصة بمساحة عملك، ولها معرفات تم إنشاؤها مثل skill_01AbCdEfGhIjKlMnOpQrStUv.

ما الذي تغير بالفعل في الإصدار العام (GA)

ثلاثة أشياء جديدة أو تم تثبيتها اعتبارًا من 20 أغسطس 2026:

لا يوجد رأس بيتا (beta header). تعمل واجهة برمجة تطبيقات المهارات على واجهة برمجة تطبيقات Claude باستخدام x-api-key و anthropic-version: 2023-06-01 فقط.
سير عمل أبسط للتحميل والإصدار. تصف Anthropic الإصدار العام (GA) بأنه يجلب "واجهة برمجة تطبيقات أبسط لتحميل وتدوين إصدارات" المهارات المخصصة. الإصدارات هي موارد من الدرجة الأولى ولها نقاط نهاية خاصة بها.
المزيد من المنصات. واجهة برمجة تطبيقات المهارات متاحة عبر Microsoft Foundry بالإضافة إلى واجهة برمجة تطبيقات Claude. يتم تنفيذ المهارات في بيئة Claude المعزولة (sandbox) المُدارة، لذلك لا توجد بنية تحتية من جانبك.

بقية موجة الإصدار العام مهمة لمستخدمي المهارات أيضًا: غالبًا ما تُنشئ المهارات ملفات (عرض تقديمي، جدول بيانات مملوء)، وتعود تلك المخرجات عبر واجهة برمجة تطبيقات الملفات (Files API) التي تم إطلاقها في الإصدار العام مؤخرًا.

سطح نقاط النهاية

كل شيء يقع تحت /v1/skills:

العملية	نقطة النهاية
إنشاء مهارة	`POST /v1/skills`
سرد المهارات	`GET /v1/skills`
استرداد مهارة	`GET /v1/skills/{skill_id}`
حذف مهارة	`DELETE /v1/skills/{skill_id}`
إنشاء إصدار جديد	`POST /v1/skills/{skill_id}/versions`
سرد الإصدارات	`GET /v1/skills/{skill_id}/versions`

يؤدي إنشاء مهارة إلى تحميل مجموعة ملفاتها الكاملة؛ ويؤدي إنشاء إصدار إلى نفس الشيء مقابل معرف مهارة موجود. في مشروع Apidog، يتوافق هذا بوضوح مع مجلد واحد من ستة طلبات محفوظة مع {{skill_id}} و {{skill_version}} كمتغيرات بيئة، لذا فإن ترويج إصدار جديد عبر بيئات التطوير والإنتاج هو تغيير متغير، وليس تعديل طلب.

تحميل مهارة مخصصة

تتكون المهارة المخصصة الدنيا من شيئين: المجلد واستدعاء التحميل. لنفترض أنك تحتفظ بمهارة تقرير العلامة التجارية (brand-report) في مستودعك:

brand-report/
  SKILL.md
  templates/report.html
  scripts/build_report.py

مع بدء ملف SKILL.md بهذا الشكل:

---
name: brand-report
description: Generates the weekly brand performance report as a formatted HTML document from a CSV of metrics. Use when asked for a brand report, weekly summary deck, or performance writeup.
---

قم بتحميلها عن طريق إرسال الملفات كبيانات نموذج متعددة الأجزاء (multipart form data):

curl -X POST https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F 'files[]=@brand-report/SKILL.md;filename=brand-report/SKILL.md' \
  -F 'files[]=@brand-report/templates/report.html;filename=brand-report/templates/report.html' \
  -F 'files[]=@brand-report/scripts/build_report.py;filename=brand-report/scripts/build_report.py'

تعيد الاستجابة skill_id الذي تم إنشاؤه ومعرف skver_* للإصدار الأول. قم بتخزين كليهما؛ يذهب معرف المهارة في طلبات Messages الخاصة بك، ومعرف الإصدار هو نقطة الارتداد الخاصة بك. تحقق من أسماء حقول multipart الدقيقة مقابل مرجع واجهة برمجة تطبيقات المهارات لإصدار SDK الخاص بك، حيث تقوم مساعدات SDK المكتوبة بتغليف هذا الاستدعاء في معظم اللغات.

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

استخدام مهارة في طلب الرسائل (Messages request)

لا ترتبط المهارات بطلب من تلقاء نفسها. بل تعتمد على أداة تنفيذ التعليمات البرمجية، المُعلَن عنها من خلال المعامل container:

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Build the Q3 revenue deck from the attached numbers"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

القواعد التي تحكم هذه الكتلة:

يجب تمكين أداة تنفيذ التعليمات البرمجية في tools، حيث يتم تنفيذ المهارات داخل بيئة الاختبار المعزولة هذه. يتبع دعم النماذج قائمة توافق أداة تنفيذ التعليمات البرمجية.
ما يصل إلى 20 مهارة لكل طلب. يقرأ Claude وصف كل مهارة ويحمل التعليمات فقط لتلك التي تتطلبها المهمة.
تثبيت الإصدارات تحت سيطرتك. "latest" يشير إلى أحدث إصدار؛ بينما يؤدي تثبيت معرف skver_* (أو إصدار تاريخي لمهارات Anthropic) إلى تجميد السلوك. ثبت في بيئة الإنتاج، واجعلها متحركة في بيئة التطوير.

عندما تنتج مهارة مستندًا، تحتوي الاستجابة على file_id تقوم بتنزيله عبر GET /v1/files/{file_id}/content الخاص بواجهة برمجة تطبيقات الملفات (Files API). هذا التفاعل ثنائي واجهة برمجة التطبيقات (المهارات للإنشاء، الملفات للاسترداد) هو حلقة الإنتاج الأساسية.

إدارة الإصدارات: لقطات، وليست فروقات

نموذج إدارة الإصدارات هو الجزء الذي تخطئ فيه معظم الفرق في المحاولة الأولى. الإصدار الجديد هو لقطة كاملة، وليس فرقًا (delta). عندما تقوم بـ POST /v1/skills/{skill_id}/versions، تقوم بتحميل مجموعة ملفات المهارة بالكامل مرة أخرى؛ الملفات التي تحذفها لا يتم ترحيلها من الإصدار السابق. يجب أن يتطابق name في ملف SKILL.md للإصدار الجديد أيضًا مع الاسم الحالي للمهارة.

تعامل مع مجلدات المهارات كقطع أثرية للبناء (build artifacts): احتفظ بمصدر الحقيقة في مستودعك، وقم بتغليف المجلد بأكمله في CI، وادفعه كإصدار جديد. يكون التراجع (rollback) بعد ذلك أمرًا بسيطًا، حيث تظل الإصدارات القديمة قابلة للوصول بواسطة معرفاتها skver_* ويتم إصلاح حادث إنتاجي عن طريق إعادة تثبيت سلسلة واحدة.

تحديد نطاق مساحة العمل: فخ بيئات المستأجرين المتعددين

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

الحل هو نفسه بالنسبة لواجهة برمجة تطبيقات الملفات (Files API): أنشئ مساحة عمل منفصلة لكل مستأجر. مساحة العمل هي حد العزل، وتحصل كل مؤسسة على ما يصل إلى 100 مساحة عمل قبل الحاجة إلى التحدث إلى فريق الحسابات. ترث المفاتيح والملفات والمهارات جميعها هذا الحد، لذا فإن قرارًا واحدًا يعزل الثلاثة.

المهارات طويلة الأمد: pause_turn وإعادة استخدام الحاوية

يمكن أن تتجاوز عمليات تنفيذ المهارات دورة نموذج واحدة. يتعامل معها آليتان:

pause_turn: عندما تتوقف استجابة مع stop_reason: "pause_turn"، قم بإلحاق محتوى المساعد بسجل رسائلك واستدعِ مرة أخرى، مع تمرير نفس container.id. تستأنف البيئة المعزولة (sandbox) العمل من حيث توقفت.
إعادة استخدام الحاوية: يقبل الكائن container معرفًا (id) من استجابة سابقة، مما يحافظ على الملفات والحالة المثبتة حية عبر محادثة متعددة الأدوار. هذا يعني أن المهارة يمكنها بناء جدول بيانات في الدور الأول ومراجعته في الدور الثالث دون إعادة الإنشاء من الصفر.

كلا النمطين عبارة عن تسلسلات HTTP ذات حالة، مما يجعل اختبارها يدويًا صعبًا وممتعًا كسيناريو في Apidog: يؤكد الطلب الأول على stop_reason، يقوم نص برمجي برفع container.id إلى متغير، يعيد الطلب الثاني استخدامه، وتؤكد الخطوة الأخيرة أن file_id الذي تم إنشاؤه يتم تنزيله بشكل نظيف. يقوم Apidog CLI بتشغيل نفس السيناريو في CI، لذا فإن زيادة إصدار المهارة لا يمكن أن تكسر مسار عملك بصمت. إذا كنت ترغب في رؤية كيفية تصرف المهارات داخل نظام بيئي آخر لمقارنتها، فقد قمنا بتحليل مهارة Claude الخاصة بـ Postman في مراجعة سابقة.

أين تعمل

في الإصدار العام (GA)، تتوفر واجهة برمجة تطبيقات المهارات على واجهة برمجة تطبيقات Claude وعبر Microsoft Foundry. تُنفّذ المهارات في بيئة Anthropic المعزولة (sandbox) بغض النظر عن ذلك، لذا فإن "النشر" هو مجرد تحميل، ولا يوجد صورة حاوية (container image)، ولا ترقيع وقت التشغيل (runtime patching)، ولا مقبض توسيع (scaling knob) من جانبك. لاحظ الاعتماد على النموذج بدلاً من المنصة: يجب أن يستخدم الطلب نموذجًا تدعمه أداة تنفيذ التعليمات البرمجية، مثل claude-opus-5 في الأمثلة أعلاه. يغطي دليل واجهة برمجة تطبيقات Claude Opus 5 أساسيات طلب هذا النموذج إذا كنت تبدأ من جديد.

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

هل ما زلت بحاجة إلى رأس بيتا (beta header) للمهارات؟ لا. اعتبارًا من 20 أغسطس 2026، تعمل /v1/skills ومعامل container.skills مع الرؤوس القياسية في واجهة برمجة تطبيقات Claude. أزل أي علامات بيتا مثبتة عند ترقية SDK الخاص بك.

هل يمكن للمهارة استدعاء واجهات برمجة تطبيقات خارجية أثناء تشغيلها؟ تُنفّذ المهارات داخل بيئة Claude المعزولة (code sandbox) مع قيود الشبكة الخاصة بأداة تنفيذ التعليمات البرمجية. قم بتضمين ما تحتاجه المهارة في مجلدها بدلاً من افتراض خروج مفتوح، واحتفظ بمنطق استدعاء واجهة برمجة التطبيقات في طبقة تطبيقك حيث يمكنك اختباره بشكل صحيح.

كم عدد المهارات التي يمكن لطلب واحد تحميلها؟ ما يصل إلى 20 مهارة. يقرأ Claude وصف كل مهارة من البيانات الوصفية (frontmatter) ليقرر أي منها تحتاجه المهمة، لذا فإن الأوصاف تحمل أهمية كبيرة: اكتبها كقواعد توجيه، وليس كنص تسويقي.

ما الفرق بين هذه المهارات ومهارات Claude Code؟ نفس المفهوم، بيئة تشغيل مختلفة. يكتشف Claude Code مجلدات المهارات على نظام ملفاتك؛ بينما تستضيف واجهة برمجة تطبيقات المهارات هذه المجلدات على الخادم، مع إدارة الإصدارات، لاستدعاءات Messages API. يتم مشاركة تنسيق المجلد مع البيانات الوصفية (frontmatter) لـ SKILL.md، لذا فإن المهارة التي كتبتها لـ Claude Code عادةً ما تُنقل بتغيير قليل.

خلاصة

يحول الإصدار العام (GA) المهارات من تجربة إلى سطح تشغيلي: ست نقاط نهاية، وإصدار لقطة (snapshot versioning)، وعزل مساحة العمل، وتسليم نظيف إلى واجهة برمجة تطبيقات الملفات (Files API) للمخرجات. تتعامل الفرق التي تحصل على القيمة الأسرع مع المهارات كأي قطعة أثرية أخرى قابلة للنشر، مما يعني التغليف في CI، والإصدارات المثبتة في الإنتاج، والاختبارات الآلية حول دورة حياة الحاوية. صمم نقاط النهاية الست في Apidog، واربط ترقية الإصدار بسيناريو اختبار، وستعرف أن إصدار مهارة سيء قد عطل مُنشئ العروض التقديمية الخاص بك قبل أن يكتشف المستخدمون ذلك. حمل Apidog مجانًا وابنِ الحزمة في فترة ما بعد الظهر.