صيغة الملف
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 وحدهما مطلوبان. الحقل ذو النوع الخاطئ يُفشل الملف كله، فلا تُحمَّل المهارة. وتُتجاهل المفاتيح غير المدرجة هنا.
| الحقل | النوع | القيمة الافتراضية | المعنى |
|---|---|---|---|
name | string | مطلوب | المعرّف. [a-z0-9-]، دون شرطة في البداية أو النهاية أو شرطتين متتاليتين، وبحد أقصى 64 بايت. يطابق اسم المجلد. |
description | string | مطلوب | ما تفعله المهارة ومتى تُستخدم. بحد أقصى 1,024 بايت. يظهر في قائمة مهارات الموظف ويقيّمه find_skills. |
version | string | "1.0.0" | إصدار دلالي. تتحقق منه نطاقات requires في المهارات الأخرى. ضعه بين علامتي اقتباس. |
triggers | قائمة نصوص | [] | كلمات وعبارات تصف متى تنطبق المهارة. يظهر ما يصل إلى ثلاث منها في قائمة المهارات، وتُحتسب كلها في find_skills. ولا تحمّل أي مهارة بمفردها أبدًا. |
platform | قائمة نصوص | الكل | macos، linux، windows. لا تُحمَّل المهارة إلا حيث يتطابق أحدها. |
capabilities | قائمة نصوص | [] | network وstorage يوسّعان بيئة السكربتات المعزولة. انظر بيئة السكربتات المعزولة. |
metadata | map | {} | يحتوي على secrets وallowed_domains. انظر أدناه. |
requires | قائمة من {name, version} | [] | مهارات أخرى تبني عليها هذه المهارة. name هو الاسم القصير للمهارة، وversion نطاق semver، وقيمته الافتراضية "*". |
plugins | قائمة من {name, version, optional} | [] | الإضافات التي تستخدمها هذه المهارة. القيمة الافتراضية لـ version هي "*"، ولـ optional هي false. |
dependencies | قائمة نصوص | [] | الأسماء القصيرة للمهارات التي يجب أن تكون موجودة. |
priority | integer | 0 | يرتّب المهارات في قوائم الإدارة. ولا يؤثر في المهارة التي يختارها الموظف. |
author | string | "" | يُخزَّن للعرض. |
license | string | "" | يُخزَّن للعرض. |
compatibility | string | "" | ملاحظة نصية حرة، بحد أقصى 500 بايت. |
tags | قائمة نصوص | [] | يُخزَّن للعرض. |
allowed-tools | string | "" | نص مفصول بمسافات. يُخزَّن ولا يُفرض. |
عندما تكون مهارة مذكورة في 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_skill | name, args | تحمّل مهارة. تعيد المتن الموسَّع، ومسار المجلد، وأول 20 اسم ملف. وتعيد تفعيل المهارة المعطّلة. |
find_skills | query | تعيد ما يصل إلى 10 مهارات مرتبة حسب تطابق الاسم والمُشغِّل والوصف. |
read_skill_file | name, path | تقرأ ملفًا في مجلد المهارة. ومن دون path، تسرد الملفات وأحجامها. |
save_skill | name, content | تكتب ملف SKILL.md كاملًا في مجلد مهارات المستخدم. ولا يمكن الكتابة فوق مهارات المتجر. |
delete_skill | name | تحذف مهارة مستخدم. |
install_skill | code | تثبّت مهارة من المتجر عبر رمز تثبيتها SKIL-. |
configure_skill | name, key, value | تضبط سرًّا. ومن دون key، تعرض ما تحتاج إليه المهارة. |
rate_skill | name, rating, review | تقيّم مهارة في المتجر من 1 إلى 5. |
read_skill_reviews | name | تقرأ مراجعات مهارة في المتجر. |
execute | skill, script, args, timeout | تشغّل سكربتًا من مجلد مهارة. انظر بيئة السكربتات المعزولة. |
بيئة السكربتات المعزولة
تشغّل الأداة execute سكربتًا واحدًا من مجلد مهارة. وتختار بيئة التشغيل بناءً على الملف.
| السكربت | بيئة التشغيل |
|---|---|
.py | Python، عبر uv المضمّن في Nebo عند وجوده، وإلا python3. |
.ts, .js | Bun المضمّن في 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 حرف، تُختصر المهارات المشتركة أولًا، وتحتفظ مهارات الموظف الخاصة بإدخالاتها كاملة. |
حدود الملفات التي تنشرها في المتجر موجودة في صفحة النشر.