--- read_when: - انتشار Skills - اشکال‌زدایی خطاهای انتشار summary: قالب پوشهٔ Skills، فایل‌های الزامی، مصنوعات پشتیبان، محدودیت‌ها. x-i18n: generated_at: "2026-07-27T14:57:49Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: fdf16a589b8961ccd9181a53a9fa92a358952b9147d22eaf977f23e0b4b4d653 source_path: clawhub/skill-format.md workflow: 16 --- # قالب Skill ## روی دیسک یک Skill یک پوشه است. الزامی: - `SKILL.md` (یا `skill.md`؛ قالب قدیمی `skills.md` نیز پذیرفته می‌شود) اختیاری: - هر فایل عادی پشتیبان (به «فایل‌های Skill» مراجعه کنید) - `.clawhubignore` (الگوهای نادیده‌گرفتن برای انتشار، قالب قدیمی `.clawdhubignore`) - `.gitignore` (این مورد نیز رعایت می‌شود) ## درون‌ریزی از GitHub درون‌ریز وب GitHub از انتشار/همگام‌سازی محلی سخت‌گیرانه‌تر است. این درون‌ریز فقط فایل‌های `SKILL.md` یا فایل‌های قدیمی `skills.md` را در مخزن‌های عمومی و غیرفورکِ متعلق به حساب GitHub واردشده شناسایی می‌کند. مخزن‌های خصوصی، فورک‌ها، مخزن‌های بایگانی‌شده/غیرفعال یا مخزن‌های عمومی اشخاص ثالث را درون‌ریزی نمی‌کند. فراداده نصب محلی (نوشته‌شده توسط CLI): - `/.clawhub/origin.json` (قالب قدیمی `.clawdhub`) وضعیت نصب پوشه کاری (نوشته‌شده توسط CLI): - `/.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 پایه ```yaml --- name: my-skill description: خلاصه‌ای کوتاه از کاری که این Skill انجام می‌دهد. version: 1.0.0 --- ``` ### فراداده زمان اجرا (`metadata.openclaw`) نیازمندی‌های زمان اجرای Skill را در `metadata.openclaw` تعریف کنید (نام‌های مستعار: `metadata.clawdbot`، `metadata.clawdis`). ```yaml --- name: my-skill description: مدیریت وظایف از طریق API Todoist. metadata: openclaw: requires: env: - TODOIST_API_KEY bins: - curl primaryEnv: TODOIST_API_KEY --- ``` برای متغیرهای محیطی که باید پیش از اجرای Skill موجود باشند، از `requires.env` استفاده کنید. هنگامی که برای هر متغیر به فراداده نیاز دارید، از جمله متغیرهای اختیاری با `required: false`، از `envVars` استفاده کنید. ### مرجع کامل فیلدها | فیلد | نوع | توضیحات | | ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `requires.env` | `string[]` | متغیرهای محیطی الزامی که Skill انتظار دارد. | | `requires.bins` | `string[]` | فایل‌های اجرایی CLI که همه آن‌ها باید نصب باشند. | | `requires.anyBins` | `string[]` | فایل‌های اجرایی CLI که دست‌کم یکی از آن‌ها باید موجود باشد. | | `requires.config` | `string[]` | مسیر فایل‌های پیکربندی که Skill می‌خواند. | | `primaryEnv` | `string` | متغیر محیطی اصلیِ اطلاعات احراز هویت برای Skill. | | `envVars` | `array` | تعریف متغیرهای محیطی با `name`، مقدار اختیاری `required` و مقدار اختیاری `description`. برای متغیرهای محیطی اختیاری، `required: false` را تنظیم کنید. | | `always` | `boolean` | اگر `true` باشد، Skill همیشه فعال است (به نصب صریح نیازی نیست). | | `skillKey` | `string` | کلید فراخوانی Skill را بازنویسی می‌کند. | | `emoji` | `string` | ایموجی نمایشی Skill. | | `homepage` | `string` | نشانی اینترنتی صفحه اصلی یا مستندات Skill. | | `os` | `string[]` | محدودیت‌های سیستم‌عامل (برای نمونه `["macos"]`، `["linux"]`). | | `install` | `array` | مشخصات نصب وابستگی‌ها (پایین را ببینید). | | `nix` | `object` | مشخصات Plugin مربوط به Nix (به README مراجعه کنید). | | `config` | `object` | مشخصات پیکربندی Clawdbot (به README مراجعه کنید). | ### مشخصات نصب اگر Skill به نصب وابستگی‌ها نیاز دارد، آن‌ها را در آرایه `install` تعریف کنید: ```yaml 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 بدون آن‌ها نمی‌تواند اجرا شود. ```yaml 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 کامل ```yaml --- name: todoist-cli description: مدیریت وظایف، پروژه‌ها و برچسب‌های Todoist از خط فرمان. version: 1.2.0 metadata: 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` برای متغیرهای اختیاری).