توفّر Institflow [مهارة وكيل (Agent Skill)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) خاصّة بواجهة برمجة التطبيقات العامة الخاصّة بها — مجلّد صغير ومكتفٍ ذاتيًا يعلّم أيّ وكيل برمجي (Claude Code أو Cursor أو Codex أو أيّ أداة أخرى قادرة على قراءة ملفّ وتنفيذ طلبات HTTP) كلّ ما يحتاجه للتكامل الصحيح: المصادقة، مغلّف الأخطاء، مفاتيح عدم التكرار (Idempotency)، التصفّح بالمؤشّر (Pagination)، حدود المعدّل، التحقّق من توقيع الويب هوك، وأمثلة برمجية فعلية — دون أن يضطرّ الوكيل لاكتشاف كلّ ذلك بالتجربة والخطأ مقابل مستأجرك.

## مهارة Institflow للوكلاء (Agent Skill)

المهارة عبارة عن مجلّد، `institflow-api/`، يحتوي على ملفّ دخول واحد (`SKILL.md`) بالإضافة إلى مواد مرجعية يحمّلها الوكيل عند الحاجة فقط (فهرس كامل لنقاط النهاية مُولَّد من مواصفة الواجهة الحيّة، وتفاصيل الويب هوك والأخطاء، ومثالان قابلان للتشغيل — واحد بلغة TypeScript وآخر بلغة Python، كلاهما يستخدمان `fetch`/المكتبة القياسية فقط دون أيّ SDK). لا تُشجّع المهارة على أيّ نمط غير آمن أبدًا — لا مفاتيح في سلاسل الاستعلام، ومقارنة توقيع الويب هوك بزمن ثابت، ومفاتيح عدم تكرار على كل استدعاء يحرّك أموالًا.

[تنزيل institflow-api-skill.tar.gz](https://docs.institflow.com/downloads/institflow-api-skill.tar.gz) أو [institflow-api-skill.zip](https://docs.institflow.com/downloads/institflow-api-skill.zip) — المجلّد نفسه بصيغتين. يُستخرج ملف tar.gz مباشرةً إلى مجلّد المهارات بأمر واحد:

```bash
curl -fsSL https://docs.institflow.com/downloads/institflow-api-skill.tar.gz | tar -xz -C ~/.claude/skills
```

يترك هذا مجلّد `~/.claude/skills/institflow-api/` جاهزًا للاستخدام مباشرةً — دون خطوة فكّ ضغط منفصلة. يُعاد بناء كلتا الحزمتين من هذا الموقع كلّما تغيّرت مجموعة نقاط نهاية الواجهة، لذا أعِد تشغيل الأمر (أو أعِد تنزيل ملف zip) دوريًا بدل الاحتفاظ بنسخة خاصّة بك إلى أجل غير مسمّى.

> **تعمل بالفعل داخل هذا المستودع؟**
>
> تخطَّ التنزيل: يحتوي هذا المستودع على نسخة جاهزة للاستخدام في `.claude/skills/institflow-api` (مطابقة تمامًا لـ `skills/institflow-api/`، المصدر الأساسي الذي يُبنى منه كلا التنزيلين أعلاه، بواسطة المولّد نفسه) — يحمّلها Claude Code تلقائيًا، دون الحاجة إلى تنزيل أو فكّ ضغط.

## التثبيت في Claude Code

يكتشف Claude Code المهارات من مجلّد شخصي (متاح في كل مشروع) أو مجلّد خاصّ بالمشروع (يُضاف إلى المستودع ويُشارَك مع فريقك):

```bash
# شخصي — متاح في كل مشروع على هذا الجهاز
unzip institflow-api-skill.zip -d ~/.claude/skills/institflow-api

# خاصّ بالمشروع — يُضاف إلى هذا المستودع ويُشارَك مع فريقك
unzip institflow-api-skill.zip -d .claude/skills/institflow-api
```

يقرأ Claude Code ترويسة (frontmatter) كل مهارة (`name` و`description`) ليقرّر متى تكون ذات صلة — لست بحاجة للإشارة إليها بالاسم. اطلب منه "إنشاء طالب عبر واجهة Institflow" أو "التحقّق من توقيع هذا الويب هوك من Institflow" وستُحمَّل المهارة تلقائيًا.

## قواعد Cursor

لا يقرأ Cursor بعد صيغة Agent Skills مباشرةً — وجّهه إلى المحتوى نفسه كقاعدة مشروع بدلًا من ذلك: فُكّ ضغط المهارة داخل مستودعك (في أيّ مكان، مثل `docs/institflow-api/`) وأضف ملفّ `.cursor/rules/institflow-api.mdc` قصيرًا يشير إليه:

```plaintext
---
description: Institflow public API integration — auth, pagination, idempotency, webhooks
globs:
alwaysApply: false
---

When writing code that calls the Institflow API, follow docs/institflow-api/SKILL.md exactly —
especially its Idempotency, Pagination, and Gotchas sections. Endpoint details are in
docs/institflow-api/reference/endpoints.md.
```

## وكلاء أخرى

أيّ وكيل لا يستطيع تحميل مجلّد مهارة أصلًا يستفيد من المحتوى نفسه: الصق `SKILL.md` مباشرةً في موجّه النظام أو نافذة السياق الخاصّة به، أو وجّه أداة قادرة على جلب رابط إلى `llms.txt` أدناه، الذي يسرد كل دليل، ومواصفة الواجهة القابلة للقراءة الآلية، ورابط تنزيل المهارة في مكان واحد لهذا الغرض بالتحديد.

```plaintext
https://docs.institflow.com/llms.txt
https://docs.institflow.com/llms-full.txt
```

## أو الاتصال بخادم MCP مباشرةً

إذا كان وكيلك يعمل نيابةً عن شخص محدّد مسجّل الدخول (وليس بشكل غير مراقَب كخدمة) ويتحدّث بروتوكول Model Context Protocol، فإنّ الاتصال بـ `/mcp` غالبًا ما يكون خيارًا أنسب من واجهة REST التي تغطّيها هذه المهارة — إذ تحصر موافقة OAuth الجلسة بصلاحيات ذلك الشخص نفسه بالضبط، وتعود الإجراءات الهدّامة كمعاينة تأكيد بدل تنفيذها فورًا. راجع [دليل MCP و OAuth 2.1](https://docs.institflow.com/ar/mcp) لمعرفة رابط الاتصال، وتدفّق الاكتشاف، وفهرس الأدوات الكامل، وقسم "REST مقابل MCP" في هذه المهارة نفسها لمعرفة أيّهما تختار.

> **سطحان، ونموذج صلاحيات واحد**
>
> تستدعي REST (بمفتاح API) وMCP (برمز OAuth) نفس خدمات النطاق تمامًا وتحت نفس سجلّ الصلاحيات تمامًا — لا شيء ممكن عبر أحدهما لا يخضع لنفس القواعد عبر الآخر.