SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

اشتراک‌گذاری مهارت‌های عامل بین مخازن بدون ایجاد تداخل

کپی کردن مهارت‌ها در مخازن مختلف باعث ایجاد تداخل می‌شود. با مدیریت مهارت‌ها به عنوان وابستگی، یک مخزن مرکزی ایجاد کنید تا هر پروژه با نسخه مشخص به آن متصل شود.

اشتراک‌گذاری مهارت‌های agent بین مخزن‌ها

برای اشتراک‌گذاری مهارت‌های agent بین مخزن‌ها، کپی‌کردن فایل را متوقف کنید و به آن وابسته شوید. یک مخزن مهارت واحد نگه دارید، برای آن tag ایجاد کنید و هر پروژه را به یک tag مشخص وابسته کنید. سپس برای هر مهارت یک smoke test اضافه کنید و هر به‌روزرسانی نسخه را مانند به‌روزرسانی یک dependency بازبینی کنید.

این کار چهار بخش دارد: یک مرجع مشترک و معتبر، یک نسخه pinned برای هر مخزن، یک smoke test برای هر مهارت و یک مسیر بازبینی. در ادامه توضیح می‌دهیم که چرا هر بخش وجود دارد، ابزارهایی که در 2026 عرضه می‌شوند با این موضوع چگونه برخورد می‌کنند و چگونه می‌توان کل این ساختار را روی یک git remote خودمیزبان، بدون استفاده از git host یا package registry خارجی، ایجاد کرد. smoke testها تنها استثنا هستند. آن‌ها Claude Code را اجرا می‌کنند و Claude Code هر درخواست را به یک model API ارسال می‌کند؛ بنابراین این مرحله همچنان از سرور شما خارج می‌شود.

یک مهارت agent پوشه‌ای است که یک فایل SKILL.md و هر script و reference file موردنیاز آن را در خود دارد. اگر این واحد برای شما جدید است، ابتدا agent skill چیست و SKILL.md چگونه کار می‌کند را بخوانید. این صفحه درباره supply chain پیرامون این واحد است.

محل قرارگیری مهارت‌ها و دلیل دشواری اشتراک‌گذاری آن‌ها

Claude Code مهارت‌ها را از مکان‌های زیر، در کنار سایر مسیرها، بارگذاری می‌کند و مستندات مهارت‌ها هر مسیر را نام‌گذاری کرده است.

  • .claude/skills/<skill-name>/SKILL.md در داخل دایرکتوری تنظیمات مدیریت‌شده، مکان سازمانی است. این مسیر برای هر کاربر در ماشین‌هایی که سازمان آن را مستقر کرده است، بارگذاری می‌شود.
  • ~/.claude/skills/<skill-name>/SKILL.md شخصی است. این مسیر در تمام پروژه‌های شما و نه هیچ‌کس دیگر بارگذاری می‌شود.
  • .claude/skills/<skill-name>/SKILL.md در سطح پروژه است. این مسیر برای هر کسی که آن مخزن (repository) را دریافت (checkout) کند، بارگذاری می‌شود.
  • <plugin>/skills/<skill-name>/SKILL.md در داخل یک افزونه (plugin) عرضه می‌شود. این مسیر در هر جایی که آن افزونه فعال باشد، بارگذاری می‌شود.

Claude Code همچنین مهارت‌ها را از دایرکتوری‌های تو در توی پروژه، دایرکتوری‌های ارائه‌شده با --add-dir و مهارت‌های فعال‌شده برای حساب کاربری claude.ai شما بارگذاری می‌کند.

سطح پروژه برای یک تیم مفید است، زیرا این مهارت‌ها commit می‌شوند و هر کسی که مخزن را clone کند، آن‌ها را دریافت می‌کند. این همان جایی است که مشکلات آغاز می‌شود. یک مهارت در .claude/skills/ متعلق به یک مخزن است. شما هشت مخزن دارید. بنابراین مهارت هشت بار کپی می‌شود.

بخش frontmatter هیچ کمکی نمی‌کند. مشخصات Agent Skills اجازه استفاده از شش کلید را می‌دهد و مسیرهای توزیعی که آن را اعمال می‌کنند، در صورت استفاده از کلیدی دیگر، لیست را چاپ می‌کنند:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

به آنچه وجود ندارد توجه کنید: هیچ کلیدی برای version وجود ندارد. یک نسخه می‌تواند تحت metadata ثبت شود، اما مشخصات، هیچ وابستگی (dependency pin) یا مکانیزم به‌روزرسانی را تعریف نمی‌کند. این منطقی است، زیرا یک مهارت بیشتر یک سند است تا یک بسته (package). این بدان معناست که نسخه‌سازی باید از لایه اطراف فایل انجام شود و آن لایه وظیفه شماست.

