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

ریپوزٹریز کے درمیان agent skills کا اشتراک کیسے کریں

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

اس کام کے چار حصے ہیں: مشترکہ source of truth، ہر repository کے لیے pinned version، ہر skill کے لیے smoke test، اور review path۔ ذیل میں بتایا گیا ہے کہ ہر حصہ کیوں ضروری ہے، 2026 میں دستیاب tools اس سلسلے میں کیا سہولت دیتے ہیں، اور کسی بیرونی service کے بغیر self-hosted git remote پر پورا نظام کیسے بنایا جائے۔

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

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

Claude Code skills کو 3 جگہوں سے لوڈ کرتا ہے، اور skills documentation میں ہر path درج ہے۔

• ~/.claude/skills/<skill-name>/SKILL.md ذاتی سطح پر ہوتی ہے۔ یہ آپ کے تمام projects میں لوڈ ہوتی ہے، لیکن کسی اور کے projects میں نہیں۔
• .claude/skills/<skill-name>/SKILL.md project level پر ہوتی ہے۔ یہ اس repository کو checkout کرنے والے ہر شخص کے لیے لوڈ ہوتی ہے۔
• <plugin>/skills/<skill-name>/SKILL.md plugin کے اندر شامل ہوتی ہے۔ یہ جہاں بھی وہ plugin enabled ہو، وہاں لوڈ ہوتی ہے۔

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

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

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

غور کریں کہ کیا موجود نہیں ہے: version key موجود نہیں۔ فائل کے اندر یہ ریکارڈ نہیں ہوتا کہ کون سی copy نئی ہے۔ یہ مناسب ہے، کیونکہ 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 میں جاری ہونے والے tools کیا حل کرتے ہیں

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

Lockfiles۔ Vercel Labs کا skills command line tool (vercel-labs/skills، MIT license کے تحت، 5 August 2026 تک v1.5.22) git repository سے skills کو اس directory میں install کرتا ہے جس کی آپ کے agent کو توقع ہوتی ہے، اور یہ 70 سے زیادہ agents کا layout جانتا ہے۔ npx skills add <repo> install کرتا ہے، npx skills update upgrade کرتا ہے، اور npx skills list موجودہ skills دکھاتا ہے۔ Installed skills کا record ہر repository کے بجائے فی user ایک بار رکھا جاتا ہے۔ اس project کی ایک زیرِ غور request (issue 283) میں skills install command کا مطالبہ کیا گیا ہے، جو lock file میں درج ہر skill کو دوبارہ install کرے تاکہ دوسری machine پر بھی یہی set حاصل ہو۔ اس request کو موجودہ صورتِ حال کی رپورٹ سمجھیں۔ Lockfile کا تصور طے ہو چکا ہے۔ اس کا per-project حصہ ابھی تیار ہو رہا ہے۔

Specs and tests۔ SkillSpec دوسرا زاویہ اختیار کرتا ہے۔ یہ SKILL.md کو قابلِ اعتماد prose کے بجائے جانچنے کے لیے contract سمجھتا ہے، اور اس کا بیان کردہ مقصد skills کو "followable, testable, and provable" بنانا ہے۔ skillspec doctor <path> بتاتا ہے کہ agent کے thread چھوڑ دینے کا امکان کہاں ہے۔ skillspec boundary map <path> بتاتا ہے کہ skill کن resources تک پہنچ سکتی ہے، اور skillspec boundary assess <path> ان findings کو risk کے لحاظ سے rank کرتا ہے۔ یہ Rust crate ہے، MIT یا Apache 2.0 کے dual license کے تحت، اور 29 July 2026 تک version 0.2.2 پر ہے۔ تازہ ترین version کے بجائے pinned version install کریں:

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

--locked ان dependency versions کے ساتھ build کرتا ہے جن کے ساتھ crate publish کیا گیا تھا، اس لیے build کے دوران dependencies تبدیل نہیں ہوتیں۔ skillspec --version کو 0.2.2 print کرنا چاہیے۔ مختلف number کا مطلب ہے کہ آپ کے PATH میں اس سے پہلے موجود کوئی پرانا binary استعمال ہو رہا ہے۔

Vendor practice۔ Google نے google/skills میں skills بنانے کا طریقہ how it builds, tests and scales agent skills پر ایک post میں بیان کیا ہے۔ Scale کو الگ رکھیں تو mechanism معمول کا continuous integration (CI) ہے۔ Merge سے پہلے ہر skill frontmatter metadata، line count، directory layout اور naming کے لیے linters سے گزرتی ہے۔ Link checker کسی بھی ایسی URL پر build fail کر دیتا ہے جو 404 واپس کرے۔ اس سے وہ بظاہر درست link بھی پکڑا جاتا ہے جو agent نے خود بنائی ہو۔ Authors کو skill کے ساتھ evaluation prompt suite اور scoring rubric بھی فراہم کرنا ہوتا ہے۔ اس کے بعد scheduled evaluation jobs پوری library پر ہر ہفتے چلتی ہیں تاکہ regressions پکڑی جا سکیں، اور ہر skill کا ایک نامزد 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 میں شامل کیا جا سکتا ہے۔

اس کے بجائے plugin marketplace کے ذریعے pinning

اگر آپ ہر developer سے submodules سیکھنے کا تقاضا نہیں کرنا چاہتے تو Claude Code plugin system تقسیم کا عمل خود انجام دیتا ہے، اور یہ 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 حاصل کیا جاتا ہے۔ یہ branch یا tag کے لیے ref قبول کرتا ہے، لیکن sha قبول نہیں کرتا۔ catalog کے اندر موجود plugin source دونوں کو قبول کرتا ہے۔ جب دونوں مقرر ہوں تو sha مؤثر pin ہوتا ہے۔ اس لیے exact-commit pin catalog entry میں شامل کریں۔

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

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

