قالب Skill

روی دیسک

یک Skill یک پوشه است.

الزامی:

• SKILL.md (یا skill.md؛ قالب قدیمی skills.md نیز پذیرفته می‌شود)

اختیاری:

• هر فایل عادی پشتیبان (به «فایل‌های Skill» مراجعه کنید)
• .clawhubignore (الگوهای نادیده‌گرفتن برای انتشار، قالب قدیمی .clawdhubignore)
• .gitignore (این مورد نیز رعایت می‌شود)

درون‌ریزی از GitHub

درون‌ریز وب GitHub از انتشار/همگام‌سازی محلی سخت‌گیرانه‌تر است. این درون‌ریز فقط فایل‌های SKILL.md یا فایل‌های قدیمی skills.md را در مخزن‌های عمومی و غیرفورکِ متعلق به حساب GitHub واردشده شناسایی می‌کند. مخزن‌های خصوصی، فورک‌ها، مخزن‌های بایگانی‌شده/غیرفعال یا مخزن‌های عمومی اشخاص ثالث را درون‌ریزی نمی‌کند.

فراداده نصب محلی (نوشته‌شده توسط CLI):

• <skill>/.clawhub/origin.json (قالب قدیمی .clawdhub)

وضعیت نصب پوشه کاری (نوشته‌شده توسط CLI):

• <workdir>/.clawhub/lock.json (قالب قدیمی .clawdhub)

SKILL.md

• Markdown با frontmatter اختیاری YAML.
• سرور هنگام انتشار، فراداده را از frontmatter استخراج می‌کند.
• description به‌عنوان خلاصه Skill در رابط کاربری/جست‌وجو استفاده می‌شود.

برای Agent Skills قابل‌حمل، name باید با پوشه والد مطابقت داشته باشد و از 1 تا 64 حرف کوچک، عدد یا خط تیره تشکیل شود. ClawHub شناسه مسیریابی‌پذیر و نام نمایشی کاتالوگ را جدا نگه می‌دارد؛ بنابراین نام‌های موجود از کلاینت‌های دیگر همچنان قابل‌انتشار می‌مانند و بی‌سروصدا بازنویسی نمی‌شوند. فهرست‌های کاتالوگ ممکن است نام‌های طولانی را از نظر بصری کوتاه کنند، بدون آنکه نام ذخیره‌شده تغییر کند.

فراداده frontmatter

فراداده Skill در frontmatter قالب YAML در ابتدای SKILL.md تعریف می‌شود. این بخش به رجیستری (و تحلیل امنیتی) اعلام می‌کند که Skill برای اجرا به چه چیزهایی نیاز دارد.

frontmatter پایه

---name: my-skilldescription: خلاصه‌ای کوتاه از کاری که این Skill انجام می‌دهد.version: 1.0.0---

فراداده زمان اجرا (metadata.openclaw)

نیازمندی‌های زمان اجرای Skill را در metadata.openclaw تعریف کنید (نام‌های مستعار: metadata.clawdbot، metadata.clawdis).

---name: my-skilldescription: مدیریت وظایف از طریق API Todoist.metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY---

برای متغیرهای محیطی که باید پیش از اجرای Skill موجود باشند، از requires.env استفاده کنید. هنگامی که برای هر متغیر به فراداده نیاز دارید، از جمله متغیرهای اختیاری با required: false، از envVars استفاده کنید.

مرجع کامل فیلدها

مشخصات نصب

اگر Skill به نصب وابستگی‌ها نیاز دارد، آن‌ها را در آرایه install تعریف کنید:

metadata:  openclaw:    install:      - kind: brew        formula: jq        bins: [jq]      - kind: node        package: typescript        bins: [tsc]

انواع نصب پشتیبانی‌شده: brew، node، go، uv.

متغیرهای محیطی اختیاری

متغیرهای محیطی اختیاری را زیر metadata.openclaw.envVars تعریف و required: false را تنظیم کنید. ورودی‌های اختیاری را به requires.env اضافه نکنید، زیرا requires.env به این معناست که Skill بدون آن‌ها نمی‌تواند اجرا شود.

metadata:  openclaw:    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: توکن API Todoist که برای درخواست‌های احرازشده استفاده می‌شود.      - name: TODOIST_PROJECT_ID        required: false        description: شناسه اختیاری پروژه پیش‌فرض، هنگامی که کاربر موردی را مشخص نمی‌کند.

