NeboAI
NeboAI
ابدأ الآن

مرجع SKILL.md

تسرد هذه الصفحة كل جزء من المهارة يقرؤه Nebo: حقول المقدمة، والمتغيرات التي يوسّعها، والأدوات التي يستخدمها الموظفون للعمل مع المهارات، والبيئة التي تعمل فيها السكربتات.

صيغة الملف

SKILL.md نص بترميز UTF-8. يبدأ بسطر من ثلاث شرطات، ثم مقدمة YAML، ثم سطر إغلاق من ثلاث شرطات. وكل ما بعد ذلك هو المتن: تعليمات Markdown يتلقاها الموظف عند تحميل المهارة. يعثر Nebo على الملف باسمه دون مراعاة حالة الأحرف.

---
name: expense-review
description: Check submitted expenses against the company policy and flag anything that needs a receipt or an approval. Use when someone asks to review expenses or a reimbursement request.
version: "1.2.0"
author: Example Co
license: MIT
tags: [finance, expenses]
triggers: [reimbursement, expense report]
platform: [macos, linux, windows]
capabilities: [network]
metadata:
  allowed_domains: [api.example.com]
  secrets:
    - key: EXAMPLE_API_KEY
      label: Example API key
      hint: Create one at https://example.com/settings/keys
      required: true
requires:
  - name: receipt-capture
    version: ">=1.0.0"
plugins:
  - name: example-ledger
    version: ">=2.0.0"
    optional: true
---

# Expense review

Follow the policy in references/policy.md ...

حقول المقدمة

الحقلان name وdescription وحدهما مطلوبان. الحقل ذو النوع الخاطئ يُفشل الملف كله، فلا تُحمَّل المهارة. وتُتجاهل المفاتيح غير المدرجة هنا.

الحقلالنوعالقيمة الافتراضيةالمعنى
namestringمطلوبالمعرّف. [a-z0-9-]، دون شرطة في البداية أو النهاية أو شرطتين متتاليتين، وبحد أقصى 64 بايت. يطابق اسم المجلد.
descriptionstringمطلوبما تفعله المهارة ومتى تُستخدم. بحد أقصى 1,024 بايت. يظهر في قائمة مهارات الموظف ويقيّمه find_skills.
versionstring"1.0.0"إصدار دلالي. تتحقق منه نطاقات requires في المهارات الأخرى. ضعه بين علامتي اقتباس.
triggersقائمة نصوص[]كلمات وعبارات تصف متى تنطبق المهارة. يظهر ما يصل إلى ثلاث منها في قائمة المهارات، وتُحتسب كلها في find_skills. ولا تحمّل أي مهارة بمفردها أبدًا.
platformقائمة نصوصالكلmacos، linux، windows. لا تُحمَّل المهارة إلا حيث يتطابق أحدها.
capabilitiesقائمة نصوص[]network وstorage يوسّعان بيئة السكربتات المعزولة. انظر بيئة السكربتات المعزولة.
metadatamap{}يحتوي على secrets وallowed_domains. انظر أدناه.
requiresقائمة من {name, version}[]مهارات أخرى تبني عليها هذه المهارة. name هو الاسم القصير للمهارة، وversion نطاق semver، وقيمته الافتراضية "*".
pluginsقائمة من {name, version, optional}[]الإضافات التي تستخدمها هذه المهارة. القيمة الافتراضية لـ version هي "*"، ولـ optional هي false.
dependenciesقائمة نصوص[]الأسماء القصيرة للمهارات التي يجب أن تكون موجودة.
priorityinteger0يرتّب المهارات في قوائم الإدارة. ولا يؤثر في المهارة التي يختارها الموظف.
authorstring""يُخزَّن للعرض.
licensestring""يُخزَّن للعرض.
compatibilitystring""ملاحظة نصية حرة، بحد أقصى 500 بايت.
tagsقائمة نصوص[]يُخزَّن للعرض.
allowed-toolsstring""نص مفصول بمسافات. يُخزَّن ولا يُفرض.

عندما تكون مهارة مذكورة في requires أو dependencies مفقودة أو خارج النطاق، أو عندما لا تكون إضافة مطلوبة مثبّتة، تُحمَّل المهارة مع ذلك وتُعلَّم بأنها متراجعة. ويرى المالك ما الذي ينقص.

الأسرار

صرّح ببيانات الاعتماد التي تحتاج إليها سكربتات المهارة تحت metadata.secrets. يوفّر المالك القيم، ويخزّنها Nebo مشفّرة لتلك المهارة.

metadata:
  secrets:
    - key: EXAMPLE_API_KEY
      label: Example API key
      hint: Create one at https://example.com/settings/keys
      required: true
المفتاحالمعنى
keyاسم متغير البيئة الذي يستلمه السكربت. مطلوب.
labelالاسم الذي يُعرض على المالك.
hintمن أين تُحصل القيمة.
requiredعندما يكون true، يرفض execute تشغيل سكربتات المهارة حتى تُضبط القيمة. القيمة الافتراضية false.

يضبط الموظف قيمة باستخدام configure_skill. يمكنك الإشارة إلى سر في النص بالصيغة ${secret.KEY}، لكن ينبغي أن تقرأ النصوص البرمجية متغير البيئة بدلًا من ذلك.

متغيرات القوالب