مشکل اول: هشت کپی که به‌آرامی از هم فاصله می‌گیرند

عملیات کپی-پیست در روز اول به‌خوبی کار می‌کند، اما در روز 60 با شکست مواجه می‌شود. شخصی یک دستورالعمل اشتباه را در مخزن payments اصلاح می‌کند و هفت مخزن دیگر را تغییر نمی‌دهد. فرد دیگری قانونی درباره صفحه‌بندی در orders اضافه می‌کند. اکنون یک نام مهارت واحد، بسته به اینکه عامل (agent) در کدام دایرکتوری اجرا شده باشد، دو خروجی متفاوت ارائه می‌دهد و هیچ‌کدام از توسعه‌دهندگان از این موضوع مطلع نیستند.

این شکست به‌صورت خاموش رخ می‌دهد، زیرا هیچ وضعیت خطایی وجود ندارد. یک مهارت در واقع متن است. یک دستورالعمل قدیمی، پاسخی با اعتمادبه‌نفس اما غلط تولید می‌کند که پرهزینه‌ترین نوع خطا است. هیچ بخشی در عامل وجود ندارد که کپی شما را با کپی‌های دیگر مقایسه کند، بنابراین تنها نشانه، زمانی است که یک شخص متوجه تضاد بین دو مخزن می‌شود.

مشکل دوم: عدم تثبیت نسخه (version pinning)

حتی زمانی که یک تیم مهارت‌ها (skills) را در یک مکان واحد نگهداری می‌کند، روش معمول اشتراک‌گذاری، یک مرحله کپی‌برداری است: یک اسکریپت راه‌اندازی، یک خط curl در مستندات ورود به سیستم، یا یک shell alias که یک پوشه را همگام‌سازی می‌کند. تمام این روش‌ها، هر چیزی را که در حال حاضر در ابتدای شاخه (head of the branch) قرار دارد، نصب می‌کنند.

این بدان معناست که دو توسعه‌دهنده روی یک commit یکسان از یک برنامه، ممکن است دستورالعمل‌های متفاوتی را اجرا کنند، زیرا آن‌ها همگام‌سازی را در روزهای متفاوتی انجام داده‌اند. این همچنین به این معنی است که شما نمی‌توانید به سوالی که پس از اجرای ناموفق یک agent اهمیت دارد، پاسخ دهید: کدام نسخه از این مهارت، این خروجی را ایجاد کرده است؟ بدون ثبت یک revision، اجرا قابل بازتولید نیست و در نتیجه، گزارش باگ قابل پیگیری نخواهد بود.

مشکل سوم: هیچ‌کس نمی‌داند که این مهارت همچنان کار می‌کند

یک مهارت (skill) کامپایلر ندارد. این مهارت مجموعه‌ای از دستورالعمل‌ها برای یک مدل است، بنابراین ممکن است در حالی که فایل دقیقاً به همان شکل باقی مانده است، از کار بیفتد. ارتقای مدل می‌تواند نحوه پیروی آن از دستورالعمل‌های طولانی را تغییر دهد. یک ابزار خط فرمان که توسط مهارت فراخوانی می‌شود ممکن است نام یکی از flagهای خود را تغییر دهد. یک URL در یک فایل مرجع ممکن است خطای 404 برگرداند و عامل (agent) شروع به کار بر اساس صفحه خطا کند.

در هیچ‌کدام از این موارد، خرابی به شکل آشکار رخ نمی‌دهد. عامل همچنان پاسخ می‌دهد. پاسخ فقط نسبت به ماه گذشته کیفیت پایین‌تری دارد، که تشخیص این موضوع در هر pull request به صورت جداگانه، کار دشواری است.

مشکلاتی که ابزارهای عرضه‌شده در سال 2026 حل می‌کنند

پاسخ‌های متعددی در حال حاضر مطرح شده‌اند که در مورد محل قرارگیری نسخه با یکدیگر اختلاف نظر دارند.

