SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor

ریپوزٹریز میں agent skills کا drift کیسے روکیں

8 ریپوزٹریز میں skill کی نقول بدلنے لگیں تو ایک shared repo، tag اور ہر project کے لیے pinned version استعمال کریں، smoke tests اور review path کے ساتھ۔

repos کے درمیان agent skills کا اشتراک کیسے کریں

repos کے درمیان agent skills کا اشتراک کرنے کے لیے فائل کی نقل بنانا بند کریں اور اس پر dependency قائم کریں۔ ایک skills repository رکھیں، اسے tag کریں، اور ہر project کو کسی tag پر pin کریں۔ پھر ہر skill کے لیے smoke test شامل کریں، اور ہر bump کا اسی طرح review کریں جیسے dependency bump کا review کرتے ہیں۔

اس عمل کے چار حصے ہیں: shared source of truth، ہر repository کے لیے pinned version، ہر skill کے لیے smoke test، اور review path۔ ذیل میں بتایا گیا ہے کہ ہر حصہ کیوں ضروری ہے، 2026 میں shipping tools اس سلسلے میں کیا سہولت دیتے ہیں، اور self-hosted git remote پر پورا نظام کیسے بنایا جائے، جس میں کسی بیرونی git host یا package registry کی ضرورت نہ ہو۔ smoke tests اس سے مستثنیٰ ہیں۔ وہ Claude Code چلاتے ہیں، جو ہر request کو model API پر بھیجتا ہے، اس لیے یہ مرحلہ اب بھی آپ کے server سے باہر request بھیجتا ہے۔

agent skill ایک ایسا folder ہے جس میں SKILL.md file اور اس کے لیے درکار scripts اور reference files شامل ہوتی ہیں۔ اگر یہ unit آپ کے لیے نئی ہے تو پہلے agent skill کیا ہے اور SKILL.md کیسے کام کرتی ہے پڑھیں۔ یہ صفحہ اس unit کے گرد supply chain کے بارے میں ہے۔

مہارت کہاں موجود ہوتی ہے، اور اسے شیئر کرنا مشکل کیوں ہے

Claude Code دیگر مقامات کے علاوہ درج ذیل مقامات سے بھی skills لوڈ کرتا ہے، اور skills documentation میں ہر path درج ہے۔

  • .claude/skills/<skill-name>/SKILL.md managed settings directory کے اندر enterprise location ہے۔ جن مشینوں پر کوئی organization اسے deploy کرتی ہے، وہاں یہ ہر user کے لیے load ہوتی ہے۔
  • ~/.claude/skills/<skill-name>/SKILL.md ذاتی location ہے۔ یہ آپ کے تمام projects میں load ہوتی ہے، کسی اور کے projects میں نہیں۔
  • .claude/skills/<skill-name>/SKILL.md project level location ہے۔ جو بھی اس repository کو checkout کرے، اس کے لیے یہ load ہوتی ہے۔
  • <plugin>/skills/<skill-name>/SKILL.md plugin کے اندر شامل ہوتی ہے۔ جہاں بھی وہ plugin enabled ہو، وہاں یہ load ہوتی ہے۔

Claude Code nested project directories، --add-dir کے ساتھ فراہم کردہ directories، اور آپ کے claude.ai account کے لیے enabled skills سے بھی skills load کرتا ہے۔

ٹیم کے لیے project level location مفید ہے، کیونکہ اسے commit کیا جا سکتا ہے اور repository clone کرنے والے ہر شخص کو یہ مل جاتی ہے۔ مسئلہ بھی یہیں سے شروع ہوتا ہے۔ .claude/skills/ میں موجود skill ایک repository سے وابستہ ہوتی ہے۔ آپ کے پاس آٹھ repositories ہیں۔ اس لیے یہ skill آٹھ بار copy ہوتی ہے۔

Frontmatter بھی کوئی مدد فراہم نہیں کرتا۔ Agent Skills spec چھ keys کی اجازت دیتی ہے، اور وہ distribution paths جو اس spec کو نافذ کرتی ہیں، کسی دوسری key کے استعمال پر فہرست دکھاتی ہیں:

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

غور کریں کہ کیا موجود نہیں ہے: version key موجود نہیں ہے۔ Version کو metadata کے تحت درج کیا جا سکتا ہے، لیکن spec میں dependency pin یا update mechanism کی کوئی تعریف نہیں ہے۔ یہ مناسب ہے، کیونکہ skill package کے بجائے ایک document ہوتی ہے۔ اس کا مطلب یہ ہے کہ versioning فائل کے گرد موجود layer سے آنی چاہیے، اور اس layer کی ذمہ داری آپ کی ہے۔