جو teammate project folder پر اعتماد کرتا ہے، اسے marketplace install کرنے کا prompt دکھایا جاتا ہے، اور plugin اس کے لیے فعال ہو جاتا ہے؛ اسے یہ کام کرنے کی ہدایت دینے والے wiki page کی ضرورت نہیں رہتی۔ اس کے بعد skills کو /team-skills:api-review کے ذریعے استعمال کیا جاتا ہے، کیونکہ plugin skills کو plugin name کے namespace میں رکھا جاتا ہے اور وہ اسی نام کی project skill سے متصادم نہیں ہو سکتیں۔ نیا tag push کرنے کے بعد consumers /plugin marketplace update acme-agents کے ذریعے تازہ کاری کرتے ہیں، پھر اگر install summary میں کہا جائے تو /reload-plugins چلاتے ہیں۔

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

Smoke test ایک scripted agent run ہوتا ہے جو معلوم خرابی والے fixture پر چلایا جاتا ہے اور اس میں ایک 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 ہوتا ہے، اس لیے seeded fault کو پکڑنا بند کرنے والی skill script کو fail کر دیتی ہے۔ Run ناکام ہونے پر claude خود non-zero کے ساتھ exit ہوتا ہے، اور set -euo pipefail دونوں میں سے کسی بھی failure کو failed test میں بدل دیتا ہے۔

Model ہر run کے درمیان اپنے جوابات کا انداز بدل سکتا ہے، اس لیے کبھی پورے جملے پر assert نہ کریں۔ اس identifier پر assert کریں جسے skill سے خارج کرنے کی توقع ہو، یا اس schema کے کسی field پر assert کریں جو آپ نے طلب کیا ہو۔ Fixture کو مختصر رکھیں تاکہ run کم وسائل میں مکمل ہو۔

CI میں --bare شامل کریں۔ اس کے بغیر claude -p وہی context load کرتا ہے جو interactive session load کرتا، جس میں hooks، plugins اور چلنے والی machine سے CLAUDE.md بھی شامل ہوتے ہیں۔ اس وجہ سے کسی teammate کی ذاتی configuration نتیجہ بدل سکتی ہے۔ Bare mode تمام auto-discovery چھوڑ دیتا ہے، اس لیے یہ اس skill کو بھی نہیں ڈھونڈتا جس کی آپ testing کر رہے ہیں۔ اسے صراحت کے ساتھ 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

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

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

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

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

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

یہ command skill load کرنے والی machine پر چلتی ہے، اور اس کا output model کو موصول ہونے والے text میں placeholder کی جگہ لے لیتا ہے۔ تین backticks کے بعد ! سے کھولا گیا fenced block بھی اسی طرح کئی commands چلاتا ہے۔ run time پر ان میں سے کسی کارروائی کی منظوری نہیں لی جاتی۔ مشترکہ skill پڑھنے کا مطلب اس کی command substitutions بھی پڑھنا ہے۔

دوم، frontmatter tools کو پہلے سے منظور کر سکتا ہے۔ allowed-tools درج شدہ tools کو اس turn کے لیے permission prompt کے بغیر اجازت دیتا ہے جس میں skill invoke کی گئی ہو۔ project skill کے لیے یہ اجازت اس وقت مؤثر ہوتی ہے جب کوئی شخص folder کے لیے workspace trust dialog قبول کر لے۔ Claude Code documentation اس کا نتیجہ واضح طور پر بیان کرتی ہے: repository پر trust کرنے سے پہلے project skills کا جائزہ لیں، کیونکہ skill خود کو وسیع tool access دے سکتی ہے۔

اس لیے 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 کے ذریعے لاگو ہونے پر 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 جیسا دکھائی دیتا ہے جو آپ نے لکھی تھیں۔ اپنے web search کے لیے agent کو اپنی SearXNG instance کی طرف بھیجنے سے پہلے اس boundary کے بارے میں پڑھنا ضروری ہے۔

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

• ہر 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

میں کئی repositories میں ایک agent skill کیسے شیئر کروں؟

skill کو ایک dedicated git repository میں رکھیں، اس میں releases کو tag کریں، اور ہر استعمال کرنے والے project میں file copy کرنے کے بجائے کسی tag کا reference دیں۔ اس کے لیے دو طریقے مؤثر ہیں۔ git submodule ایک exact commit record کرتا ہے، اور .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 خود صرف ref قبول کرتا ہے۔ commit pin کو ترجیح دیں، کیونکہ آپ کے review کے بعد tag منتقل کیا جا سکتا ہے۔

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

کسی مستحکم چیز پر assert کریں۔ skill کو non-interactively ایسی fixture کے خلاف چلائیں جس میں معلوم fault موجود ہو، پھر دیکھیں کہ output میں کوئی مخصوص identifier ظاہر ہوتا ہے، مثلاً وہ rule id جس کی skill سے رپورٹ کرنے کی توقع ہے۔ --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 command substitutions کو مکمل طور پر چلنے سے روک دیتا ہے۔

کیا 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 ہو جاتی ہے۔ Harness-specific keys اور spec سے باہر body features کو دوسرے tools نظرانداز یا reject کر سکتے ہیں، اس لیے ایسی skill میں انہیں شامل نہ کریں جسے آپ وسیع پیمانے پر شیئر کرنا چاہتے ہیں۔