فایل‌های قفل (Lockfiles). ابزار خط فرمان skills از Vercel Labs (لینک به vercel-labs/skills، تحت مجوز MIT، نسخه 1.7.2 در تاریخ 9 اکتبر 2026)، مهارت‌ها (skills) را از یک مخزن git در هر دایرکتوری که agent شما انتظار دارد نصب می‌کند و ساختار بیش از هفتاد agent مختلف را می‌شناسد. دستور npx skills add <repo> برای نصب، npx skills update برای ارتقا و npx skills list برای نمایش موارد نصب‌شده استفاده می‌شود. این ابزار دو فایل قفل نگهداری می‌کند. یک فایل سراسری در ~/.agents/.skill-lock.json که موارد نصب‌شده توسط یک کاربر را ثبت می‌کند. از نسخه 1.4.1 (20 فوریه 2026)، نصب در سطح پروژه نیز فایل skills-lock.json را در ریشه پروژه ایجاد می‌کند و طبق سورس‌کد ابزار، این فایل باید در سیستم کنترل نسخه (version control) ثبت شود. دستور npx skills experimental_install مهارت‌های یک پروژه را از روی این فایل بازیابی می‌کند. Issue شماره 283 که درخواست یک دستور skills install برای بازیابی فایل قفل سراسری روی دستگاهی دیگر را داشت، در تاریخ 5 نوامبر 2026 با وضعیت "برنامه‌ریزی‌نشده" بسته شد؛ نگهدارنده پروژه این مورد را مشابه درخواست مطرح‌شده در Issue 549 می‌داند. هر دو را به عنوان گزارش وضعیت مطالعه کنید. فایل قفل مخصوص پروژه وجود دارد. در نسخه 1.8.1، دستور بازیابی هنوز در راهنما به عنوان آزمایشی (experimental) برچسب‌گذاری شده است، اما npx skills install بدون منبع نیز فایل قفل پروژه را بازیابی می‌کند.

مشخصات و تست‌ها. ابزار SkillSpec رویکرد متفاوتی دارد. این ابزار یک SKILL.md را به عنوان یک قرارداد برای بررسی در نظر می‌گیرد، نه متنی برای اعتماد؛ با هدف اعلام‌شده‌ی "قابل‌دنبال‌کردن، قابل‌تست و قابل‌اثبات" کردن مهارت‌ها. دستور skillspec doctor <path> گزارش می‌دهد که یک agent احتمالاً در کجا رشته عملیات را رها می‌کند. skillspec boundary map <path> محتوای مهارت را نمایش می‌دهد و skillspec boundary assess <path> گزارش می‌دهد که مهارت به چه مواردی دسترسی دارد و آن‌ها را بر اساس ریسک رتبه‌بندی می‌کند. این ابزار یک Rust crate است که با مجوز دوگانه MIT یا Apache 2.0 ارائه می‌شود. نسخه 0.2.2 در تاریخ 29 ژوئیه 2026 منتشر شد و تا 10 اکتبر 2026 همچنان جدیدترین نسخه در crates.io است. به جای نسخه جدید، نسخه پین‌شده را نصب کنید:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

از زمان انتشار Cargo 1.100 در تاریخ 12 نوامبر 2026، دستور cargo install به‌طور پیش‌فرض از فایل قفل بسته‌بندی‌شده استفاده می‌کند و --locked دیگر عملیاتی انجام نمی‌دهد. دستور skillspec --version باید 0.2.2 را چاپ کند. عددی متفاوت به این معنی است که یک باینری قدیمی‌تر که در PATH شما زودتر قرار گرفته، در حال اجراست.

رویه Vendor. گوگل در پستی با عنوان نحوه ساخت، تست و مقیاس‌دهی مهارت‌های agent، نحوه ساخت مهارت‌ها در google/skills را شرح داده است. اگر مقیاس را کنار بگذاریم، این مکانیزم یک یکپارچه‌سازی مداوم (CI) معمولی است. هر مهارت پیش از ادغام (merge)، از فیلترهای linter برای متادیتای frontmatter، تعداد خطوط، ساختار دایرکتوری و نام‌گذاری عبور می‌کند. یک بررسی‌کننده لینک (link checker) در صورت بازگشت خطای 404 برای هر URL، بیلد را متوقف می‌کند که این کار باعث شناسایی لینک‌های احتمالی ساختگی توسط agent می‌شود. نویسندگان باید در کنار مهارت، یک مجموعه پرامپت ارزیابی و یک دستورالعمل امتیازدهی ارائه دهند. کارهای ارزیابی زمان‌بندی‌شده به‌صورت هفتگی روی کل کتابخانه اجرا می‌شوند تا رگرسیون‌ها شناسایی شوند و هر مهارت یک مالک مشخص دارد که انتظار می‌رود در صورت افت کیفیت، آن را اصلاح کند.

الگوی زیربنایی هر سه پاسخ

شما مجبور نیستید یکی از آن‌ها را انتخاب کنید. در زیر آن‌ها یک ساختار واحد وجود دارد و git به تنهایی تمام آن را در اختیار شما قرار می‌دهد.

  1. یک منبع واحد برای حقیقت. مهارت دقیقاً یک جایگاه اصلی دارد و هر مخزن به‌جای نگهداری یک کپی، به همان جایگاه ارجاع می‌دهد.
  2. یک نسخه ثابت (pinned) برای هر مخزن. هر پروژه دقیقاً همان نسخه‌ای را که استفاده می‌کند ثبت می‌نماید، بنابراین ارتقا به معنای ثبت یک commit در آن پروژه با مشخصات نویسنده و تاریخ است.
  3. یک تست سلامت (smoke test) برای هر مهارت. یک بررسی قابل‌اجرا که ثابت می‌کند مهارت همچنان نتیجه وعده‌داده‌شده را تولید می‌کند.
  4. یک مسیر بازبینی. تغییر در یک مهارت اشتراکی از مسیر بازبینی می‌گذرد و هر مصرف‌کننده پیش از پذیرش تغییر، یک diff را مشاهده می‌کند.