مسئلہ 1: خاموشی سے مختلف ہونے والی 8 نقول

پہلے دن copy-paste کام کرتا ہے۔ ساٹھویں دن یہ ناکام ہو جاتا ہے۔ کوئی شخص payments repo میں غلط ہدایت درست کرتا ہے، لیکن باقی 7 میں تبدیلی نہیں کرتا۔ کوئی دوسرا شخص orders میں pagination کے بارے میں ایک قاعدہ شامل کر دیتا ہے۔ اب ایک ہی skill name کی بنیاد پر دو مختلف reviews ملتے ہیں، اس بات پر منحصر ہے کہ agent نے کس directory سے آغاز کیا تھا، اور کسی بھی developer کو اس کا علم نہیں ہوتا۔

یہ failure خاموش رہتا ہے کیونکہ کوئی error state موجود نہیں ہوتی۔ skill نثری متن پر مشتمل ہوتی ہے۔ پرانی ہدایت پراعتماد مگر غلط جواب پیدا کرتی ہے، اور یہی مہنگی قسم کی غلطی ہے۔ agent میں ایسا کچھ نہیں جو آپ کی copy کا کسی اور کی copy سے موازنہ کرے۔ اس لیے واحد signal یہ ہوتا ہے کہ کوئی شخص محسوس کرے کہ 2 repos میں اختلاف ہے۔

مسئلہ دو: کوئی version pin نہیں کیا جاتا

ٹیم skills کو ایک جگہ رکھنے کے باوجود، انہیں شیئر کرنے کا عام طریقہ copy step ہوتا ہے: setup script، onboarding دستاویز میں موجود curl لائن، یا ایسا shell alias جو کسی folder کو sync کرتا ہے۔ یہ تمام طریقے اس وقت branch کے head پر موجود version ہی install کرتے ہیں۔

اس کا مطلب ہے کہ ایک ہی application کے اسی commit پر کام کرنے والے 2 developers مختلف instructions چلا سکتے ہیں، کیونکہ انہوں نے مختلف دنوں میں sync کیا تھا۔ اس کا یہ مطلب بھی ہے کہ agent کے ناکام run کے بعد آپ اس اہم سوال کا جواب نہیں دے سکتے: یہ کس version کی skill سے تیار ہوا؟ ریکارڈ شدہ revision کے بغیر run دوبارہ قابلِ تولید نہیں رہتا، اس لیے bug report پر مؤثر کارروائی نہیں کی جا سکتی۔

مسئلہ تین: کسی کو معلوم نہیں کہ skill اب بھی کام کرتی ہے

skill کا کوئی compiler نہیں ہوتا۔ یہ model کے لیے دی گئی ہدایات ہوتی ہیں، اس لیے file byte for byte بالکل یکساں رہنے کے باوجود یہ کام کرنا بند کر سکتی ہے۔ model upgrade سے یہ بدل جاتا ہے کہ ایک طویل instruction پر کتنی درستگی سے عمل کیا جاتا ہے۔ skill جس command line tool کو استعمال کرتی ہے، وہ کسی flag کا نام بدل دیتا ہے۔ reference file میں موجود URL، 404 واپس کرنا شروع کر دیتا ہے اور agent error page کی بنیاد پر کام کرتا ہے۔

ان میں سے کسی صورت میں بھی خرابی واضح طور پر ظاہر نہیں ہوتی۔ agent اب بھی جواب دیتا ہے۔ فرق صرف یہ ہوتا ہے کہ جواب گزشتہ ماہ کے مقابلے میں بدتر ہوتا ہے، اور ہر pull request کے بعد اسے محسوس کرنا مشکل ہوتا ہے۔

2026 میں جاری ہونے والے ٹولز کیا حل کرتے ہیں

کئی حل اب دستیاب ہو رہے ہیں، اور ان کے درمیان اس بات پر اتفاق نہیں کہ version کہاں محفوظ ہونا چاہیے۔

