قالب فایل
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-]، بدون خط تیره در ابتدا، انتها یا خط تیره دوتایی، حداکثر ۶۴ بایت. با نام پوشه یکی باشد. |
description | string | الزامی | مهارت چه میکند و کی باید از آن استفاده کرد. حداکثر ۱٬۰۲۴ بایت. در فهرست مهارتهای کارمند نمایش داده میشود و 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 | "" | یادداشت آزاد، حداکثر ۵۰۰ بایت. |
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} | مسیر فایل اجرایی یک افزونه اعلامشده. slug با حروف بزرگ و با زیرخط به جای خط تیره نوشته میشود: example-ledger به ${plugin.EXAMPLE_LEDGER_BIN} تبدیل میشود. |
${secret.KEY} | مقدار یک راز اعلامشده. |
$ARGUMENTS | args ارسالشده به use_skill. وقتی بدنه $ARGUMENTS ندارد، آرگومانها پس از آن افزوده میشوند. |
ابزارهای مهارت
کارمندان از طریق این ابزارها با مهارتها کار میکنند. use_skill همیشه در دسترس است؛ بقیه وقتی کارمند به آنها نیاز دارد بارگذاری میشوند.
| ابزار | پارامترها | کاربرد |
|---|---|---|
use_skill | name, args | یک مهارت را بارگذاری میکند. بدنه گسترشیافته، مسیر پوشه و ۲۰ نام فایل نخست را برمیگرداند. یک مهارت غیرفعال را دوباره فعال میکند. |
find_skills | query | حداکثر ۱۰ مهارت را بر اساس تطابق نام، تریگر و توضیح رتبهبندیشده برمیگرداند. |
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 | به یک مهارت فروشگاه از ۱ تا ۵ امتیاز میدهد. |
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", []))})) اسکریپت در یک نسخه موقت از پوشه مهارت اجرا میشود، با زمان انتظار پیشفرض ۳۰ ثانیه. در macOS و Linux در یک محیط ایزوله سیستمعامل اجرا میشود:
- نمیتواند مخازن اطلاعات ورود، دادههای مرورگر و keychain، یا تنظیمات و پایگاه داده خود Nebo را بخواند.
- فقط میتواند در پوشه کاری خودش و
/tmp/neboبنویسد. قابلیتstorageپوشه داده Nebo را اضافه میکند. - به شبکه دسترسی ندارد. قابلیت
networkدسترسی به مخازن بستهها و دامنههای فهرستشده درmetadata.allowed_domainsرا مجاز میکند.
فایلها و محدودیتها
| مورد | قاعده |
|---|---|
| منابع | همه فایلها به جز SKILL.md، manifest.json، signatures.json و فایلهای نقطهدار. |
| فایلهای اجرایی | فایلهای زیر scripts/ یا bin/، و یک فایل ریشه به نام binary. |
| مسیرها | نسبت به پوشه مهارت. مسیرهایی که .. دارند یا از پوشه بیرون میروند رد میشوند. |
| مهارت غیرفعال | پوشهای با SKILL.md.disabled به جای SKILL.md. |
| فهرست مهارتها | هر ورودی در ۲۵۰ نویسه بریده میشود. وقتی کل فهرست از ۸٬۰۰۰ نویسه بیشتر شود، ابتدا مهارتهای مشترک کوتاه میشوند؛ مهارتهای خود کارمند ورودی کاملشان را نگه میدارند. |
محدودیتهای فایلهایی که در فروشگاه منتشر میکنید در صفحه انتشار آمده است.