این ساختار یک وابستگی (dependency) است. مهارت‌ها سریع‌تر از آنکه ابزارهای پیرامونشان رشد کنند به یک artifact اشتراکی تبدیل شدند، بنابراین ابزاری که از قبل به آن اعتماد دارید، مطمئن‌ترین گزینه برای استفاده است.

ساختاری برای یک تیم کوچک روی یک git remote شخصی‌سازی‌شده (self-hosted)

یک مخزن (repository) تمام مهارت‌ها را در خود جای می‌دهد. هیچ چیز دیگری در آن قرار ندارد، بنابراین تاریخچهٔ آن به عنوان یک changelog از دستورالعمل‌ها عمل می‌کند.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

نسخه‌ها (Releases) همان تگ‌ها هستند. از تگ‌های annotated استفاده کنید، زیرا این تگ‌ها شامل پیام و تاریخ هستند. پیام تگ را به گونه‌ای بنویسید که دلیل نیاز مصرف‌کننده به ارتقای نسخه را توضیح دهد:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

اگر remote شما Gitea، Forgejo، GitLab یا یک مخزن bare روی SSH در VPS شخصی شما باشد، هیچ‌کدام از موارد زیر تغییر نمی‌کند. تمام آنچه در اینجا آمده، ترکیبی از git و یک symlink است.

پین کردن با استفاده از git submodule

یک submodule دقیقاً یک commit خاص از یک مخزن دیگر را درون مخزن شما ثبت می‌کند. آن رکورد همان پین (pin) است. در هر پروژه مصرف‌کننده:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

لینک نمادین (symlink) بخشی است که باعث کارکرد این فرآیند می‌شود. یک ورودی skill در سطح پروژه می‌تواند یک symlink به دایرکتوری دیگری در دیسک باشد و Claude Code آن را دنبال کرده و SKILL.md را از مقصد می‌خواند. بنابراین، skill به عنوان یک skill معمولی پروژه بارگذاری می‌شود، در حالی که بایت‌های آن در submodule و در commit انتخابی شما قرار دارند.

پین را بررسی کنید:

git submodule status

یک خط سالم با یک فاصله شروع می‌شود، سپس commit، سپس مسیر و در نهایت نزدیک‌ترین تگ:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

یک - در ابتدای خط به این معنی است که submodule هرگز مقداردهی اولیه (initialise) نشده است، بنابراین .claude/skills/api-review به هیچ‌جا اشاره نمی‌کند و skill بدون هیچ خطایی بارگذاری نمی‌شود. این مشکل را با git submodule update --init برطرف کنید. یک + در ابتدای خط به این معنی است که commit بررسی‌شده (checked-out) با commit ثبت‌شده متفاوت است، بنابراین آن توسعه‌دهنده در حال اجرای دستورالعمل‌هایی است که هیچ‌کس دیگری ندارد. کلون‌های جدید به git clone --recurse-submodules نیاز دارند و این خط باید در README قرار بگیرد، زیرا یک clone ساده، vendor/agent-skills را خالی می‌گذارد و هیچ خطایی چاپ نمی‌کند.

ارتقا یک اقدام آگاهانه است و این دقیقاً هدف اصلی است:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

خط diff مسیر بازبینی است. این خط همان تغییری را نشان می‌دهد که سایر مخازن مصرف‌کننده مشاهده خواهند کرد و در یک pull request به‌خوبی جای می‌گیرد.

استفاده از marketplace افزونه‌ها برای Pinning

اگر ترجیح می‌دهید از توسعه‌دهندگان نخواهید که submodules را یاد بگیرند، سیستم افزونه Claude Code توزیع را برای شما انجام می‌دهد و با یک remote خود-میزبانی‌شده (self-hosted) کار می‌کند. یک کاتالوگ در .claude-plugin/marketplace.json در مخزن skills قرار دهید:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