Lockfiles۔ Vercel Labs کا skills command line tool (vercel-labs/skills، MIT licensed، 9 October 2026 تک v1.7.2) git repository سے skills انسٹال کرکے اس directory میں رکھتا ہے جہاں آپ کا agent انہیں متوقع طور پر تلاش کرتا ہے۔ یہ ستر سے زیادہ agents کا layout جانتا ہے۔ npx skills add <repo> انسٹال کرتا ہے، npx skills update upgrade کرتا ہے، اور npx skills list دکھاتا ہے کہ آپ کے پاس کیا موجود ہے۔ یہ دو lock files رکھتا ہے۔ ایک global file ~/.agents/.skill-lock.json اس چیز کا ریکارڈ رکھتی ہے جو کسی ایک user نے انسٹال کی ہے۔ 20 February 2026 سے، project scope میں انسٹال کرنے پر project root میں skills-lock.json بھی لکھی جاتی ہے، اور tool کے source code کے مطابق اس file کو version control میں check in کرنا چاہیے۔ npx skills experimental_install اس file سے project کی skills بحال کرتا ہے۔ skills install command کے ذریعے کسی دوسری machine پر global lock file بحال کرنے کی درخواست، یعنی issue 283، 5 November 2026 کو planned نہ ہونے کی وجہ سے بند کر دی گئی؛ maintainer اسے issue 549 جیسی ہی درخواست قرار دیتا ہے۔ دونوں کو status report کے طور پر پڑھیں۔ Per-project lockfile موجود ہے۔ جاری شدہ v1.8.1 میں restore command ابھی بھی help میں experimental کے طور پر درج ہے، لیکن بغیر source کے npx skills install بھی project lockfile بحال کرتا ہے۔

Specs اور tests۔ SkillSpec دوسرا زاویہ اختیار کرتا ہے۔ یہ SKILL.md کو بھروسا کرنے کے لیے نثر کے بجائے جانچنے کے لیے contract سمجھتا ہے۔ اس کا بیان کردہ مقصد skills کو "followable, testable, and provable" بنانا ہے۔ skillspec doctor <path> بتاتا ہے کہ agent کے thread چھوڑنے کا امکان کہاں ہے۔ skillspec boundary map <path> دکھاتا ہے کہ skill میں کیا شامل ہے، اور skillspec boundary assess <path> بتاتا ہے کہ یہ کن چیزوں تک رسائی حاصل کر سکتی ہے، جنہیں risk کے لحاظ سے ترتیب دیا جاتا ہے۔ یہ Rust crate ہے اور MIT یا Apache 2.0 کے تحت dual licensed ہے۔ Version 0.2.2، 29 July 2026 کو publish ہوا، اور 10 October 2026 تک crates.io پر اب بھی جدید ترین version ہے۔ جدید ترین version کے بجائے مقررہ version انسٹال کریں:

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

Cargo 1.100 کے بعد، جو 12 November 2026 کو جاری ہوا، cargo install packaged lockfile کو default طور پر استعمال کرتا ہے، اور --locked کوئی عمل نہیں کرتا۔ skillspec --version کو 0.2.2 دکھانا چاہیے۔ مختلف number کا مطلب ہے کہ آپ کے PATH میں پہلے موجود کوئی پرانا binary ترجیح حاصل کر رہا ہے۔

Vendor practice۔ Google نے google/skills میں skills بنانے کے طریقے کو how it builds, tests and scales agent skills میں بیان کیا ہے۔ scale کو الگ رکھیں تو mechanism عام continuous integration (CI) ہے۔ ہر skill merge ہونے سے پہلے frontmatter metadata، line count، directory layout اور naming کے لیے linters سے گزرتی ہے۔ Link checker کسی بھی ایسے URL پر build ناکام کر دیتا ہے جو 404 واپس کرے؛ اس سے وہ بظاہر درست link بھی پکڑا جاتا ہے جو agent نے خود بنا لیا ہو۔ Authors کو skill کے ساتھ evaluation prompt suite اور scoring rubric بھی فراہم کرنا ہوتا ہے۔ اس کے بعد scheduled evaluation jobs پوری library کے خلاف weekly چلتی ہیں تاکہ regressions کا پتا چل سکے، اور ہر skill کا ایک named owner ہوتا ہے جس سے توقع کی جاتی ہے کہ quality کم ہونے پر وہ اسے درست کرے گا۔

تینوں جوابات کے پیچھے ایک ہی نمونہ

آپ کو ان میں سے کسی ایک کا انتخاب کرنے کی ضرورت نہیں۔ ان سب کے پیچھے ایک ہی ساخت ہے، اور سادہ git آپ کو یہ تمام سہولتیں فراہم کرتا ہے۔

  1. سچائی کا ایک ہی ماخذ۔ skill کی صرف ایک مرکزی جگہ ہوتی ہے، اور ہر repository نقل رکھنے کے بجائے اسی جگہ کا حوالہ دیتی ہے۔
  2. ہر repository کے لیے ایک مقررہ version۔ ہر project اپنے استعمال کردہ عین revision کو ریکارڈ کرتا ہے، اس لیے upgrade اس project میں ایک commit ہوتا ہے، جس کے ساتھ author اور date موجود ہوتے ہیں۔
  3. ہر skill کے لیے ایک smoke test۔ ایک قابلِ اجرا check یہ ثابت کرتا ہے کہ skill اب بھی وہ نتیجہ پیدا کرتی ہے جس کا وہ وعدہ کرتی ہے۔
  4. review کا راستہ۔ shared skill میں تبدیلی review کے مرحلے سے گزرتی ہے، اور ہر consumer اسے اختیار کرنے سے پہلے diff دیکھتا ہے۔