دلیل اهمیت این موضوع

تحلیل امنیتی ClawHub بررسی می‌کند که موارد تعریف‌شده توسط Skill با عملکرد واقعی آن مطابقت داشته باشد. اگر کد به TODOIST_API_KEY ارجاع دهد، اما frontmatter آن را زیر requires.env، primaryEnv یا envVars تعریف نکرده باشد، تحلیل عدم تطابق فراداده را علامت‌گذاری می‌کند. دقیق نگه‌داشتن تعریف‌ها به عبور Skill از بازبینی کمک می‌کند و باعث می‌شود کاربران بدانند چه چیزی را نصب می‌کنند.

نمونه: frontmatter کامل

---name: todoist-clidescription: مدیریت وظایف، پروژه‌ها و برچسب‌های Todoist از خط فرمان.version: 1.2.0metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: توکن API Todoist.      - name: TODOIST_PROJECT_ID        required: false        description: شناسه اختیاری پروژه پیش‌فرض.    emoji: "\u2705"    homepage: https://github.com/example/todoist-cli---

فایل‌های Skill

انتشار همه فایل‌های عادی موجود در پوشه Skill را، صرف‌نظر از پسوند، می‌پذیرد. فایل‌های نادیده‌گرفته‌شده، مسیرهای مخفی، پیوندهای نمادین، فراداده macOS و محدودیت‌های اندازه سمت سرور همچنان اعمال می‌شوند.

• فایل‌های دارای اندازه محدود که حاوی UTF-8 معتبر باشند، به‌صورت متن ساده escapeشده قابل پیش‌نمایش‌اند و در تحلیل متن محدودشده گنجانده می‌شوند.
• فایل‌های دیگر بایت‌های دقیق خود را حفظ می‌کنند و برای بارگیری در دسترس‌اند.
• اسکنرهای امنیتی کل مصنوع ذخیره‌شده را دریافت می‌کنند؛ تشخیص متن یک موضوع مربوط به نمایش و تحلیل است، نه فهرست مجاز بارگذاری.

محدودیت‌ها (سمت سرور):

• اندازه کل بسته: 50MB.
• متن تعبیه‌شده شامل SKILL.md + حداکثر حدود 40 فایل UTF-8 دارای اندازه محدود است (سقف با تلاش بهترین حالت).

شناسه‌های مسیریابی

• به‌طور پیش‌فرض از نام پوشه مشتق می‌شوند.
• محدوده‌های بسته باید دقیقاً با شناسه ناشر ClawHub مطابقت داشته باشند. شناسه‌های ناشر می‌توانند شامل حروف کوچک، اعداد، خط تیره، نقطه و زیرخط باشند؛ آن‌ها باید با یک حرف کوچک یا عدد شروع و پایان یابند.
• شناسه‌های بسته باید با حروف کوچک و برای npm ایمن باشند؛ برای نمونه @example.tools/demo-plugin یا demo-plugin.

نسخه‌بندی + برچسب‌ها

• هر انتشار یک نسخه جدید ایجاد می‌کند (semver).
• برچسب‌ها اشاره‌گرهای رشته‌ای به یک نسخه هستند؛ latest معمولاً استفاده می‌شود.

مجوز

• همه Skillهای منتشرشده در ClawHub تحت مجوز MIT-0 قرار دارند.
• هر کسی می‌تواند Skillهای منتشرشده را، از جمله برای کاربرد تجاری، استفاده، اصلاح و بازتوزیع کند.
• ذکر منبع الزامی نیست.
• شرایط مجوز متعارض را به SKILL.md اضافه نکنید؛ ClawHub از بازنویسی مجوز برای هر Skill پشتیبانی نمی‌کند.

Skillهای پولی

• ClawHub از Skillهای پولی، قیمت‌گذاری برای هر Skill، دیوار پرداخت یا تقسیم درآمد پشتیبانی نمی‌کند.
• فراداده قیمت‌گذاری را به SKILL.md اضافه نکنید؛ این مورد بخشی از قالب Skill نیست و یک Skill منتشرشده را پولی نمی‌کند.
• اگر Skill با یک سرویس پولی شخص ثالث یکپارچه می‌شود، هزینه خارجی و حساب الزامی را به‌روشنی در دستورالعمل‌های Skill و تعریف‌های محیطی مستند کنید (requires.env برای متغیرهای الزامی، یا envVars همراه با required: false برای متغیرهای اختیاری).