در اینجا دو منبع متفاوت در کار هستند و اشتباه رایج، جابه‌جا گرفتن آن‌هاست. منبع marketplace، یعنی جایی که کاتالوگ از آن دریافت می‌شود، ref را برای یک branch یا tag و در نسخه Claude Code v2.1.324 یا بالاتر، یک commit SHA کامل با حروف کوچک می‌پذیرد؛ این منبع فیلد جداگانه sha را قبول نمی‌کند. منبع افزونه در داخل کاتالوگ هر دو را می‌پذیرد و هنگامی که هر دو تنظیم شده باشند، sha مقدار نهایی برای pin کردن است. کاتالوگ را از طریق ref در منبع marketplace آن و افزونه را از طریق sha در ورودی کاتالوگ pin کنید. نام نوع‌ها (type names) نیز متفاوت هستند. در داخل کاتالوگ، url به معنای یک مخزن git برای clone کردن است. در یک منبع marketplace، url به معنای لینک مستقیم به یک فایل marketplace.json است و مخزن git با git مشخص می‌شود.

سپس هر مخزن مصرف‌کننده، marketplace را در فایل .claude/settings.json خود که commit شده است، اعلام می‌کند:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Claude Code پس از آنکه هم‌تیمی کادر اعتماد (trust dialog) فضای کاری را برای پوشه پروژه بپذیرد، marketplace را برای او ثبت می‌کند و نیازی به صفحه wiki برای راهنمایی آن‌ها نیست. ورودی کاتالوگ به جای مسیر نسبی، به یک URL از نوع git اشاره می‌کند، بنابراین افزونه به تنهایی از تنظیمات مخزن نصب نمی‌شود. هر هم‌تیمی یک بار دستور claude plugin install team-skills@acme-agents --scope project را اجرا می‌کند و تا آن زمان، Claude Code گزارش می‌دهد که افزونه در تنظیمات پروژه فعال است اما نصب نشده است. سپس مهارت‌ها به /team-skills:api-review پاسخ می‌دهند، زیرا مهارت‌های افزونه بر اساس نام افزونه namespace می‌شوند و نمی‌توانند با مهارت پروژه که نام مشابهی دارد تداخل پیدا کنند. پس از اینکه یک tag جدید push کردید و pinها را در کاتالوگ و مخازن مصرف‌کننده به‌روزرسانی کردید، مصرف‌کنندگان با /plugin marketplace update acme-agents رفرش می‌کنند و سپس اگر خلاصه نصب درخواست کرد، /reload-plugins را اجرا می‌کنند.

نوشتن یک smoke test برای یک skill

یک smoke test شامل اجرای اسکریپت‌شدهٔ یک agent روی یک fixture با یک خطای شناخته‌شده، به همراه یک assertion است. Claude Code به‌صورت غیرتعاملی با -p اجرا می‌شود و یک skill که توسط کاربر فراخوانی شده در آنجا کار می‌کند: /skill-name را در رشتهٔ prompt قرار دهید تا پیش از شروع اجرا، بسط داده شود.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md یک فایل کوتاه با یک خطای عمدی است. assertion این است که skill باید آن را نام ببرد. jq -e زمانی که فیلتر آن null تولید می‌کند، با کد خروجی غیرصفر خارج می‌شود؛ بنابراین اگر یک skill دیگر خطای کاشته‌شده را شناسایی نکند، اسکریپت شکست می‌خورد. claude خود در صورت شکست اجرا، با کد خروجی غیرصفر خارج می‌شود و set -euo pipefail هر دو نوع شکست را به یک تست ناموفق تبدیل می‌کند.

مدل‌ها پاسخ‌های خود را بین اجراها تغییر می‌دهند، بنابراین هرگز روی یک جملهٔ کامل assertion ننویسید. روی شناسه‌ای که skill باید صادر کند یا روی فیلدی از طرحواره‌ای (schema) که درخواست کرده‌اید assertion بگذارید و fixture را کوچک نگه دارید تا هزینهٔ اجرا پایین بماند.

در CI، از --bare استفاده کنید. بدون آن، claude -p همان contextای را بارگذاری می‌کند که یک نشست تعاملی بارگذاری می‌کرد، شامل hookها، pluginها و CLAUDE.md از ماشینی که روی آن اجرا می‌شود؛ بنابراین پیکربندی شخصی یک همکار می‌تواند نتیجه را تغییر دهد. حالت bare، کشف خودکار (auto-discovery) را به جز برای skillهای موجود در .claude/skills/ تحت دایرکتوری که صراحتاً با --add-dir ارائه شده، نادیده می‌گیرد؛ این حالت، skill پروژه‌ای که در حال تست آن هستید را نادیده می‌گیرد، پس آن را صراحتاً بارگذاری کنید. حالت bare، ورود به سیستم (login) اشتراک شما را نیز نمی‌خواند، بنابراین ابتدا ANTHROPIC_API_KEY را در محیط تنظیم کنید:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

