repos میں agent skills بغیر drift کے کیسے شیئر کریں

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

repos کے درمیان agent skills کا اشتراک کرنے کے لیے file کی copy بنانا بند کریں اور اس پر 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 میں ship ہونے والے tools اس سلسلے میں کیا سہولت دیتے ہیں، اور کسی بیرونی service کے بغیر self-hosted git remote پر یہ پورا نظام کیسے بنایا جائے۔

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

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

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

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

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

Frontmatter اس معاملے میں کوئی مدد نہیں دیتا۔ Agent Skills spec چھ 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 نہیں ہے۔ File کے اندر یہ ریکارڈ نہیں ہوتا کہ کون سی copy نئی ہے۔ یہ مناسب ہے، کیونکہ skill کسی package کے بجائے ایک document ہوتی ہے۔ اس کا مطلب یہ ہے کہ versioning file کے اردگرد موجود layer سے آنی چاہیے، اور اس layer کی ذمہ داری آپ کی ہے۔

مسئلہ ایک: آٹھ نقول جو خاموشی سے مختلف ہو جاتی ہیں

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

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

مسئلہ دو: کوئی بھی ورژن pin نہیں کیا جاتا

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

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

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

skill کا کوئی compiler نہیں ہوتا۔ یہ model کے لیے ہدایات ہوتی ہیں، اس لیے file کا ایک ایک byte بالکل یکساں رہنے کے باوجود یہ کام کرنا بند کر سکتی ہے۔ model upgrade سے یہ بدل جاتا ہے کہ طویل ہدایت پر کتنی درستگی سے عمل کیا جاتا ہے۔ 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 licensed، 5 August 2026 تک v1.5.22) git repository سے skills انسٹال کرتا ہے اور انہیں اس directory میں رکھتا ہے جس کی agent کو توقع ہوتی ہے۔ یہ ستر سے زیادہ agents کا layout جانتا ہے۔ npx skills add <repo> انسٹال کرتا ہے، npx skills update upgrade کرتا ہے، اور npx skills list موجودہ skills دکھاتا ہے۔ انسٹال شدہ چیزوں کا record ہر repository کے لیے الگ رکھنے کے بجائے ہر user کے لیے ایک بار رکھا جاتا ہے۔ اس project کی ایک کھلی request (issue 283) میں skills install command کا مطالبہ کیا گیا ہے، جو lock file سے تمام tracked skills دوبارہ انسٹال کرے تاکہ دوسری machine پر بھی وہی set حاصل ہو۔ اس request کو موجودہ حالت کی رپورٹ سمجھیں۔ Lockfile کا تصور طے ہو چکا ہے۔ اس کا per-project حصہ ابھی تیار ہو رہا ہے۔

Specs اور 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> ان نتائج کو risk کے لحاظ سے درجہ دیتا ہے۔ یہ Rust crate ہے، MIT یا Apache 2.0 کے تحت dual licensed ہے، اور 29 July 2026 تک version 0.2.2 پر ہے۔ تازہ ترین version کے بجائے مخصوص version انسٹال کریں:

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

--locked اسی dependency versions کے ساتھ build ہوتا ہے جن کے ساتھ crate publish کیا گیا تھا۔ اس لیے build آپ کے نیچے غیر متوقع طور پر تبدیل نہیں ہوتا۔ 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) ہے۔ ہر skill merge ہونے سے پہلے frontmatter metadata، line count، directory layout اور naming کے لیے linters سے گزرتی ہے۔ Link checker ایسے ہر URL پر build fail کر دیتا ہے جو 404 واپس کرے۔ اس سے agent کا بنایا ہوا بظاہر درست link پکڑا جاتا ہے۔ Authors کو skill کے ساتھ evaluation prompt suite اور scoring rubric بھی فراہم کرنا ہوتا ہے۔ اس کے بعد scheduled evaluation jobs پوری library کے خلاف ہر ہفتے چلتی ہیں تاکہ regressions کا پتا چل سکے۔ ہر skill کا ایک named owner بھی ہوتا ہے، جس سے quality کم ہونے پر اسے درست کرنے کی توقع کی جاتی ہے۔

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

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

1. سچائی کا ایک ہی ماخذ۔ ہر skill کا ٹھیک ایک مرکزی مقام ہوتا ہے، اور ہر repository اپنی copy رکھنے کے بجائے اسی مقام کا حوالہ دیتی ہے۔
2. ہر repository کے لیے متعین version۔ ہر project اپنے استعمال کردہ عین revision کو record کرتا ہے، اس لیے 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 پر ترتیب

ایک 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 کے ذریعے pin کرنا

ایک submodule آپ کی repository کے اندر کسی دوسری repository کا ایک مخصوص commit محفوظ کرتا ہے۔ یہی record pin ہوتا ہے۔ ہر consuming 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 کسی دوسرے disk location کی directory کا symlink ہو سکتی ہے، اور Claude Code اس symlink کو follow کرکے target سے SKILL.md پڑھتا ہے۔ اس طرح skill عام project skill کے طور پر load ہوتی ہے، جبکہ اس کا data submodule میں آپ کے منتخب کردہ commit پر محفوظ رہتا ہے۔

