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

نحوه اشتراک‌گذاری مهارت‌های عامل (Agent Skills) بین مخازن

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

این کار شامل چهار بخش است: یک منبع واحد برای حقیقت (source of truth)، یک نسخه متصل برای هر مخزن، یک تست دود برای هر مهارت، و یک مسیر بازبینی. مطالب زیر توضیح می‌دهند که چرا هر بخش وجود دارد، ابزارهایی که در سال 2026 عرضه می‌شوند چه نقشی در این زمینه دارند، و چگونه می‌توان کل این سیستم را روی یک git remote خودمیزبان (self-hosted) بدون نیاز به سرویس‌های خارجی پیاده‌سازی کرد.

یک مهارت عامل، پوشه‌ای است که شامل یک فایل SKILL.md به همراه تمامی اسکریپت‌ها و فایل‌های مرجع مورد نیاز آن است. اگر این واحد برای شما جدید است، ابتدا چیستی مهارت عامل و نحوه عملکرد SKILL.md را مطالعه کنید. این صفحه به زنجیره تأمین پیرامون آن واحد می‌پردازد.

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

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

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

گزینه میانی برای یک تیم کاربردی‌تر است، زیرا در مخزن 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 وجود ندارد. هیچ چیزی درون فایل ثبت نمی‌کند که کدام نسخه جدیدتر است. این موضوع منطقی است، زیرا یک مهارت بیشتر یک سند (document) محسوب می‌شود تا یک بسته (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.5.22 در تاریخ 5 اوت 2026)، مهارت‌ها (skills) را از یک مخزن git در هر دایرکتوری که agent شما انتظار دارد نصب می‌کند و ساختار بیش از هفتاد agent مختلف را می‌شناسد. دستور npx skills add <repo> برای نصب، npx skills update برای ارتقا و npx skills list برای نمایش موارد نصب‌شده استفاده می‌شود. سوابق موارد نصب‌شده به‌جای هر مخزن، یک‌بار برای هر کاربر نگهداری می‌شود. یک درخواست باز در آن پروژه (issue 283) خواستار دستور skills install است که تمام مهارت‌های ردیابی‌شده را از فایل قفل مجدداً نصب کند تا دستگاه دوم به همان مجموعه دست یابد. این درخواست را به‌عنوان یک گزارش وضعیت در نظر بگیرید. ایده فایل قفل نهایی شده است، اما بخش مربوط به هر پروژه هنوز در حال توسعه است.

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

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

دستور --locked با نسخه‌های وابستگی (dependency) که crate با آن‌ها منتشر شده است، build را انجام می‌دهد تا build دچار تغییرات ناخواسته نشود. دستور skillspec --version باید 0.2.2 را چاپ کند. عددی متفاوت به این معنی است که یک باینری قدیمی‌تر در PATH شما اولویت پیدا کرده است.

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

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

شما مجبور نیستید یکی از آن‌ها را انتخاب کنید. در زیر آن‌ها یک ساختار واحد وجود دارد و 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 می‌پذیرد و sha را قبول نمی‌کند. منبع افزونه در داخل کاتالوگ هر دو را می‌پذیرد، و هنگامی که هر دو تنظیم شده باشند، sha مقدار نهایی و موثر برای pin کردن است. بنابراین، pin کردن روی یک commit دقیق، در ورودی کاتالوگ انجام می‌شود.

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

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

هم‌تیمی‌ای که به پوشه پروژه اعتماد دارد، برای نصب marketplace ترغیب می‌شود و افزونه بدون نیاز به صفحه ویکی برای راهنمایی، برای او فعال می‌گردد. سپس مهارت‌ها (skills) به /team-skills:api-review پاسخ می‌دهند، زیرا مهارت‌های افزونه بر اساس نام افزونه namespace می‌شوند و نمی‌توانند با مهارت‌های پروژه که نام مشابهی دارند تداخل پیدا کنند. پس از اینکه یک tag جدید push کردید، مصرف‌کنندگان با /plugin marketplace update acme-agents به‌روزرسانی می‌کنند و سپس اگر خلاصه نصب درخواست کرد، /reload-plugins را اجرا می‌کنند.

نوشتن یک تست smoke برای یک مهارت

تست smoke یک اجرای اسکریپت‌شده از agent روی یک fixture با یک خطای شناخته‌شده، به‌علاوه یک assertion است. Claude Code به‌صورت غیرتعاملی با -p اجرا می‌شود و یک مهارت که توسط کاربر فراخوانی شده در آنجا کار می‌کند: /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 این است که مهارت، نام آن را ذکر کند. jq -e زمانی که فیلتر آن null تولید می‌کند، با کد خروجی غیرصفر خارج می‌شود؛ بنابراین مهارتی که دیگر خطای کاشته‌شده را شناسایی نکند، اسکریپت را با شکست مواجه می‌کند. خود claude نیز در صورت شکست اجرا، با کد خروجی غیرصفر خارج می‌شود و set -euo pipefail هر دو نوع شکست را به یک تست ناموفق تبدیل می‌کند.

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

در CI، از --bare استفاده کنید. بدون آن، claude -p همان contextای را بارگذاری می‌کند که یک نشست تعاملی بارگذاری می‌کرد، شامل hookها، پلاگین‌ها و CLAUDE.md از ماشینی که روی آن اجرا می‌شود؛ بنابراین پیکربندی شخصی یک همکار می‌تواند نتیجه را تغییر دهد. حالت bare تمام قابلیت‌های auto-discovery را نادیده می‌گیرد، که به این معنی است که مهارتی که در حال تست آن هستید را نیز نادیده می‌گیرد، پس آن را به‌طور صریح بارگذاری کنید. حالت 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

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

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

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

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

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

این دستور روی ماشینی که مهارت را بارگذاری می‌کند اجرا شده و خروجی آن جایگزین جای‌نگهدار (placeholder) در متنی می‌شود که مدل دریافت می‌کند. یک بلوک محصور با سه backtick که با ! دنبال شود، چندین دستور را به همین شیوه اجرا می‌کند. هیچ‌کس در زمان اجرا این موارد را تأیید نمی‌کند. خواندن یک مهارت اشتراکی به معنای خواندن جایگزینی‌های دستوری (command substitutions) آن است.

دوم، frontmatter می‌تواند ابزارها را از پیش تأیید کند. allowed-tools ابزارهای فهرست‌شده را بدون نمایش اعلان مجوز برای نوبتی که مهارت را فراخوانی کرده است، مجاز می‌شمارد. برای یک مهارت پروژه، این مجوز زمانی اعمال می‌شود که شخصی کادر محاوره‌ای اعتماد به workspace را برای آن پوشه بپذیرد. مستندات Claude Code پیامد این موضوع را به‌صراحت بیان می‌کند: پیش از اعتماد به یک مخزن، مهارت‌های پروژه را بررسی کنید، زیرا یک مهارت می‌تواند به خود دسترسی گسترده به ابزارها بدهد.

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

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

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

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

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

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

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

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

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

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