یک plugin که با --plugin-dir بارگذاری می‌شود، نام خود را از .claude-plugin/plugin.json می‌گیرد و بدون آن manifest، نام آن از روی دایرکتوری‌اش انتخاب می‌شود. یک plugin.json با "name": "team-skills" در کنار کاتالوگ در مخزن skillها commit کنید، وگرنه دستور بالا باید به جای آن /agent-skills:api-review را فراخوانی کند.

با --output-format stream-json، رویداد system/init گزارش می‌دهد که کدام pluginها بارگذاری شده‌اند و یک آرایه plugin_errors برای آن‌هایی که بارگذاری نشده‌اند حمل می‌کند. این رویداد stream را باز می‌کند مگر اینکه رویدادهای startup زودتر بیایند. اگر plugin_errors خالی نبود، job مربوط به CI را با شکست مواجه کنید. این کار باعث شناسایی pinهایی می‌شود که به revisionای اشاره دارند که دیگر وجود ندارد؛ در غیر این صورت، agent به‌طور بی‌سروصدا قوانین داخلی شما را نادیده می‌گیرد.

یک مهارت اشتراکی، دستوری اجرایی است

دو ویژگی این موضوع را به واقعیت تبدیل می‌کنند و هر دو زمانی که فایل از تیم دیگری می‌آید، اهمیت دارند.

نخست، یک SKILL.md می‌تواند پیش از آنکه مدل چیزی را بخواند، دستورات shell را اجرا کند. خطی مانند این در بدنه، پیش‌پردازش محسوب می‌شود:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

این دستور روی ماشینی که مهارت را بارگذاری می‌کند اجرا شده و خروجی آن جایگزین جای‌نگهدار (placeholder) در متنی می‌شود که مدل دریافت می‌کند. یک بلوک محصور با سه backtick که با ! دنبال شود، چندین دستور را به همین روش اجرا می‌کند. در زمان اجرا، هیچ درخواستی برای تأیید این موارد از کاربر پرسیده نمی‌شود. Claude Code هر دستور را با قوانین دسترسی شما تطبیق می‌دهد. خارج از حالت auto، دستوری که آن قوانین اجازه ندهند، مهارت را متوقف می‌کند، مگر اینکه مهارت آن را از طریق ویژگی دوم در ادامه، پیش‌تأیید کرده باشد. قوانین Deny و ask همچنان بر آن پیش‌تأیید اولویت دارند. خواندن یک مهارت اشتراکی به معنای خواندن جایگزینی‌های دستوری آن است.

دوم، frontmatter می‌تواند ابزارها را پیش‌تأیید کند. allowed-tools ابزارهای فهرست‌شده را بدون درخواست مجوز برای نوبتی که مهارت را فراخوانی کرده، اعطا می‌کند. اعتماد به فضای کاری (Workspace trust) مانع این اعطا نمی‌شود: Claude Code فیلد allowed-tools یک مهارت پروژه را حتی در یک -p که در پوشه‌ای اجرا شده که هیچ‌کس به آن اعتماد نکرده است، اعمال می‌کند. مستندات Claude Code پیامد آن را به‌وضوح بیان می‌کند: یک مهارت می‌تواند دسترسی گسترده به ابزارها را به خود اعطا کند، بنابراین پیش از اجرای Claude Code در یک مخزن، allowed-tools مهارت‌های موجود در آن را بررسی کنید. یک سازمان می‌تواند با تنظیم allowManagedPermissionRulesOnly در تنظیمات مدیریت‌شده، این فیلد را از مهارت‌های پروژه و شخصی سلب کند؛ این کار به Claude Code نسخه 2.1.282 یا بالاتر نیاز دارد.

بنابراین، با به‌روزرسانی مهارت دقیقاً مانند به‌روزرسانی وابستگی‌ها (dependency) برخورد کنید. هر جا که مکانیزم اجازه می‌دهد، نسخه را با commit دقیق قفل (pin) کنید، زیرا یک tag قابل جابه‌جایی است و یک branch طبق تعریف همواره در حال تغییر است. روی یک ماشین با محدودیت‌های امنیتی، "disableSkillShellExecution": true در تنظیمات، تمام جایگزینی‌های دستوری را با متن تحت‌اللفظی [shell command execution disabled by policy] جایگزین می‌کند و به جای اجرای آن‌ها، این متن را اعمال می‌کند؛ این تنظیم از طریق تنظیمات مدیریت‌شده اعمال می‌شود و کاربر نمی‌تواند آن را لغو کند. مهارت‌های بسته‌بندی‌شده (bundled) و مدیریت‌شده از این تنظیم مستثنی هستند.