Pin کی تصدیق کریں:

git submodule status

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

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

ابتدا میں - کا مطلب ہے کہ submodule کبھی initialize نہیں کیا گیا، اس لیے .claude/skills/api-review کسی چیز کی طرف اشارہ نہیں کرتا اور skill خاموشی سے load نہیں ہوتی۔ اسے git submodule update --init سے درست کریں۔ ابتدا میں + کا مطلب ہے کہ checkout کیا گیا commit محفوظ کیے گئے commit سے مختلف ہے، اس لیے وہ developer ایسی ہدایات استعمال کر رہا ہے جو کسی اور کے پاس نہیں ہیں۔ نئے 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 کا طریقہ فراہم کرتی ہے۔ اس میں وہی تبدیلی دکھائی دیتی ہے جو ہر دوسرے consuming repo میں نظر آئے گی، اور اسے pull request میں شامل کیا جا سکتا ہے۔

اس کے بجائے plugin 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 قبول کرتا ہے اور sha قبول نہیں کرتا۔ catalog کے اندر موجود plugin source دونوں کو قبول کرتا ہے، اور جب دونوں set ہوں تو sha مؤثر pin ہوتا ہے۔ اس لیے exact-commit pin catalog entry میں ہونا چاہیے۔

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

{
  "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 کے ذریعے refresh کرتے ہیں، پھر اگر install summary اس کا مطالبہ کرے تو /reload-plugins چلاتے ہیں۔

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

smoke test معلوم خرابی والے fixture کے خلاف scripted agent run اور ایک assertion پر مشتمل ہوتا ہے۔ Claude Code -p کے ساتھ non-interactive طریقے سے چلتا ہے، اور 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 مختلف runs کے دوران اپنے جوابات مختلف الفاظ میں لکھ سکتا ہے، اس لیے کبھی پورے جملے پر assertion نہ لگائیں۔ اس identifier پر assertion لگائیں جسے skill سے خارج کرنے کی توقع ہے، یا اس schema کے کسی field پر جس کا آپ نے مطالبہ کیا ہو۔ fixture کو مختصر رکھیں تاکہ run کم لاگت والا رہے۔

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

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

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

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

یہ command skill لوڈ کرنے والی مشین پر چلتی ہے، اور اس کا output ماڈل کو موصول ہونے والے متن میں placeholder کی جگہ لے لیتا ہے۔ تین backticks کے بعد ! سے کھولا گیا fenced block بھی اسی طرح متعدد commands چلاتا ہے۔ run time پر کوئی بھی ان actions کی منظوری نہیں دیتا۔ مشترکہ 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 کو باہر کی سمت منتقل کرتی ہے، کیونکہ حاصل شدہ text context میں بالکل ان instructions جیسا دکھائی دیتا ہے جو آپ نے خود لکھی ہیں۔ اپنے agent کو web search کے لیے اپنی SearXNG instance کی طرف بھیجنے سے پہلے اس boundary کے بارے میں پڑھنا ضروری ہے۔

ورژن میں اضافہ کرتے وقت کیا پڑھیں

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

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

جب کوئی model یا tool change کسی skill کو توڑ دے

کسی کی اس میں ترمیم کیے بغیر skill کے پس منظر میں کئی چیزیں تبدیل ہو سکتی ہیں۔ model upgrade کی وجہ سے طویل ہدایات پر عمل کی reliability بدل جاتی ہے، اس لیے وہ skill جو model کے step nine تک پہنچنے پر انحصار کرتی تھی، وہاں تک پہنچنا بند کر سکتی ہے۔ command line tool کسی flag کا نام بدل دیتا ہے، تو agent پرانا flag چلاتا ہے، error پڑھتا ہے اور اپنی طرف سے طریقہ اختیار کرتا ہے۔ حوالہ دیا گیا URL 404 واپس کرنا شروع کر دیتا ہے۔ agent harness کے skill selection کے طریقے میں تبدیلی آ جاتی ہے، اس لیے جو description پہلے match جیتتا تھا، اب نہیں جیتتا۔

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

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

FAQ

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

Skill کو ایک dedicated git repository میں رکھیں، اس میں releases کو tag کریں، اور ہر استعمال کرنے والے project میں file copy کرنے کے بجائے کسی tag کا reference دیں۔ اس کے لیے دو طریقے کارآمد ہیں۔ ایک git submodule exact commit ریکارڈ کرتا ہے، اور .claude/skills/<name> سے submodule کے اندر موجود skill تک 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 کو 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 load کے وقت ! command substitution form کے ذریعے 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۔ جو skill صرف انہی keys تک محدود ہو، وہ ان tools میں load ہو جاتی ہے جو اس spec کو implement کرتے ہیں، اور Claude Code میں بھی بغیر تبدیلی کے load ہوتی ہے۔ Harness-specific keys اور spec سے باہر body features کو دوسرے tools نظرانداز یا reject کر سکتے ہیں، اس لیے جس skill کو وسیع پیمانے پر share کرنا ہو اس میں انہیں شامل نہ کریں۔