یہی dependency کی ساخت ہے۔ Skills کے لیے shared artifact کا تصور tooling کے اردگرد بننے والی سہولتوں سے زیادہ تیزی سے عام ہوا، اس لیے جس tooling پر آپ پہلے ہی اعتماد کرتے ہیں، اسی سے کام لینا محفوظ ترین انتخاب ہے۔

چھوٹی ٹیم کے لیے self-hosted git remote کا layout

ایک repository میں skills رکھی جاتی ہیں۔ اس میں کوئی اور چیز نہیں ہوتی، اس لیے اس کی history ہدایات کے changelog کے طور پر پڑھی جاتی ہے۔

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

Releases کے لیے tags استعمال کریں۔ annotated tags استعمال کریں، کیونکہ ان میں message اور date شامل ہوتے ہیں۔ message میں یہ وجہ لکھیں کہ consumer اس bump کو کیوں چاہے گا:

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

اگر آپ کا remote Gitea، Forgejo، GitLab یا اپنے VPS پر SSH کے ذریعے bare repository ہے، تو اس کے بعد بیان کردہ طریقہ تبدیل نہیں ہوتا۔ یہاں صرف git اور ایک symlink استعمال ہوتے ہیں۔

Git submodule کے ذریعے مخصوص commit مقرر کرنا

ایک submodule آپ کے repository کے اندر کسی دوسرے repository کا بالکل ایک commit ریکارڈ کرتا ہے۔ یہی ریکارڈ pin ہے۔ ہر استعمال کرنے والے project میں:

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 اس طریقۂ کار کا بنیادی حصہ ہے۔ Project level پر skill entry کسی دوسرے مقام پر موجود directory کی symlink ہو سکتی ہے، اور Claude Code اس symlink کی پیروی کرکے target سے SKILL.md پڑھتا ہے۔ اس طرح skill عام project skill کے طور پر load ہوتی ہے، جبکہ اس کا اصل data آپ کے منتخب کردہ commit پر submodule میں موجود رہتا ہے۔

Pin کی جانچ کریں:

git submodule status

درست line space سے شروع ہوتی ہے، پھر commit، پھر path، اور آخر میں قریب ترین tag آتا ہے:

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

شروع میں - کا مطلب ہے کہ submodule کبھی initialise نہیں کیا گیا۔ اس لیے .claude/skills/api-review کسی مقام کی طرف اشارہ نہیں کرتا اور skill خاموشی سے load نہیں ہوتی۔ اسے git submodule update --init سے درست کریں۔ شروع میں + کا مطلب ہے کہ checkout کیا گیا commit ریکارڈ شدہ commit سے مختلف ہے۔ اس صورت میں وہ developer ایسی instructions چلا رہا ہے جو کسی اور کے پاس نہیں ہیں۔ نئے clones کے لیے git clone --recurse-submodules درکار ہے، اور یہ line README میں ہونی چاہیے، کیونکہ عام clone vendor/agent-skills کو خالی چھوڑ دیتا ہے اور کوئی error ظاہر نہیں کرتا۔

Upgrade جان بوجھ کر کیا جاتا ہے، اور یہی اس طریقۂ کار کا مقصد ہے:

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 line review کا راستہ ہے۔ یہ وہی تبدیلی دکھاتی ہے جو استعمال کرنے والے ہر دوسرے repo کو نظر آئے گی، اور اسے pull request میں شامل کیا جا سکتا ہے۔

پلگ اِن marketplace کے ذریعے pinning

اگر آپ ہر developer سے submodules سیکھنے کا تقاضا نہیں کرنا چاہتے تو Claude Code plugin system distribution خود سنبھال لیتا ہے، اور یہ self-hosted remote کے ساتھ کام کرتا ہے۔ skills repository میں .claude-plugin/marketplace.json پر ایک catalog رکھیں:

{
  "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"
      }
    }
  ]
}