همین دقت باید در مورد آنچه یک مهارت می‌خواند نیز اعمال شود. مهارتی که env را اجرا می‌کند یا یک فایل پیکربندی را باز می‌کند، هر آنچه را که پیدا کند به context مدل وارد می‌کند؛ این همان شکستی است که در دور نگه داشتن اسرار از عامل‌هایی که اجرا می‌کنید پوشش داده شده است. مهارتی که صفحه‌ای را واکشی می‌کند یا کوئری اجرا می‌کند، همان سطح از افشاگری را به سمت بیرون دارد، زیرا متن بازیابی‌شده دقیقاً مانند دستوراتی که نوشته‌اید در context قرار می‌گیرد؛ مرزی که ارزش دارد پیش از اشاره دادن یک عامل به نمونه SearXNG خود برای جستجوی وب درباره آن مطالعه کنید.

هنگام ارتقای نسخه چه مواردی را بررسی کنیم

  • تفاوت (diff) در بدنه هر SKILL.md، زیرا آن متن دستوری است که عامل (agent) شما از آن پیروی خواهد کرد.
  • تمام جایگزینی‌های دستور (command substitution)، زیرا هنگام بارگذاری مهارت، روی سیستم شما اجرا می‌شوند.
  • هر تغییری در allowed-tools، زیرا آن خط بدون پرسش از شما، دسترسی به ابزارها را اعطا می‌کند.
  • اجرای تست پشت تگ. اگر مخزن اشتراکی تست‌های smoke خود را در CI اجرا می‌کند، تگی که به آن متصل می‌شوید باید دارای یک اجرای موفق (سبز) باشد.

بازبینی‌کننده‌ای که نمی‌تواند کل تفاوت را در 10 دقیقه بخواند، در حال بررسی مهارتی است که بیش از حد بزرگ شده است. آن را تقسیم کنید. همین استدلال در مورد اسناد مخزنی که عامل‌های شما می‌خوانند نیز صدق می‌کند: قوانین پایدار را در فایل‌های توصیف‌شده در تفکیک AGENTS.md و HUMAN.md و استدلال‌های معماری را در فایل DESIGN.md که برای عامل‌ها نوشته شده نگه دارید و اجازه دهید مهارت‌ها روی رویه‌های محدود متمرکز بمانند.

وقتی تغییر مدل یا ابزار باعث از کار افتادن یک مهارت می‌شود

گاهی اوقات بدون اینکه کسی تغییری در یک مهارت ایجاد کند، زیرساخت‌های آن تغییر می‌کنند. ارتقای مدل ممکن است نحوه پیروی از دستورالعمل‌های طولانی را تغییر دهد؛ در نتیجه مهارتی که قبلاً تا مرحله 9 پیش می‌رفت، ممکن است دیگر به آن مرحله نرسد. یک ابزار خط فرمان ممکن است نام یک flag را تغییر دهد؛ در این صورت agent از flag قدیمی استفاده می‌کند، با خطا مواجه می‌شود و سعی می‌کند با بداهه‌پردازی آن را رفع کند. یک URL ارجاع‌داده‌شده ممکن است با خطای 404 مواجه شود. همچنین، نحوه انتخاب مهارت‌ها توسط harness تغییر می‌کند و باعث می‌شود description که قبلاً در انتخاب برنده می‌شد، دیگر انتخاب نشود. وقتی یک رویه به این شکل زودتر از موعد متوقف می‌شود، با تغییر نسخه (version bump) مشکل حل نمی‌شود؛ بلکه دستورالعمل‌ها به ساختاری نیاز دارند که اجرای مراحل پایانی را اجباری کند. این همان رویکردی است که در مهارت unlazy و روش Depth Tree آن دنبال می‌شود.

به همین دلیل است که در این ساختار، smoke test اهمیت حیاتی دارد. تست هر مهارت را هم به‌صورت زمان‌بندی‌شده و هم هنگام push اجرا کنید. گوگل به همین دلیل کارهای ارزیابی خود را به‌صورت هفتگی روی کل کتابخانه اجرا می‌کند؛ برای تیمی با 10 مهارت، یک cron job هفتگی روی یک VPS کوچک کافی است. این تنها راهی است که باعث می‌شود پیش از توسعه‌دهنده، شما از خرابی مطلع شوید.

قابلیت حمل (Portability) نیز کمک‌کننده است. مشخصات Agent Skills تعداد کلیدهای frontmatter را به 6 عدد محدود می‌کند؛ بنابراین مهارتی که طبق آن مشخصات نوشته شده باشد، در ابزارهایی فراتر از ابزاری که برای آن ساخته شده نیز بارگذاری می‌شود، در حالی که هر کلید اختصاصی برای یک harness، در واقع شرط‌بندی روی یک فروشنده خاص است. نوشتن مهارت‌هایی که پس از تعویض مدل همچنان کار کنند، خود یک تخصص مجزا است که در اجرای یک مهارت روی هر مدلی به آن پرداخته شده است.

FAQ

