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

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

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

این کار شامل چهار بخش است: یک منبع واحد برای حقیقت (source of truth)، یک نسخه پین‌شده برای هر مخزن، یک تست smoke برای هر مهارت و یک مسیر بازبینی. مطالب زیر توضیح می‌دهند که چرا هر بخش وجود دارد، ابزارهایی که در سال 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)

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

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

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

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

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

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

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

فایل‌های Lock. ابزار خط فرمان 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 است که تمام مهارت‌های ردیابی‌شده را از فایل lock دوباره نصب کند تا دستگاه دوم به همان مجموعه دست یابد. این درخواست را به‌عنوان یک گزارش وضعیت در نظر بگیرید. ایده فایل lock تثبیت شده است، اما بخش مربوط به هر پروژه هنوز در حال توسعه است.

مشخصات و تست‌ها. 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 با آن‌ها منتشر شده است بیلد می‌شود تا بیلد تحت تأثیر تغییرات ناخواسته قرار نگیرد. دستور skillspec --version باید 0.2.2 را چاپ کند. عددی متفاوت به این معنی است که یک باینری قدیمی‌تر در PATH شما اولویت پیدا کرده است.

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

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

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

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

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

ساختاری برای تیم‌های کوچک روی یک ریموت git شخصی‌سازی‌شده (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

اگر ریموت شما 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، سپس مسیر، و در نهایت نزدیک‌ترین tag:

 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 نیز جای می‌گیرد.

پین کردن با استفاده از یک بازارچه افزونه (plugin marketplace)

اگر ترجیح می‌دهید از همه توسعه‌دهندگان نخواهید که submodules را یاد بگیرند، سیستم افزونه Claude Code توزیع را برای شما انجام می‌دهد و با یک remote که خودتان میزبانی می‌کنید، کار می‌کند. یک کاتالوگ در مسیر .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"
      }
    }
  ]
}

در اینجا دو منبع متفاوت در کار هستند و اشتباه رایج، جابه‌جا گرفتن آن‌هاست. منبع بازارچه، یعنی جایی که خود کاتالوگ از آن دریافت می‌شود، برای branch یا tag مقدار ref را می‌پذیرد و sha را قبول نمی‌کند. منبع افزونه در داخل کاتالوگ هر دو را می‌پذیرد، و زمانی که هر دو تنظیم شده باشند، sha پینِ موثر خواهد بود. بنابراین، پین کردن روی یک commit دقیق، در ورودی کاتالوگ انجام می‌شود.

سپس هر مخزن مصرف‌کننده، بازارچه را در فایل .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
  }
}

هم‌تیمی‌ای که به پوشه پروژه اعتماد دارد، برای نصب بازارچه ترغیب می‌شود و افزونه بدون نیاز به صفحه wiki برای راهنمایی، برای او فعال می‌گردد. سپس مهارت‌ها (skills) به /team-skills:api-review پاسخ می‌دهند، زیرا مهارت‌های افزونه بر اساس نام افزونه namespace می‌شوند و نمی‌توانند با یک مهارت پروژه که نام مشابهی دارد، تداخل پیدا کنند. پس از اینکه یک tag جدید push کردید، مصرف‌کنندگان با /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 نگذارید. روی شناسه‌ای (identifier) که skill باید تولید کند یا روی فیلدی از یک schema که درخواست کرده‌اید assertion بگذارید و fixture را کوچک نگه دارید تا هزینهٔ اجرا پایین بماند.

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

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 به نسخه‌ای اشاره داشت که دیگر وجود ندارد، شناسایی شود؛ در غیر این صورت، agent به‌آرامی قوانین داخلی شما را نادیده می‌گیرد.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

FAQ

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

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

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

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

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

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

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

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

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

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