یہاں دو مختلف sources استعمال ہو رہے ہیں، اور انہیں آپس میں خلط ملط کرنا عام غلطی ہے۔ marketplace source، یعنی وہ جگہ جہاں سے catalog خود fetch ہوتا ہے، branch یا tag کے لیے ref قبول کرتا ہے اور Claude Code v2.1.324 یا بعد کے ورژن میں مکمل lowercase commit SHA بھی قبول کرتا ہے؛ یہ الگ sha field قبول نہیں کرتا۔ catalog کے اندر موجود plugin source دونوں قبول کرتا ہے، اور جب دونوں set ہوں تو sha مؤثر pin ہوتا ہے۔ catalog کو اس کے marketplace source کے ref کے ذریعے pin کریں، اور plugin کو catalog entry کے sha کے ذریعے۔ type names بھی مختلف ہیں۔ catalog کے اندر url سے مراد clone کرنے کے لیے git repository ہے۔ marketplace source میں url براہ راست marketplace.json file کے link کو ظاہر کرتا ہے، جبکہ git repository git ہوتی ہے۔

ہر consuming repository اپنی committed .claude/settings.json میں marketplace declare کرتی ہے:

{
  "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 project folder کے لیے workspace trust dialog قبول کرنے کے بعد کسی teammate کے لیے marketplace register کر دیتا ہے؛ انہیں یہ کام کرنے کی ہدایت دینے کے لیے wiki page کی ضرورت نہیں رہتی۔ catalog entry relative path کے بجائے git URL کی طرف اشارہ کرتی ہے، اس لیے plugin صرف repository کی settings سے install نہیں ہوتا۔ ہر teammate ایک بار claude plugin install team-skills@acme-agents --scope project چلاتا ہے، اور اس سے پہلے Claude Code بتاتا ہے کہ plugin project settings میں enabled ہے لیکن installed نہیں ہے۔ اس کے بعد skills /team-skills:api-review کے تحت دستیاب ہوتی ہیں، کیونکہ plugin skills کو plugin name کے ذریعے namespace کیا جاتا ہے اور وہ اسی نام کی project skill سے متصادم نہیں ہو سکتیں۔ نیا tag push کرنے اور catalog اور consuming repositories میں pins update کرنے کے بعد consumers /plugin marketplace update acme-agents سے refresh کرتے ہیں، پھر اگر install summary اس کا مطالبہ کرے تو /reload-plugins چلاتے ہیں۔

ایک skill کے لیے smoke test لکھنا

Smoke test کسی معلوم خرابی والے fixture کے خلاف scripted agent run اور ایک assertion پر مشتمل ہوتا ہے۔ Claude Code، -p کے ساتھ non-interactively چلتا ہے، اور وہاں user-invoked skill بھی کام کرتی ہے: prompt string میں /skill-name شامل کریں، تو run شروع ہونے سے پہلے اسے expand کر دیا جاتا ہے۔

#!/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 ایک مختصر file ہے جس میں ایک دانستہ خرابی ہوتی ہے۔ Assertion یہ ہے کہ skill اس خرابی کا نام بتائے۔ جب اس کا filter null پیدا کرتا ہے تو jq -e non-zero exit کرتا ہے، اس لیے اگر skill seeded fault کو پکڑنا بند کر دے تو script ناکام ہو جاتی ہے۔ Run ناکام ہونے پر claude خود بھی non-zero exit کرتا ہے، اور set -euo pipefail دونوں میں سے کسی failure کو failed test میں تبدیل کر دیتا ہے۔

Model مختلف runs میں اپنے جوابات مختلف الفاظ میں بیان کرتا ہے، اس لیے کبھی مکمل sentence پر assertion نہ لگائیں۔ ایسے identifier پر assertion لگائیں جسے skill سے خارج کرنے کی توقع ہو، یا اس schema کے کسی field پر جس کے لیے آپ نے output طلب کیا ہو۔ Fixture کو مختصر رکھیں تاکہ run کم لاگت والا رہے۔

CI میں --bare شامل کریں۔ اس کے بغیر claude -p وہی context load کرتا ہے جو interactive session load کرتا، جس میں hooks، plugins اور machine سے CLAUDE.md بھی شامل ہیں۔ اس لیے کسی teammate کی ذاتی configuration نتیجہ تبدیل کر سکتی ہے۔ Bare mode، directory میں --add-dir کے ذریعے واضح طور پر فراہم کی گئی .claude/skills/ کے تحت موجود skills کے علاوہ auto-discovery کو چھوڑ دیتا ہے۔ یہ اسی project skill کو بھی چھوڑ دیتا ہے جس کی آپ testing کر رہے ہیں، اس لیے اسے explicitly load کریں۔ Bare mode آپ کا subscription login بھی نہیں پڑھتا، اس لیے پہلے environment میں ANTHROPIC_API_KEY set کریں:

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-dir کے ذریعے load کیا گیا plugin اپنا نام .claude-plugin/plugin.json سے لیتا ہے، اور اس manifest کے بغیر اس کا نام اس کی directory کے نام پر رکھا جاتا ہے۔ Skills repository میں catalog کے ساتھ "name": "team-skills" کے ذریعے ایک plugin.json commit کریں، ورنہ اوپر والی command کو اس کے بجائے /agent-skills:api-review call کرنا ہوگا۔

--output-format stream-json کے ساتھ system/init event بتاتا ہے کہ کون سے plugins load ہوئے، اور ان plugins کے لیے plugin_errors array بھی شامل کرتا ہے جو load نہیں ہو سکے۔ اگر startup events پہلے نہ آئیں تو یہ stream کھول دیتا ہے۔ غیر خالی plugin_errors کی صورت میں CI job کو fail کریں۔ اس سے اس ایسے pin کا پتا چل جاتا ہے جو ایسی revision کی طرف اشارہ کرتا ہے جو اب موجود نہیں، ورنہ agent خاموشی سے آپ کے house rules نظرانداز کرتا رہتا ہے۔

مشترکہ skill قابلِ عمل ہدایت ہوتی ہے

دو خصوصیات اس بات کو لفظی طور پر درست بناتی ہیں، اور جب فائل کسی دوسری ٹیم کی طرف سے آئے تو دونوں اہم ہوتی ہیں۔

اول، ایک SKILL.md ماڈل کے کچھ بھی پڑھنے سے پہلے shell commands چلا سکتا ہے۔ متن میں اس طرح کی لائن preprocessing ہوتی ہے:

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

یہ command اس machine پر چلتی ہے جو skill load کر رہی ہو، اور اس کا output اس متن میں placeholder کی جگہ لے لیتا ہے جو ماڈل کو موصول ہوتا ہے۔ تین backticks کے بعد ! سے شروع کیا گیا fenced block بھی اسی طرح متعدد commands چلاتا ہے۔ run time پر اس میں سے کسی چیز کے لیے کوئی prompt نہیں دکھایا جاتا۔ Claude Code ہر command کو آپ کے permission rules کے خلاف چیک کرتا ہے۔ auto mode کے باہر، وہ command جس کی ان rules میں اجازت نہ ہو skill کو abort کر دیتی ہے، الا یہ کہ skill نیچے دی گئی دوسری خصوصیت کے ذریعے اسے پہلے سے approve کر دے۔ Deny اور ask rules اس pre-approval پر بھی غالب رہتے ہیں۔ مشترکہ skill پڑھنے کا مطلب اس کی command substitutions پڑھنا بھی ہے۔

دوم، frontmatter tools کو پہلے سے approve کر سکتا ہے۔ allowed-tools فہرست میں شامل tools کو اس turn کے لیے، جس نے skill کو invoke کیا ہو، permission prompt کے بغیر grant کرتا ہے۔ Workspace trust اس grant کو محدود نہیں کرتا: Claude Code کسی project skill کا allowed-tools اس وقت بھی apply کرتا ہے جب وہ -p run میں ایسی folder میں چل رہا ہو جس پر کسی نے trust نہیں کیا۔ Claude Code کی documentation اس کا نتیجہ واضح طور پر بیان کرتی ہے: skill خود کو وسیع tool access grant کر سکتی ہے، اس لیے کسی repository میں checked-in skills کے allowed-tools کا جائزہ لیں، اس سے پہلے کہ وہاں Claude Code چلائیں۔ کوئی organization managed settings میں allowManagedPermissionRulesOnly set کر کے project اور personal skills سے یہ field روک سکتی ہے۔ اس کے لیے Claude Code v2.1.282 یا اس کے بعد کا ورژن درکار ہے۔

اس لیے skill کے bump کو dependency bump کی طرح ہی handle کریں۔ جہاں mechanism اجازت دے، exact commit کے ذریعے pin کریں، کیونکہ tag منتقل کیا جا سکتا ہے اور branch تعریف کے مطابق منتقل ہوتی رہتی ہے۔ locked-down machine پر settings میں "disableSkillShellExecution": true ہر command substitution کو چلانے کے بجائے literal text [shell command execution disabled by policy] سے replace کر دیتا ہے، اور managed settings کے ذریعے apply ہونے کی صورت میں user اسے override نہیں کر سکتا۔ Bundled اور managed skills اس setting سے مستثنیٰ ہیں۔

یہی احتیاط اس چیز پر بھی لاگو ہوتی ہے جسے skill پڑھتی ہے۔ جو skill env چلاتی ہے یا config file کھولتی ہے، وہ وہاں موجود ہر چیز model کے context میں لے آتی ہے۔ یہی وہ failure ہے جس کا احاطہ ان agents سے secrets باہر رکھنا جنہیں آپ چلاتے ہیں میں کیا گیا ہے۔ جو skill کوئی page fetch کرتی ہے یا query چلاتی ہے، وہ اسی exposure کو باہر کی طرف لے جاتی ہے، کیونکہ retrieved text context میں بالکل ان instructions کی طرح پہنچتا ہے جو آپ نے لکھی ہوں۔ اس boundary کے بارے میں پڑھ لینا مفید ہے، اس سے پہلے کہ آپ web search کے لیے کسی agent کو اپنی SearXNG instance کی طرف بھیجیں۔

ورژن بڑھاتے وقت کیا پڑھیں

  • ہر SKILL.md body کا diff، کیونکہ یہی متن وہ ہدایات ہیں جن پر آپ کا agent عمل کرے گا۔
  • ہر command substitution، کیونکہ skill لوڈ ہونے پر یہ آپ کی machine پر چلتی ہیں۔
  • allowed-tools میں ہونے والی ہر تبدیلی، کیونکہ یہ لائن prompt کے بغیر tools فراہم کرتی ہے۔
  • tag کے پیچھے چلنے والا test run۔ اگر shared repository CI میں اپنے smoke tests چلاتی ہے تو جس tag پر آپ pin کر رہے ہیں، اس کے ساتھ green run منسلک ہونا چاہیے۔

جس diff کو reviewer دس منٹ میں مکمل نہ پڑھ سکے، وہ ایسے skill کا جائزہ لے رہا ہے جو بہت بڑا ہو چکا ہے۔ اسے تقسیم کریں۔ یہی اصول ان repository documents پر بھی لاگو ہوتا ہے جنہیں آپ کے agents پڑھتے ہیں: مستقل rules ان files میں رکھیں جن کی وضاحت AGENTS.md اور HUMAN.md کی تقسیم میں کی گئی ہے، architectural reasoning agents کے لیے لکھی گئی DESIGN.md میں رکھیں، اور skills کو محدود procedures تک رکھیں۔

جب کوئی model یا tool تبدیلی کسی skill کو متاثر کرے

کسی کی جانب سے skill میں ترمیم کیے بغیر بھی اس کے اندر کئی چیزیں تبدیل ہو سکتی ہیں۔ model upgrade کے بعد طویل ہدایات پر عمل کی reliability بدل جاتی ہے، اس لیے جو skill model کے step 9 تک پہنچنے پر منحصر تھی، وہ وہاں تک پہنچنا بند کر سکتی ہے۔ کوئی command line tool کسی flag کا نام بدل دیتا ہے، پھر agent پرانا flag چلاتا، error پڑھتا اور اپنی طرف سے طریقہ اختیار کرتا ہے۔ کسی حوالہ شدہ URL سے 404 response ملنا شروع ہو جاتا ہے۔ کوئی agent harness skills منتخب کرنے کا طریقہ بدل دیتا ہے، اس لیے جو description پہلے match جیتتا تھا، اب نہیں جیتتا۔ جب کوئی procedure اس طرح وقت سے پہلے ختم ہونے لگے تو version bump اسے درست نہیں کرتا۔ Instructions میں ایسی structure درکار ہوتی ہے جو آخری steps پر عمل کو یقینی بنائے۔ یہی طریقہ unlazy skill اور اس کے Depth Tree method کی بنیاد ہے۔

اسی لیے اس arrangement میں smoke test بنیادی اہمیت رکھتا ہے۔ ہر skill کا test push کے وقت ہی نہیں بلکہ مقررہ schedule کے مطابق بھی چلائیں۔ اسی وجہ سے Google ہر ہفتے پوری library پر اپنے evaluation jobs چلاتا ہے۔ 10 skills والی team کے لیے چھوٹے VPS پر weekly cron job کافی ہے۔ یہ واحد طریقہ ہے جس سے developer سے پہلے breakage کا پتا چل سکتا ہے۔

Portability بھی مدد دیتی ہے۔ Agent Skills spec frontmatter کو 6 keys تک محدود رکھتی ہے۔ اس لیے اس spec کے مطابق لکھی گئی skill اس tool کے علاوہ دوسرے tools میں بھی load ہو جاتی ہے جس کے لیے اسے لکھا گیا تھا۔ اس کے برعکس، ہر harness-specific key کسی ایک vendor پر انحصار ہے۔ ایسی skills لکھنا جو model swap کے بعد بھی کام کرتی رہیں، اپنی الگ discipline ہے۔ اس کا احاطہ کسی بھی model پر skill کو کام کرنے کے قابل بنانا میں کیا گیا ہے۔

FAQ

میں ایک ہی agent skill کو متعدد repositories میں کیسے share کر سکتا ہوں؟

skill کو ایک dedicated git repository میں رکھیں، اس میں releases کو tag کریں، اور ہر استعمال کرنے والے project میں file copy کرنے کے بجائے tag کا reference دیں۔ اس کے لیے دو طریقے کارآمد ہیں۔ git submodule ایک exact commit ریکارڈ کرتا ہے، اور .claude/skills/<name> سے submodule تک symlink اسے عام project skill کے طور پر load کرنے دیتا ہے۔ plugin marketplace یہی کام /plugin کے ذریعے کرتا ہے، جبکہ pin استعمال کرنے والی repository کے .claude/settings.json میں declare ہوتا ہے۔ دونوں طریقے version کو git history میں محفوظ رکھتے ہیں، اس لیے آپ بتا سکتے ہیں کہ کسی مخصوص agent run کے لیے کون سی instructions استعمال ہوئیں۔

کیا میں agent skill کو کسی مخصوص version پر pin کر سکتا ہوں؟

SKILL.md کے اندر سے نہیں، کیونکہ اس frontmatter میں version key موجود نہیں۔ pin اس file کے بیرونی layer سے آنا ضروری ہے۔ git submodule design کے لحاظ سے exact commit کو pin کرتا ہے۔ Claude Code plugin marketplace میں plugin source branch یا tag کے لیے ref اور exact commit کے لیے sha قبول کرتا ہے، اور دونوں موجود ہونے کی صورت میں sha کو ترجیح دی جاتی ہے۔ marketplace source خود branch، tag یا Claude Code v2.1.324 یا بعد کے versions میں مکمل lowercase commit SHA کے لیے ref قبول کرتا ہے۔ commit pin کو ترجیح دیں، کیونکہ review کے بعد tag تبدیل کیا جا سکتا ہے۔

skill کے smoke test میں کیا assert کرنا چاہیے؟

کسی مستحکم چیز پر assert کریں۔ معلوم خرابی رکھنے والے fixture کے خلاف skill کو non-interactively چلائیں، پھر جانچیں کہ output میں کوئی مخصوص identifier موجود ہے، مثلاً وہ rule id جسے skill کو report کرنا ہے۔ --output-format json اور --json-schema کے ساتھ structured output طلب کرنے سے check exact ہو جاتا ہے، جبکہ jq -e value غائب ہونے پر script کو fail کر دیتا ہے۔ مکمل sentence پر کبھی assert نہ کریں، کیونکہ model مختلف runs میں اپنے answers کو نئے الفاظ میں بیان کر سکتا ہے۔

کیا کسی دوسری team کی repository سے shared skill install کرنا محفوظ ہے؟

اسے code dependency سمجھیں، کیونکہ یہ executable instruction ہے۔ ایک SKILL.md، ! command substitution form کے ذریعے load time پر shell commands چلا سکتا ہے، اور frontmatter کا allowed-tools field prompt کے بغیر tools کو پہلے سے approve کر سکتا ہے۔ ہر bump پر diff پڑھیں، branch کے بجائے exact commit پر pin کریں، اور ایسے source کو ترجیح دیں جسے آپ کی اپنی team control کرتی ہو۔ managed machines پر settings میں "disableSkillShellExecution": true user، project، plugin اور additional-directory skills میں command substitutions کو چلنے سے روکتا ہے؛ bundled اور managed skills اس پابندی سے مستثنیٰ ہیں۔

کیا shared skill Claude Code کے علاوہ دوسرے agents میں بھی کام کرے گی؟

یہ اس بات پر منحصر ہے کہ آپ کون سا frontmatter استعمال کرتے ہیں۔ Agent Skills spec چھ keys متعین کرتی ہے: name، description، license، compatibility، metadata اور allowed-tools۔ صرف انہی keys تک محدود skill ان tools میں load ہو جاتی ہے جو اس spec کو implement کرتے ہیں، اور Claude Code میں بھی بغیر تبدیلی کے load ہو جاتی ہے۔ spec سے باہر harness-specific keys اور body features کو دوسرے tools نظرانداز یا reject کر سکتے ہیں، اس لیے جس skill کو بڑے پیمانے پر share کرنا ہو اس میں انہیں شامل نہ کریں۔

کیا یہ مضمون مفید تھا؟

#agent-skills#versioning#claude-code#team-standards#self-hosting