چگونه می‌توانم یک مهارت عامل (agent skill) را بین چندین مخزن به اشتراک بگذارم؟

مهارت را در یک مخزن git اختصاصی قرار دهید، نسخه‌های آن را تگ کنید و به جای کپی کردن فایل، هر پروژه مصرف‌کننده را به یک تگ ارجاع دهید. دو مکانیزم برای این کار وجود دارد. یک git submodule یک commit دقیق را ذاتاً (by design) ثبت می‌کند و یک symlink از .claude/skills/<name> به داخل submodule باعث می‌شود که آن به عنوان یک مهارت معمولی پروژه بارگذاری شود. یک بازارچه افزونه (plugin marketplace) همین کار را از طریق /plugin انجام می‌دهد، که در آن pin در فایل .claude/settings.json مخزن مصرف‌کننده اعلام می‌شود. هر دو روش، نسخه را در تاریخچه git ثبت می‌کنند، بنابراین می‌توانید پاسخ دهید که کدام دستورالعمل‌ها منجر به اجرای یک عامل خاص شده‌اند.

آیا می‌توانم یک مهارت عامل را به نسخه خاصی محدود (pin) کنم؟

نه از داخل SKILL.md، زیرا آن frontmatter فاقد کلید version است. این محدودسازی باید از لایه اطراف فایل اعمال شود. یک git submodule ذاتاً (by design) یک commit دقیق را pin می‌کند. در بازارچه افزونه Claude Code، منبع افزونه برای یک branch یا تگ، ref و برای یک commit دقیق، sha را می‌پذیرد و در صورت وجود هر دو، sha اولویت دارد. خود منبع بازارچه برای یک branch، تگ یا در نسخه Claude Code v2.1.324 یا بالاتر، یک commit SHA کامل با حروف کوچک، ref را می‌پذیرد. استفاده از commit برای pin کردن را ترجیح دهید، زیرا یک تگ می‌تواند پس از بررسی شما تغییر کند.

یک تست دود (smoke test) برای مهارت باید چه چیزی را تایید کند؟

روی چیزی پایدار تایید (assert) انجام دهید. مهارت را به صورت غیرتعاملی در برابر یک fixture که حاوی یک خطای شناخته‌شده است اجرا کنید، سپس بررسی کنید که یک شناسه خاص در خروجی ظاهر می‌شود؛ برای مثال، یک rule id که مهارت باید گزارش کند. درخواست خروجی ساختاریافته با --output-format json و --json-schema باعث می‌شود که بررسی دقیق باشد و jq -e در صورت نبود مقدار، اسکریپت را با شکست مواجه می‌کند. هرگز روی یک جمله کامل تایید انجام ندهید، زیرا مدل پاسخ‌های خود را بین دفعات اجرا بازنویسی می‌کند.

آیا نصب یک مهارت اشتراکی از مخزن تیم دیگر امن است؟

با آن به عنوان یک وابستگی کد (code dependency) رفتار کنید، زیرا این یک دستورالعمل اجرایی است. یک SKILL.md می‌تواند دستورات shell را در زمان بارگذاری از طریق فرم جایگزینی دستور ! اجرا کند و فیلد allowed-tools در frontmatter می‌تواند ابزارها را بدون پرسش تأیید کند. در هر به‌روزرسانی (bump)، تفاوت‌ها (diff) را بخوانید، به جای branch به یک commit دقیق pin کنید و منبعی را ترجیح دهید که تیم خودتان کنترل می‌کند. در ماشین‌های مدیریت‌شده، "disableSkillShellExecution": true در تنظیمات، اجرای جایگزینی دستورات در مهارت‌های کاربر، پروژه، افزونه و دایرکتوری‌های اضافی را متوقف می‌کند؛ مهارت‌های بسته‌بندی‌شده و مدیریت‌شده از این قاعده مستثنی هستند.

آیا یک مهارت اشتراکی در عامل‌هایی غیر از Claude Code کار می‌کند؟

این به frontmatter مورد استفاده شما بستگی دارد. مشخصات Agent Skills شش کلید را تعریف می‌کند: name، description، license، compatibility، metadata و allowed-tools. مهارتی که به این موارد محدود باشد، در ابزارهایی که این مشخصات را پیاده‌سازی می‌کنند بارگذاری می‌شود و همچنین بدون تغییر در Claude Code نیز بارگذاری خواهد شد. کلیدهای خاصِ یک ابزار (harness-specific) و ویژگی‌های بدنه فراتر از این مشخصات، در جاهای دیگر نادیده گرفته یا رد می‌شوند، بنابراین آن‌ها را از هر مهارتی که قصد دارید به طور گسترده به اشتراک بگذارید، دور نگه دارید.

آیا این مقاله مفید بود؟