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-]، بدون خط تیره در ابتدا، انتها یا خط تیره دوتایی، حداکثر ۶۴ بایت. با نام پوشه یکی باشد.
descriptionstringالزامیمهارت چه می‌کند و کی باید از آن استفاده کرد. حداکثر ۱٬۰۲۴ بایت. در فهرست مهارت‌های کارمند نمایش داده می‌شود و 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""یادداشت آزاد، حداکثر ۵۰۰ بایت.
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}مسیر فایل اجرایی یک افزونه اعلام‌شده. slug با حروف بزرگ و با زیرخط به جای خط تیره نوشته می‌شود: example-ledger به ${plugin.EXAMPLE_LEDGER_BIN} تبدیل می‌شود.
${secret.KEY}مقدار یک راز اعلام‌شده.
$ARGUMENTSargs ارسال‌شده به use_skill. وقتی بدنه $ARGUMENTS ندارد، آرگومان‌ها پس از آن افزوده می‌شوند.

ابزارهای مهارت

کارمندان از طریق این ابزارها با مهارت‌ها کار می‌کنند. use_skill همیشه در دسترس است؛ بقیه وقتی کارمند به آن‌ها نیاز دارد بارگذاری می‌شوند.

ابزارپارامترهاکاربرد
use_skillname, argsیک مهارت را بارگذاری می‌کند. بدنه گسترش‌یافته، مسیر پوشه و ۲۰ نام فایل نخست را برمی‌گرداند. یک مهارت غیرفعال را دوباره فعال می‌کند.
find_skillsqueryحداکثر ۱۰ مهارت را بر اساس تطابق نام، تریگر و توضیح رتبه‌بندی‌شده برمی‌گرداند.
read_skill_filename, pathیک فایل را در پوشه مهارت می‌خواند. بدون path، فایل‌ها و اندازه‌شان را فهرست می‌کند.
save_skillname, contentیک SKILL.md کامل را در پوشه مهارت‌های کاربر می‌نویسد. مهارت‌های فروشگاه را نمی‌توان بازنویسی کرد.
delete_skillnameیک مهارت کاربر را حذف می‌کند.
install_skillcodeیک مهارت فروشگاه را با کد نصب SKIL- آن نصب می‌کند.
configure_skillname, key, valueیک راز را تنظیم می‌کند. بدون key، نشان می‌دهد مهارت به چه چیزی نیاز دارد.
rate_skillname, rating, reviewبه یک مهارت فروشگاه از ۱ تا ۵ امتیاز می‌دهد.
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", []))}))

اسکریپت در یک نسخه موقت از پوشه مهارت اجرا می‌شود، با زمان انتظار پیش‌فرض ۳۰ ثانیه. در 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.
فهرست مهارت‌هاهر ورودی در ۲۵۰ نویسه بریده می‌شود. وقتی کل فهرست از ۸٬۰۰۰ نویسه بیشتر شود، ابتدا مهارت‌های مشترک کوتاه می‌شوند؛ مهارت‌های خود کارمند ورودی کاملشان را نگه می‌دارند.

محدودیت‌های فایل‌هایی که در فروشگاه منتشر می‌کنید در صفحه انتشار آمده است.