المهارات

المهارات هي حزم قدرات مدعومة بالملفات، يتم اكتشافها عند بدء التشغيل وعرضها على النموذج بوصفها:

بيانات وصفية خفيفة الوزن في موجه النظام (الاسم + الوصف)
محتوى عند الطلب عبر read skill://...
أوامر تفاعلية اختيارية /skill:<name>

يتناول هذا المستند سلوك وقت التشغيل الحالي في src/extensibility/skills.ts وsrc/discovery/builtin.ts وsrc/internal-urls/skill-protocol.ts وsrc/discovery/agents-md.ts.

ما هي المهارة في قاعدة الشيفرة هذه

تُمثَّل المهارة المكتشفة على النحو التالي:

name
description
filePath (مسار SKILL.md)
baseDir (دليل المهارة)
بيانات وصفية للمصدر (provider، level، المسار)

يتطلب وقت التشغيل فقط name وpath للتحقق من الصحة. عملياً، تعتمد جودة المطابقة على أن يكون description ذا معنى.

التخطيط المطلوب وتوقعات SKILL.md

تخطيط الدليل

بالنسبة للاكتشاف القائم على الموفر (الموفرون الأصليون/Claude/Codex/Agents/plugin)، تُكتشف المهارات على مستوى واحد تحت skills/:

<skills-root>/<skill-name>/SKILL.md

لا يكتشف محملو الموفرين الأنماط المتداخلة مثل <skills-root>/group/<skill>/SKILL.md.

بالنسبة لـ skills.customDirectories، يستخدم الفحص نفس التخطيط غير المتكرر (*/SKILL.md).

Provider-discovered layout (non-recursive under skills/):

<root>/skills/
  ├─ postgres/
  │   └─ SKILL.md      ✅ discovered
  ├─ pdf/
  │   └─ SKILL.md      ✅ discovered
  └─ team/
      └─ internal/
          └─ SKILL.md  ❌ not discovered by provider loaders

Custom-directory scanning is also non-recursive, so nested paths are ignored unless you point `customDirectories` at that nested parent.

بيانات frontmatter الخاصة بـ `SKILL.md`

حقول frontmatter المدعومة في نوع المهارة:

name?: string
description?: string
globs?: string[]
alwaysApply?: boolean
تُحفظ المفاتيح الإضافية كبيانات وصفية غير معروفة

سلوك وقت التشغيل الحالي:

يُعيَّن name افتراضياً إلى اسم دليل المهارة
يُطلب description من أجل:
- اكتشاف مهارات موفر .xcsh الأصلي (requireDescription: true)
- عمليات فحص skills.customDirectories عبر scanSkillsFromDir في src/discovery/helpers.ts (غير متكررة)
يمكن للموفرين غير الأصليين تحميل المهارات دون وصف

خط أنابيب الاكتشاف

تُنفذ discoverSkills() في src/extensibility/skills.ts مرحلتين:

موفرو القدرات عبر loadCapability("skills")
الأدلة المخصصة عبر scanSkillsFromDir(..., { requireDescription: true }) (تعداد دليل بمستوى واحد)

إذا كان skills.enabled يساوي false، يُعيد الاكتشاف مهارات بدون عناصر.

موفرو المهارات المدمجون والأولوية

يُرتب الموفرون حسب الأولوية أولاً (الأعلى يفوز)، ثم ترتيب التسجيل عند التعادل.

موفرو المهارات المسجلون حالياً:

native (الأولوية 100) — مهارات المستخدم/المشروع .xcsh عبر src/discovery/builtin.ts
claude (الأولوية 80)
مجموعة الأولوية 70 (بترتيب التسجيل):
- claude-plugins
- agents
- codex

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

مبدلات المصدر والتصفية

تطبق discoverSkills() عناصر التحكم التالية:

مبدلات المصدر: enableCodexUser، enableClaudeUser، enableClaudeProject، enablePiUser، enablePiProject
مرشحات glob على اسم المهارة:
- ignoredSkills (استبعاد)
- includeSkills (قائمة السماح للتضمين؛ فارغة تعني تضمين الكل)

ترتيب التصفية هو:

المصدر مُمكَّن
غير مستبعد
مُدرج (إذا كانت قائمة التضمين موجودة)

بالنسبة للموفرين غير codex/claude/native (على سبيل المثال agents، claude-plugins)، يعود التمكين حالياً إلى: مُمكَّن إذا كان أي مبدل مصدر مدمج مُمكَّناً.

التعامل مع التصادمات والتكرار

إزالة تكرار القدرات تحتفظ بالفعل بأول مهارة لكل اسم (موفر الأولوية الأعلى)
تقوم extensibility/skills.ts بالإضافة إلى ذلك بـ:
- إزالة تكرار الملفات المتطابقة بواسطة realpath (آمن للروابط الرمزية)
- إصدار تحذيرات التصادم عندما يتعارض اسم مهارة لاحقة
- الاحتفاظ بواجهة برمجية مريحة discoverSkillsFromDir({ dir, source }) كمحوّل رفيع فوق scanSkillsFromDir
تُدمج مهارات الأدلة المخصصة بعد مهارات الموفر وتتبع نفس سلوك التصادم

سلوك الاستخدام في وقت التشغيل

التعرض في موجه النظام

يستخدم بناء موجه النظام (src/system-prompt.ts) المهارات المكتشفة على النحو التالي:

إذا كانت أداة read متاحة:
- تضمين قائمة المهارات المكتشفة في الموجه
وإلا:
- حذف القائمة المكتشفة

تتلقى الوكلاء الفرعية لأداة المهمة قائمة المهارات المكتشفة/المقدمة للجلسة عبر إنشاء الجلسة الاعتيادي؛ لا يوجد تثبيت مهارة لكل مهمة بصورة منفردة.

أوامر `/skill:<name>` التفاعلية

إذا كان skills.enableSkillCommands يساوي true، يُسجّل الوضع التفاعلي أمر شريطة واحداً لكل مهارة مكتشفة.

سلوك /skill:<name> [args]:

يقرأ ملف المهارة مباشرة من filePath
يُزيل frontmatter
يُحقن نص المهارة كرسالة مخصصة للمتابعة
يُضيف بيانات وصفية (Skill: <path>، User: <args> اختيارية)

سلوك رابط `skill://`

يدعم src/internal-urls/skill-protocol.ts:

skill://<name> ← يُحلَّل إلى SKILL.md لتلك المهارة
skill://<name>/<relative-path> ← يُحلَّل داخل دليل المهارة

skill:// URL resolution

skill://pdf
  -> <pdf-base>/SKILL.md

skill://pdf/references/tables.md
  -> <pdf-base>/references/tables.md

Guards:
- reject absolute paths
- reject `..` traversal
- reject any resolved path escaping <pdf-base>

تفاصيل الحل:

يجب أن يتطابق اسم المهارة تماماً
يتم فك ترميز URL للمسارات النسبية
تُرفض المسارات المطلقة
يُرفض اجتياز المسار (..)
يجب أن يظل المسار المحلول داخل baseDir
تُعيد الملفات المفقودة خطأ صريحاً File not found

نوع المحتوى:

.md ← text/markdown
كل شيء آخر ← text/plain

لا يُنفَّذ بحث احتياطي للأصول المفقودة.