يستبدل Nebo هذه المتغيرات في المتن عندما يحمّل موظف المهارة. ولا تُستبدل داخل الملفات الأخرى، فالسكربتات تقرأ متغيرات البيئة بدلًا من ذلك.

المتغيرالقيمة
${NEBO_SKILL_DIR}المسار المطلق لمجلد المهارة.
${NEBO_DATA_DIR}مجلد قابل للكتابة لهذه المهارة: <data>/appdata/skills/<name>. يُنشأ عند أول استخدام.
${NEBO_USER_NAME}اسم المالك.
${NEBO_OS}نظام التشغيل.
${NEBO_ARCH}بنية المعالج.
${plugin.SLUG_BIN}مسار الملف التنفيذي لإضافة مصرّح بها. يُكتب الاسم المختصر بأحرف كبيرة، مع تحويل الشرطات إلى شرطات سفلية: يصبح example-ledger هو ${plugin.EXAMPLE_LEDGER_BIN}.
${secret.KEY}قيمة سرّ مصرّح به.
$ARGUMENTSقيمة args الممرّرة إلى use_skill. وعندما لا يحتوي المتن على $ARGUMENTS، تُلحق الوسائط بعده.

أدوات المهارات

يعمل الموظفون مع المهارات عبر هذه الأدوات. use_skill متاحة دائمًا، والأخرى تُحمَّل عندما يحتاج إليها الموظف.

الأداةالمعاملاتما تفعله
use_skillname, argsتحمّل مهارة. تعيد المتن الموسَّع، ومسار المجلد، وأول 20 اسم ملف. وتعيد تفعيل المهارة المعطّلة.
find_skillsqueryتعيد ما يصل إلى 10 مهارات مرتبة حسب تطابق الاسم والمُشغِّل والوصف.
read_skill_filename, pathتقرأ ملفًا في مجلد المهارة. ومن دون path، تسرد الملفات وأحجامها.
save_skillname, contentتكتب ملف SKILL.md كاملًا في مجلد مهارات المستخدم. ولا يمكن الكتابة فوق مهارات المتجر.
delete_skillnameتحذف مهارة مستخدم.
install_skillcodeتثبّت مهارة من المتجر عبر رمز تثبيتها SKIL-.
configure_skillname, key, valueتضبط سرًّا. ومن دون key، تعرض ما تحتاج إليه المهارة.
rate_skillname, rating, reviewتقيّم مهارة في المتجر من 1 إلى 5.
read_skill_reviewsnameتقرأ مراجعات مهارة في المتجر.
executeskill, script, args, timeoutتشغّل سكربتًا من مجلد مهارة. انظر بيئة السكربتات المعزولة.

بيئة السكربتات المعزولة

تشغّل الأداة execute سكربتًا واحدًا من مجلد مهارة. وتختار بيئة التشغيل بناءً على الملف.

السكربتبيئة التشغيل
.pyPython، عبر uv المضمّن في Nebo عند وجوده، وإلا python3.
.ts, .jsBun المضمّن في Nebo عند وجوده، وإلا node.
bin/<file> أو binaryيُشغَّل مباشرة.
.shغير مدعوم.

يبدأ كل تشغيل ببيئة فارغة مع هذه المتغيرات:

المتغيرالقيمة
SKILL_ARGSكائن args بصيغة JSON.
كل key لسرّقيمة السرّ بعد فك تشفيرها.
<PLUGIN>_BINمسار الملف التنفيذي لكل إضافة مصرّح بها. وتُضاف مجلدات الإضافات أيضًا إلى PATH.
import json, os

args = json.loads(os.environ.get("SKILL_ARGS", "{}"))
api_key = os.environ["EXAMPLE_API_KEY"]
print(json.dumps({"checked": len(args.get("items", []))}))

يعمل السكربت في نسخة مؤقتة من مجلد المهارة، بمهلة افتراضية قدرها 30 ثانية. وعلى macOS وLinux يعمل في بيئة معزولة على مستوى نظام التشغيل:

  • لا يستطيع قراءة مخازن بيانات الاعتماد، ولا بيانات المتصفح وسلسلة المفاتيح، ولا إعدادات Nebo وقاعدة بياناته.
  • لا يستطيع الكتابة إلا في مجلد عمله وفي /tmp/nebo. وتضيف القدرة storage مجلد بيانات Nebo.
  • لا يملك وصولًا إلى الشبكة. وتسمح القدرة network بسجلات الحزم والنطاقات المدرجة في metadata.allowed_domains.

الملفات والحدود

العنصرالقاعدة
المواردكل ملف باستثناء SKILL.md وmanifest.json وsignatures.json والملفات التي تبدأ بنقطة.
الملفات التنفيذيةالملفات تحت scripts/ أو bin/، وملف في الجذر باسم binary.
المساراتنسبةً إلى مجلد المهارة. تُرفض المسارات التي تحتوي على .. أو التي تخرج من المجلد.
مهارة معطّلةمجلد فيه SKILL.md.disabled بدلًا من SKILL.md.
قائمة المهاراتيُقتطع كل إدخال عند 250 حرفًا. وعندما تتجاوز القائمة كلها 8,000 حرف، تُختصر المهارات المشتركة أولًا، وتحتفظ مهارات الموظف الخاصة بإدخالاتها كاملة.

حدود الملفات التي تنشرها في المتجر موجودة في صفحة النشر.