Skills
Skills
Skills فایلهای دستورالعملی Markdown هستند که به عامل یاد میدهند چگونه و چه زمانی از
ابزارها استفاده کند. هر Skill در یک پوشه قرار دارد که شامل فایل SKILL.md با
frontmatter از نوع YAML و بدنه Markdown است. OpenClaw، Skills همراه بسته و هر
بازنویسی محلی را بارگذاری میکند و در زمان بارگذاری، آنها را بر اساس محیط،
پیکربندی و وجود باینری فیلتر میکند.
یک Skill سفارشی را از ابتدا بسازید و آزمایش کنید.
پیشنهادهای Skill تهیهشده توسط عامل را بازبینی و تأیید کنید.
طرحواره کامل پیکربندی skills.* و فهرستهای مجاز عامل.
Skills جامعه را مرور و نصب کنید.
ترتیب بارگذاری
OpenClaw از این منابع بارگذاری میکند، با بالاترین تقدم در ابتدا. وقتی نام یک Skill در چند محل ظاهر شود، منبع با بالاترین تقدم برنده میشود.
| اولویت | منبع | مسیر |
|---|---|---|
| ۱ — بالاترین | Skills فضای کاری | <workspace>/skills |
| ۲ | Skills عامل پروژه | <workspace>/.agents/skills |
| ۳ | Skills عامل شخصی | ~/.agents/skills |
| ۴ | Skills مدیریتشده / محلی | ~/.openclaw/skills |
| ۵ | Skills همراه بسته | همراه نصب ارائه میشود |
| ۶ — پایینترین | پوشههای اضافی | skills.load.extraDirs + Skills مربوط به Plugin |
ریشههای Skill از چیدمانهای گروهبندیشده پشتیبانی میکنند. OpenClaw هر زمان
SKILL.md در هر جایی زیر یک ریشه پیکربندیشده ظاهر شود، یک Skill را کشف میکند:
<workspace>/skills/research/SKILL.md ✓ found as "research"<workspace>/skills/personal/research/SKILL.md ✓ also found as "research"مسیر پوشه فقط برای سازماندهی است. نام Skill، دستور slash و کلید فهرست مجاز همگی
از فیلد frontmatter با نام name میآیند (یا وقتی name وجود ندارد، از نام
پوشه).
Skills مختص هر عامل در برابر Skills مشترک
در راهاندازیهای چندعاملی، هر عامل فضای کاری خودش را دارد. از مسیری استفاده کنید که با میزان دیدپذیری دلخواه شما سازگار است:
| دامنه | مسیر | قابل مشاهده برای |
|---|---|---|
| مختص هر عامل | <workspace>/skills |
فقط همان عامل |
| عامل پروژه | <workspace>/.agents/skills |
فقط عامل همان فضای کاری |
| عامل شخصی | ~/.agents/skills |
همه عاملهای این دستگاه |
| مدیریتشده مشترک | ~/.openclaw/skills |
همه عاملهای این دستگاه |
| پوشههای اضافی | skills.load.extraDirs |
همه عاملهای این دستگاه |
فهرستهای مجاز عامل
محل Skill (تقدم) و دیدپذیری Skill (اینکه کدام عامل میتواند از آن استفاده کند) کنترلهای جداگانهای هستند. از فهرستهای مجاز برای محدود کردن Skills قابل مشاهده برای یک عامل استفاده کنید، فارغ از اینکه از کجا بارگذاری شدهاند.
{ agents: { defaults: { skills: ["github", "weather"], // shared baseline }, list: [ { id: "writer" }, // inherits github, weather { id: "docs", skills: ["docs-search"] }, // replaces defaults entirely { id: "locked-down", skills: [] }, // no skills ], },}Allowlist rules
- برای اینکه همه Skills بهصورت پیشفرض نامحدود باشند،
agents.defaults.skillsرا حذف کنید. - برای به ارث بردن
agents.defaults.skills، مقدارagents.list[].skillsرا حذف کنید. - برای اینکه هیچ Skill برای آن عامل ارائه نشود،
agents.list[].skills: []را تنظیم کنید. - یک فهرست غیرخالی
agents.list[].skillsمجموعه نهایی است — با پیشفرضها ادغام نمیشود. - فهرست مجاز مؤثر در ساخت prompt، کشف دستورهای slash، همگامسازی sandbox و snapshotهای Skill اعمال میشود.
- این مرز مجوزدهی پوسته میزبان نیست. اگر همان عامل میتواند از
execاستفاده کند، آن پوسته را جداگانه با sandboxing، جداسازی کاربر سیستمعامل، فهرستهای رد/مجاز exec و اعتبارنامههای مختص هر منبع محدود کنید.
Pluginها و Skills
Pluginها میتوانند با فهرست کردن پوشههای skills در openclaw.plugin.json
(مسیرها نسبت به ریشه Plugin)، Skills خودشان را ارائه کنند. Skills مربوط به Plugin
وقتی Plugin فعال باشد بارگذاری میشوند — برای مثال، Plugin مرورگر یک Skill با نام
browser-automation برای کنترل چندمرحلهای مرورگر ارائه میکند.
پوشههای Skill مربوط به Plugin در همان سطح کمتقدم skills.load.extraDirs ادغام
میشوند، بنابراین یک Skill همراه بسته، مدیریتشده، عامل یا فضای کاری با همان نام،
آنها را بازنویسی میکند. آنها را از طریق metadata.openclaw.requires.config
روی ورودی پیکربندی Plugin محدود کنید.
برای سامانه کامل Plugin، Pluginها و ابزارها را ببینید.
Skill Workshop
Skill Workshop صف پیشنهادی میان عامل و فایلهای Skill
فعال شماست. وقتی عامل کار قابل استفاده مجددی را تشخیص دهد، بهجای نوشتن مستقیم
در SKILL.md یک پیشنهاد تهیه میکند. شما پیش از هر تغییری آن را بازبینی و تأیید
میکنید.
openclaw skills workshop listopenclaw skills workshop inspect <proposal-id>openclaw skills workshop apply <proposal-id>برای چرخه عمر کامل، مرجع CLI و پیکربندی، Skill Workshop را ببینید.
نصب از ClawHub
ClawHub رجیستری عمومی Skills است. برای نصب و بهروزرسانی از
دستورهای openclaw skills استفاده کنید، یا برای انتشار و همگامسازی از CLI
clawhub استفاده کنید.
| کنش | دستور |
|---|---|
| نصب یک Skill در فضای کاری | openclaw skills install @owner/<slug> |
| نصب از یک مخزن Git | openclaw skills install git:owner/repo@ref |
| نصب یک پوشه Skill محلی | openclaw skills install ./path/to/skill --as my-tool |
| نصب برای همه عاملهای محلی | openclaw skills install @owner/<slug> --global |
| بهروزرسانی همه Skills فضای کاری | openclaw skills update --all |
| بهروزرسانی یک Skill مدیریتشده مشترک | openclaw skills update @owner/<slug> --global |
| بهروزرسانی همه Skills مدیریتشده مشترک | openclaw skills update --all --global |
| بررسی پوشش اعتماد یک Skill | openclaw skills verify @owner/<slug> |
| چاپ Skill Card تولیدشده | openclaw skills verify @owner/<slug> --card |
| انتشار / همگامسازی از طریق CLI ClawHub | clawhub sync --all |
Install details
openclaw skills install بهصورت پیشفرض در پوشه skills/ فضای کاری فعال
نصب میکند. برای نصب در پوشه مشترک ~/.openclaw/skills، که برای همه
عاملهای محلی قابل مشاهده است مگر اینکه فهرستهای مجاز عامل آن را محدود
کنند، --global را اضافه کنید.
نصبهای Git و محلی انتظار دارند SKILL.md در ریشه منبع باشد. slug ابتدا از
frontmatter فایل SKILL.md و فیلد name در صورت معتبر بودن گرفته میشود،
سپس به نام پوشه یا مخزن برمیگردد. برای بازنویسی از --as <slug> استفاده
کنید. openclaw skills update فقط نصبهای ClawHub را دنبال میکند — برای
تازهسازی منابع Git یا محلی، آنها را دوباره نصب کنید.
Verification and security scanning
openclaw skills verify @owner/<slug> از ClawHub پوشش اعتماد
clawhub.skill.verify.v1 مربوط به Skill را درخواست میکند. Skills نصبشده از
ClawHub در برابر نسخه و رجیستری ثبتشده در .clawhub/origin.json بررسی
میشوند. slugهای تنها برای Skills نصبشده موجود یا بدون ابهام همچنان پذیرفته
میشوند، اما ارجاعهای دارای owner از ابهام ناشر جلوگیری میکنند.
صفحههای Skill در ClawHub تازهترین وضعیت اسکن امنیتی را پیش از نصب نشان
میدهند، همراه با صفحههای جزئیات برای VirusTotal، ClawScan و تحلیل ایستا.
وقتی ClawHub بررسی را ناموفق علامتگذاری کند، دستور با وضعیت غیرصفر خارج
میشود. ناشران false positiveها را از طریق داشبورد ClawHub یا
clawhub skill rescan @owner/<slug> برطرف میکنند.
Private archive installs
کلاینتهای Gateway که به تحویل خارج از ClawHub نیاز دارند میتوانند یک
آرشیو zip از Skill را با skills.upload.begin، skills.upload.chunk و
skills.upload.commit آماده کنند، سپس با
skills.install({ source: "upload", ... }) نصب کنند. این مسیر بهصورت
پیشفرض غیرفعال است و به skills.install.allowUploadedArchives: true در
openclaw.json نیاز دارد. نصبهای عادی ClawHub هرگز به آن تنظیم نیاز ندارند.
امنیت
Path containment
کشف Skill در فضای کاری، عامل پروژه و پوشههای اضافی فقط ریشههای Skill را
میپذیرد که realpath حلشده آنها داخل ریشه پیکربندیشده بماند، مگر اینکه
skills.load.allowSymlinkTargets بهطور صریح به یک ریشه مقصد اعتماد کند.
Skill Workshop فقط وقتی skills.workshop.allowSymlinkTargetWrites فعال باشد
از طریق آن مقصدهای مورد اعتماد مینویسد. پوشههای مدیریتشده
~/.openclaw/skills و شخصی ~/.agents/skills ممکن است شامل پوشههای Skill
symlinkشده باشند، اما realpath هر SKILL.md همچنان باید داخل پوشه Skill
حلشده خودش بماند.
Operator install policy
security.installPolicy را پیکربندی کنید تا پیش از ادامه نصب Skill، یک
دستور سیاست محلی مورد اعتماد اجرا شود. این سیاست metadata و مسیر منبع
آمادهشده را دریافت میکند، برای مسیرهای ClawHub، آپلودشده، Git، محلی،
بهروزرسانی و نصبکننده وابستگی اعمال میشود و وقتی دستور نتواند تصمیم
معتبری برگرداند، بسته و ناموفق میشود.
Secret injection scope
skills.entries.*.env و skills.entries.*.apiKey اسرار را فقط برای همان
نوبت عامل به فرایند میزبان تزریق میکنند — نه به sandbox. اسرار را از
promptها و logها دور نگه دارید.
برای مدل تهدید گستردهتر و چکلیستهای امنیتی، امنیت را ببینید.
قالب SKILL.md
هر Skill حداقل به یک name و description در frontmatter نیاز دارد:
---name: image-labdescription: Generate or edit images via a provider-backed image workflow--- When the user asks to generate an image, use the `image_generate` tool...کلیدهای اختیاری frontmatter
homepagestringURL که در رابط کاربری macOS Skills بهصورت "Website" نمایش داده میشود. از
طریق metadata.openclaw.homepage نیز پشتیبانی میشود.
user-invocablebooleandefault: trueوقتی true باشد، Skill بهصورت یک دستور slash قابل فراخوانی توسط کاربر ارائه
میشود.
disable-model-invocationbooleandefault: falseوقتی true باشد، OpenClaw دستورالعملهای Skill را از prompt عادی عامل بیرون
نگه میدارد. وقتی user-invocable نیز true باشد، Skill همچنان بهصورت دستور
slash در دسترس است.
command-dispatch"tool"وقتی روی tool تنظیم شود، دستور slash مدل را دور میزند و مستقیماً به یک
ابزار ثبتشده dispatch میشود.
command-toolstringنام ابزاری که وقتی command-dispatch: tool تنظیم شده است فراخوانی میشود.
command-arg-mode"raw"default: rawبرای ارسال ابزار، رشته خام آرگومانها را بدون هیچ تحلیل هستهای
به ابزار ارسال میکند. ابزار
{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" } را دریافت میکند.
دروازهگذاری
OpenClaw هنگام بارگذاری، مهارتها را با استفاده از metadata.openclaw (JSON تکخطی
در frontmatter) فیلتر میکند. مهارتی که بلوک metadata.openclaw ندارد همیشه
واجد شرایط است، مگر اینکه صراحتا غیرفعال شده باشد.
---name: image-labdescription: Generate or edit images via a provider-backed image workflowmetadata: { "openclaw": { "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] }, "primaryEnv": "GEMINI_API_KEY", }, }---alwaysbooleanوقتی true باشد، همیشه مهارت را شامل میکند و همه دروازههای دیگر را رد میکند.
emojistringایموجی اختیاری که در رابط Skills در macOS نشان داده میشود.
homepagestringURL اختیاری که با عنوان «وبسایت» در رابط Skills در macOS نشان داده میشود.
os"darwin" | "linux" | "win32"فیلتر پلتفرم. وقتی تنظیم شود، مهارت فقط روی سیستمعاملهای فهرستشده واجد شرایط است.
requires.binsstring[]هر باینری باید روی PATH وجود داشته باشد.
requires.anyBinsstring[]حداقل یک باینری باید روی PATH وجود داشته باشد.
requires.envstring[]هر متغیر محیطی باید در فرایند وجود داشته باشد یا از طریق پیکربندی ارائه شود.
requires.configstring[]هر مسیر openclaw.json باید truthy باشد.
primaryEnvstringنام متغیر محیطی مرتبط با skills.entries.<name>.apiKey.
installobject[]مشخصات نصبکننده اختیاری که توسط رابط Skills در macOS استفاده میشود (brew / node / go / uv / download).
مشخصات نصبکننده
مشخصات نصبکننده به رابط Skills در macOS میگوید چگونه یک وابستگی را نصب کند:
---name: geminidescription: Use Gemini CLI for coding assistance and Google search lookups.metadata: { "openclaw": { "emoji": "♊️", "requires": { "bins": ["gemini"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "gemini-cli", "bins": ["gemini"], "label": "Install Gemini CLI (brew)", }, ], }, }---قواعد انتخاب نصبکننده
- وقتی چند نصبکننده فهرست شده باشند، Gateway یک گزینه ترجیحی را انتخاب میکند (brew وقتی در دسترس باشد، وگرنه node).
- اگر همه نصبکنندهها
downloadباشند، OpenClaw هر ورودی را فهرست میکند تا بتوانید همه artifactهای موجود را ببینید. - مشخصات میتوانند شامل
os: ["darwin"|"linux"|"win32"]باشند تا براساس پلتفرم فیلتر شوند. - نصبهای Node به
skills.install.nodeManagerدرopenclaw.jsonاحترام میگذارند (پیشفرض: npm؛ گزینهها: npm / pnpm / yarn / bun). این فقط روی نصب مهارتها اثر میگذارد؛ runtime مربوط به Gateway همچنان باید Node باشد. - ترجیح نصبکننده Gateway: Homebrew → uv → مدیر node پیکربندیشده → go → download.
جزئیات هر نصبکننده
- Homebrew: OpenClaw بهصورت خودکار Homebrew را نصب نمیکند یا فرمولهای brew
را به دستورهای بسته سیستم ترجمه نمیکند. در کانتینرهای Linux بدون
brew، نصبکنندههای فقط brew پنهان میشوند؛ از یک image سفارشی استفاده کنید یا وابستگی را دستی نصب کنید. - Go: OpenClaw برای نصب خودکار مهارتها به Go 1.21 یا جدیدتر نیاز دارد و
تنظیمات موجود
GOBIN،GOPATHوGOTOOLCHAINرا حفظ میکند. اگر toolchain پیکربندیشده نتواند نسخه Go موردنیاز یک ماژول را تامین کند، onboarding پس از تلاش نصب، مهارت را همراه با پیشنیازهای دستی Go گروهبندی میکند. اگرgoوجود نداشته باشد و Homebrew در دسترس باشد، OpenClaw ابتدا Go را از طریق Homebrew نصب میکند وGOBINرا رویbinمتعلق به Homebrew تنظیم میکند. در Linux، OpenClaw میتواند بهجای آن ازapt-getبهعنوان root یا از طریقsudoبدون گذرواژه استفاده کند، وقتی candidate تازهسازیشدهgolang-goحداقل نسخه را برآورده کند. - Download:
url(الزامی)،archive(tar.gz|tar.bz2|zip)،extract(پیشفرض: تشخیص خودکار وقتی آرشیو شناسایی شود)،stripComponents،targetDir(پیشفرض:~/.openclaw/tools/<skillKey>).
نکات sandboxing
requires.bins هنگام بارگذاری مهارت روی host بررسی میشود. اگر یک agent
در sandbox اجرا شود، باینری باید داخل کانتینر هم وجود داشته باشد.
آن را از طریق agents.defaults.sandbox.docker.setupCommand یا یک image سفارشی
نصب کنید. setupCommand یک بار پس از ایجاد کانتینر اجرا میشود و به
خروج شبکه، فایلسیستم root قابل نوشتن، و کاربر root در sandbox نیاز دارد.
overrideهای پیکربندی
مهارتهای bundled یا managed را زیر skills.entries در
~/.openclaw/openclaw.json روشن و پیکربندی کنید:
{ skills: { entries: { "image-lab": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, config: { endpoint: "https://example.invalid", model: "nano-pro", }, }, peekaboo: { enabled: true }, sag: { enabled: false }, }, },}enabledbooleanfalse مهارت را حتی وقتی bundled یا نصبشده باشد غیرفعال میکند. مهارت bundled
coding-agent اختیاری است — skills.entries.coding-agent.enabled: true
را تنظیم کنید و مطمئن شوید یکی از claude، codex، opencode یا CLI
پشتیبانیشده دیگری نصب و احراز هویت شده است.
apiKeystring | { source, provider, id }فیلد کمکی برای مهارتهایی که metadata.openclaw.primaryEnv را اعلام میکنند.
از یک رشته متن ساده یا شیء SecretRef پشتیبانی میکند.
env"Record<string,configobjectکیسه اختیاری برای فیلدهای پیکربندی سفارشی هر مهارت.
allowBundledstring[]allowlist اختیاری فقط برای مهارتهای bundled. وقتی تنظیم شود، فقط مهارتهای bundled داخل فهرست واجد شرایط هستند. مهارتهای managed و workspace تحت تاثیر قرار نمیگیرند.
تزریق محیط
وقتی اجرای یک agent شروع میشود، OpenClaw:
metadata مهارت را میخواند
OpenClaw فهرست موثر مهارتها را برای agent حل میکند و قواعد دروازهگذاری، allowlistها، و overrideهای پیکربندی را اعمال میکند.
محیط و کلیدهای API را تزریق میکند
skills.entries.<key>.env و skills.entries.<key>.apiKey برای مدت اجرای
run روی process.env اعمال میشوند.
system prompt را میسازد
مهارتهای واجد شرایط در یک بلوک XML فشرده کامپایل میشوند و داخل system prompt تزریق میشوند.
محیط را بازیابی میکند
پس از پایان run، محیط اصلی بازیابی میشود.
برای backend bundled به نام claude-cli، OpenClaw همان snapshot مهارتهای
واجد شرایط را نیز بهصورت یک Plugin موقت Claude Code materialize میکند و آن را از طریق
--plugin-dir ارسال میکند. backendهای CLI دیگر فقط از prompt catalog استفاده میکنند.
Snapshotها و refresh
OpenClaw مهارتهای واجد شرایط را هنگام شروع یک session snapshot میکند و همان فهرست را برای همه turnهای بعدی در session دوباره استفاده میکند. تغییرات مهارتها یا پیکربندی در session جدید بعدی اثر میگذارند.
Skills در میانه session در دو حالت refresh میشود:
- watcher مهارتها یک تغییر
SKILL.mdرا شناسایی کند. - یک node راهدور واجد شرایط جدید متصل شود.
فهرست refreshشده در turn بعدی agent استفاده میشود. اگر allowlist موثر agent تغییر کند، OpenClaw برای همتراز نگه داشتن مهارتهای قابل مشاهده، snapshot را refresh میکند.
Watcher مهارتها
بهصورت پیشفرض، OpenClaw پوشههای مهارت را watch میکند و وقتی فایلهای
SKILL.md تغییر کنند، snapshot را bump میکند. زیر skills.load پیکربندی کنید:
{ skills: { load: { extraDirs: ["~/Projects/agent-scripts/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], watch: true, watchDebounceMs: 250, }, },}از allowSymlinkTargets برای چیدمانهای symlinkشده عمدی استفاده کنید که در آن root
یک مهارت به خارج از root پیکربندیشده اشاره میکند، برای مثال
<workspace>/skills/manager -> ~/Projects/manager/skills.
skills.workshop.allowSymlinkTargetWrites را فقط وقتی فعال کنید که Skill Workshop
باید پیشنهادها را از طریق همان مسیرهای symlinkشده قابل اعتماد نیز اعمال کند.
nodeهای macOS راهدور (Gateway لینوکسی)
اگر Gateway روی Linux اجرا شود اما یک node macOS با
مجوز system.run متصل باشد، OpenClaw میتواند مهارتهای فقط macOS را واجد شرایط بداند، وقتی
باینریهای لازم روی آن node موجود باشند. agent باید آن
مهارتها را از طریق ابزار exec با host=node اجرا کند.
nodeهای offline مهارتهای فقط راهدور را قابل مشاهده نمیکنند. اگر یک node پاسخ دادن به probeهای bin را متوقف کند، OpenClaw matchهای bin کششده آن را پاک میکند.
اثر توکن
وقتی مهارتها واجد شرایط باشند، OpenClaw یک بلوک XML فشرده را داخل system prompt تزریق میکند. هزینه قطعی است:
total = 195 + Σ (97 + len(name) + len(description) + len(filepath))- سربار پایه (فقط وقتی ≥ 1 مهارت وجود داشته باشد): حدود 195 کاراکتر
- برای هر مهارت: حدود 97 کاراکتر + طول فیلدهای
name،descriptionوlocationشما - XML escaping،
& < > " 'را به entity تبدیل میکند و بهازای هر رخداد چند کاراکتر اضافه میکند - با حدود 4 کاراکتر/توکن، 97 کاراکتر ≈ 24 توکن برای هر مهارت پیش از طول فیلدها
برای کمینه کردن سربار prompt، توضیحات را کوتاه و توصیفی نگه دارید.
مرتبط
راهنمای گامبهگام برای نوشتن یک مهارت سفارشی.
صف پیشنهاد برای مهارتهای draftشده توسط agent.
schema کامل پیکربندی skills.* و allowlistهای agent.
نحوه ثبت و route شدن دستورهای slash مهارت.
مهارتها را در registry عمومی مرور و منتشر کنید.
Pluginها میتوانند مهارتها را همراه ابزارهایی که مستند میکنند ارسال کنند.