اپنی کسٹم Agent Skill کیسے لکھیں؟

ایک حقیقی ناکامی سے اپنی ایجنٹ اسکل (agent skill) لکھنا

اپنی ایجنٹ اسکل لکھنے کا بہترین طریقہ یہ ہے کہ اسے کسی ایک حقیقی ناکامی سے اخذ کیا جائے۔ کوئی ایسا کام تلاش کریں جسے آپ کے کوڈنگ ایجنٹ نے دو بار غلط کیا ہو، ان دونوں بار آپ کی ٹائپ کردہ اصلاح کو لکھ لیں، اور اس اصلاح کو ایک SKILL.md فائل کے طور پر محفوظ کریں جسے ایجنٹ خود لوڈ کر سکے۔ اس کے بعد سب کچھ صرف میکانکس ہے: فائل کا لے آؤٹ، اور وہ ایک لائن جو یہ فیصلہ کرتی ہے کہ آیا اسکل کبھی فعال (fire) ہوگی یا نہیں۔

یہ ترتیب اہمیت رکھتی ہے۔ تخیل سے لکھی گئی اسکل ایک ایسے مسئلے کی دستاویز ہوتی ہے جو آپ کو کبھی پیش نہیں آیا، اور یہ ہر سیشن میں کانٹیکسٹ (context) کی قیمت لیتی ہے۔ ایک ایسی اسکل جو آپ کی دیکھی ہوئی ناکامی سے کشید کی گئی ہو، وہ اپنے ساتھ اپنا ٹیسٹ لے کر آتی ہے: وہی چیز دوبارہ پوچھیں، اور دیکھیں کہ کیا ایجنٹ اس بار اسے درست کرتا ہے۔ اگر فارمیٹ خود آپ کے لیے نیا ہے، تو پہلے ایجنٹ اسکلز کیا ہیں اور ایجنٹ انہیں کیسے لوڈ کرتا ہے پڑھیں، پھر واپس آئیں اور ایک اسکل لکھیں۔

اس کام سے شروع کریں جس میں ایجنٹ دو بار غلطی کر چکا ہو

ایک بار ہونا اتفاق ہے۔ دو بار ہونا ایک پیٹرن ہے، اور پیٹرن ایک فائل بنانے کے لائق ہوتا ہے۔

یہ ایک ایسی ناکامی ہے جو حقیقی سرورز پر بار بار ہوتی ہے۔ آپ ایجنٹ سے کہتے ہیں کہ Nginx میں reverse proxy بلاک شامل کرے۔ وہ /etc/nginx/conf.d/app.conf میں ترمیم کرتا ہے، پھر sudo systemctl restart nginx چلاتا ہے۔ ترمیم میں ٹائپنگ کی غلطی ہوتی ہے، اس لیے Nginx شروع ہونے سے انکار کر دیتا ہے، اور آپ کے ٹھیک کرنے تک سائٹ بند رہتی ہے:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

آپ چیٹ میں اسے درست کرتے ہیں۔ سروس کو چھونے سے پہلے sudo nginx -t کے ساتھ کنفیگریشن ٹیسٹ کریں، پھر restart کے بجائے reload کے ساتھ اسے لاگو کریں۔ ایک ہفتے بعد، کسی دوسرے کام پر، وہی غلطی دوبارہ ہوتی ہے۔ وہ دوسری بار سگنل ہے۔

جب ناکامی آپ کے سامنے ہو تو دو چیزیں لکھ لیں: وہ درخواست جو آپ نے ٹائپ کی، اور وہ اصلاح جو آپ نے دی، انہی الفاظ میں جو آپ نے استعمال کیے۔ یہ دو لائنیں مہارت (skill) بن جاتی ہیں۔ درخواست آپ کو بتاتی ہے کہ ٹرگر (trigger) کو کس چیز سے مطابقت رکھنی چاہیے۔ اصلاح مکمل مواد ہے۔

Anthropic کی اپنی تحریری رہنمائی اسے اولیت دیتی ہے۔ ایجنٹ کو بغیر کسی مہارت کے نمائندہ کاموں پر چلائیں، ریکارڈ کریں کہ وہ کہاں ناکام ہوتا ہے، پھر وہ کم سے کم ہدایات لکھیں جو ان ناکامیوں کو ٹھیک کر دیں۔ ناکامیاں ہی تفصیلات (specification) ہیں، لہذا ایسی مہارت جس کا سراغ آپ کسی ناکامی تک نہ لگا سکیں، عام طور پر ایسی مہارت ہوتی ہے جس کی کسی کو ضرورت نہیں تھی۔

اسی کشید (distillation) کی ایک عملی مثال کے لیے، Ponytail ایک بار بار ہونے والی ناکامی کو، یعنی ایک ایسا ایجنٹ جو آپ کی درخواست سے کہیں زیادہ دوبارہ لکھتا ہے، ایک مہارت میں بدل دیتا ہے آپ اپنی مہارت لکھنے سے پہلے اسے مکمل پڑھ سکتے ہیں۔

اسکل (skill) کی ساخت

ایک اسکل ایک ایسی ڈائریکٹری ہے جس میں ایک لازمی فائل موجود ہوتی ہے۔

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md ایک فرنٹ میٹر بلاک کے ساتھ کھلتی ہے، جس میں YAML فارمیٹ (وہی کنفیگریشن فارمیٹ جو Docker Compose فائلیں استعمال کرتی ہیں) میں کچھ سیٹنگز --- مارکرز کے درمیان لکھی جاتی ہیں، اس کے بعد مارک ڈاؤن میں ہدایات ہوتی ہیں۔ اوپر دی گئی خرابی کے لیے مکمل اسکل یہ ہے۔

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

یہ فائل بیس لائنز سے کم پر مشتمل ہے اور یہ ایک مکمل اسکل ہے۔ اس کے حصے یہ ہیں:

• name: زیادہ سے زیادہ 64 کریکٹرز، صرف چھوٹے حروف، ہندسے اور ہائفن، اور اس میں claude یا anthropic کے الفاظ شامل نہیں ہو سکتے۔ ذاتی یا پروجیکٹ اسکل میں یہ صرف ڈسپلے لیبل ہے۔ جو کمانڈ آپ ٹائپ کرتے ہیں وہ ڈائریکٹری کے نام سے آتی ہے، لہذا یہ /nginx-config-changes کے جواب میں چلتی ہے۔
• description: اسکل کیا کرتی ہے اور اسے کب استعمال کرنا ہے، زیادہ سے زیادہ 1,024 کریکٹرز۔ یہ لائن اصل کام کرتی ہے، اور اگلا سیکشن اسی کے بارے میں ہے۔
• باڈی: ہدایات، جو صرف تب لوڈ ہوتی ہیں جب اسکل درحقیقت چلتی ہے۔
• reference/: اضافی فائلیں جنہیں ایجنٹ ضرورت پڑنے پر پڑھتا ہے۔ انہیں SKILL.md سے لنک کریں اور لنکس کو ایک لیول گہرا رکھیں، کیونکہ ایک فائل سے ریفرنس کی گئی دوسری فائل اکثر صرف جزوی طور پر پڑھی جاتی ہے۔
• scripts/: وہ فائلیں جنہیں ایجنٹ پڑھنے کے بجائے ایگزیکیوٹ کرتا ہے۔ صرف ان کی آؤٹ پٹ کانٹیکسٹ کی قیمت خرچ کرتی ہے، لہذا 300 لائنوں کی اسکرپٹ سستی پڑتی ہے۔

آپ ڈائریکٹری کہاں رکھتے ہیں اس کا فیصلہ یہ کرتا ہے کہ اسکل کس کو ملے گی۔

• .claude/skills/<name>/SKILL.md ریپوزٹری میں: صرف اس پروجیکٹ کے لیے، اور یہ ہر اس شخص کے پاس جاتی ہے جو ریپو کو کلون کرتا ہے۔
• ~/.claude/skills/<name>/SKILL.md: آپ کی مشین پر موجود ہر پروجیکٹ کے لیے، اور کسی اور کے لیے نہیں۔
• <plugin>/skills/<name>/SKILL.md: پلگ ان کے اندر موجود، جہاں بھی وہ پلگ ان فعال ہو وہاں دستیاب۔

mkdir -p .claude/skills/nginx-config-changes کے ساتھ ایک بنائیں اور فائل لکھیں۔ Claude Code ان ڈائریکٹریز پر نظر رکھتا ہے، لہذا موجودہ اسکل میں ترمیم کرنے سے چلتے ہوئے سیشن کے اندر فوری اثر ہوتا ہے۔ ایک ایسی ٹاپ لیول اسکلز ڈائریکٹری بنانا جو سیشن شروع ہونے کے وقت موجود نہیں تھی، اس کے لیے ری اسٹارٹ کی ضرورت ہوتی ہے، کیونکہ سیشن کے آغاز میں نگرانی کے لیے کچھ موجود نہیں تھا۔

فائل میں description فیلڈ سب سے زیادہ اثر رکھنے والی لائن ہے

startup پر ایجنٹ ہر دستیاب skill کے name اور description کو اپنے context میں لوڈ کرتا ہے۔ یہ ان کی باڈیز (bodies) کو لوڈ نہیں کرتا۔ جب آپ کی درخواست موصول ہوتی ہے، تو یہ ایک لائن ہی اس بات کا فیصلہ کرنے کی واحد بنیاد ہوتی ہے کہ آیا یہ skill متعلقہ ہے یا نہیں، لہذا ایک مبہم description کے پیچھے موجود بہترین باڈی کبھی نہیں پڑھی جاتی۔

description کو ہمیشہ third person میں لکھیں۔ "Tests and reloads nginx safely" درست ہے۔ "I can help you with nginx" درست نہیں ہے، کیونکہ یہ متن system prompt میں داخل کیا جاتا ہے، جہاں first person کا مطلب یہ نکلتا ہے کہ ماڈل اپنے بارے میں بات کر رہا ہے۔

اس میں دو چیزیں شامل رکھیں: skill کیا کرتی ہے، اور وہ کون سی صورتحال ہے جس میں یہ لاگو ہوتی ہے۔ اہم use case کو پہلے لکھیں، کیونکہ Claude Code لسٹنگ اندراج کو 1,536 کیریکٹرز پر کاٹ دیتا ہے۔ اضافی trigger phrases اور مثالوں کے لیے ایک اختیاری when_to_use فیلڈ موجود ہے، اور اسے اسی حد کے تحت description کے ساتھ جوڑ دیا جاتا ہے۔

پھر وہ الفاظ استعمال کریں جو آپ درحقیقت ٹائپ کریں گے۔ description: Helps with nginx کسی چیز سے میچ نہیں کرتا، کیونکہ کوئی بھی "helps with" ٹائپ نہیں کرتا۔ اوپر دیا گیا ورژن /etc/nginx، server block، reverse proxy اور TLS (transport layer security) certificate path کا نام لیتا ہے، جو تقریباً ہر اس درخواست کا ذخیرہ الفاظ ہے جسے اسے ٹرگر کرنا چاہیے۔

یہاں description کے لیے ایک ٹیسٹ ہے۔ یہ ایک لائن کسی ایسے شخص کو دیں جس نے کبھی باڈی نہیں دیکھی، ساتھ ہی وہ درخواست بھی دیں جو آپ ٹائپ کرنے والے ہیں، اور ان سے پوچھیں کہ کیا یہ skill لاگو ہوتی ہے۔ اگر وہ نہیں بتا سکتے، تو ماڈل بھی نہیں بتا سکے گا۔

باڈی کو چھوٹا رکھیں، کیونکہ یہ سیاق و سباق میں رہتی ہے

جب کوئی skill استعمال کی جاتی ہے، تو اس کا رینڈر کردہ مواد ایک پیغام کے طور پر گفتگو میں شامل ہو جاتا ہے اور باقی سیشن کے دوران وہیں رہتا ہے۔ Claude Code بعد کے مراحل میں فائل کو دوبارہ نہیں پڑھتا۔ آپ جو بھی لائن لکھتے ہیں، اس کی قیمت آپ پورے سیشن کے لیے ادا کرتے ہیں، نہ کہ صرف ایک جواب کے لیے۔

Anthropic تجویز کرتا ہے کہ SKILL.md کو 500 لائنوں سے کم رکھا جائے اور تفصیلات کو الگ فائلوں میں منتقل کیا جائے۔ کمپیکشن (compaction) ظاہر کرتی ہے کہ یہ تعداد من مانی نہیں ہے۔ جب سیاق و سباق کو خالی کرنے کے لیے گفتگو کا خلاصہ کیا جاتا ہے، تو Claude Code ہر skill کے حالیہ ترین استعمال کو دوبارہ منسلک کرتا ہے، ہر ایک کے صرف 5000 ٹوکنز برقرار رکھتا ہے، اور سب سے حال ہی میں استعمال ہونے والی skill سے شروع کرتے ہوئے 25000 ٹوکنز کے مشترکہ بجٹ کو پُر کرتا ہے۔ ایک لمبی skill درمیان میں ہی کٹ جاتی ہے۔ کئی لمبی skills ایک دوسرے کو مکمل طور پر باہر نکال دیتی ہیں۔

اس لیے صرف وہی لکھیں جو ماڈل پہلے سے نہیں جانتا۔ یہ جانتا ہے کہ nginx کیا ہے اور reverse proxy کیا کام کرتا ہے۔ یہ reload کے مقابلے میں restart کے بارے میں آپ کے گھریلو اصول کو نہیں جانتا، اور یہی اصول اس فائل کے وجود کی واحد وجہ ہے۔

اگر skill ایجنٹ کو کوئی بنڈل اسکرپٹ چلانے کا کہتی ہے، تو پاتھ کا نام ${CLAUDE_SKILL_DIR} کے ساتھ رکھیں تاکہ یہ وہاں ریزولو ہو سکے جہاں skill انسٹال ہے، اور اسی کمانڈ کو پہلے سے منظور (pre-approve) کر لیں تاکہ رن (run) کسی اجازت کے پرامپٹ پر نہ رکے۔

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

یہ اجازت صرف اس ٹرن (turn) کا احاطہ کرتی ہے جس نے skill کو کال کیا تھا اور آپ کے اگلے پیغام بھیجنے پر یہ ختم ہو جاتی ہے، لہذا یہ خاموشی سے مستقل اجازت نہیں بنتی۔

یہ کیسے ثابت کریں کہ اسکل (skill) متحرک ہو رہی ہے

اسکل کے لوڈ ہونے کا مشاہدہ کرنے سے آپ کو یہ معلوم ہوتا ہے کہ ایجنٹ نے اسے تلاش کر لیا ہے۔ اس سے یہ معلوم نہیں ہوتا کہ جواب تبدیل ہوا ہے یا نہیں۔ دونوں چیزوں کی جانچ کریں، اور ایک نئے سیشن میں چیک کریں، کیونکہ جس سیشن میں آپ نے اسکل لکھی تھی، اس میں وہ تمام باتیں موجود ہیں جو آپ نے اسے لکھتے وقت کہی تھیں۔ وہ بچا ہوا سیاق و سباق فائل میں موجود خامیوں کو چھپا دیتا ہے۔

1. پروجیکٹ میں claude کے ساتھ ایک نیا سیشن شروع کریں۔
2. اپنی درخواست اس طرح ٹائپ کریں جیسے آپ عام کام کے دن کرتے ہیں، اپنے الفاظ میں، اسکل کا نام لیے بغیر۔
3. اس کے متحرک ہونے (invocation) کا مشاہدہ کریں۔ اگر اسکل متحرک نہیں ہوتی تو اس کی تفصیل (description) کو درست کریں۔ ابھی مسئلہ باڈی (body) کا نہیں ہے۔
4. کنٹرول کے طور پر /nginx-config-changes کے ساتھ اسے دستی طور پر چلائیں۔ دستی طور پر چلانے پر درست رویہ اور درخواست کے ذریعے چلانے پر غلط رویہ اس بات کی تصدیق کرتا ہے کہ مسئلہ ٹرگر (trigger) کا ہے نہ کہ ہدایات کا۔
5. اسی درخواست کو اسکل بند کر کے چلائیں اور دونوں جوابات کا موازنہ کریں۔ /skills مینو میں، اسکل کو ہائی لائٹ کریں، اس کی حالت کو off پر لانے کے لیے Space دبائیں، پھر محفوظ کرنے کے لیے Enter دبائیں۔ یہ .claude/settings.local.json میں ایک skillOverrides اندراج لکھتا ہے، اور کام مکمل ہونے پر Space کو دوبارہ دبانے سے یہ واپس on پر آ جاتی ہے۔
6. کچھ ایسی درخواستیں لکھیں جن سے اسکل کو متحرک نہیں ہونا چاہیے، اور چیک کریں کہ وہ ان پر خاموش رہتی ہے۔

اس لوپ کو خودکار بنانے کے لیے، آفیشل مارکیٹ پلیس سے skill-creator پلگ ان انسٹال کریں۔

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

اگر انسٹالیشن کے آؤٹ پٹ میں Run /reload-plugins to activate. لکھا آئے، تو وہ کمانڈ چلائیں۔ پھر Claude سے کہیں کہ وہ آپ کی اسکل کا نام لے کر اس کی جانچ کرے۔ پلگ ان ٹیسٹ کیسز کو اسکل ڈائریکٹری کے اندر evals/evals.json میں محفوظ کرتا ہے اور ہر کیس کو اپنے سب ایجنٹ میں چلاتا ہے، لہذا ہر رن ایک صاف سیاق و سباق کے ساتھ شروع ہوتا ہے۔ پھر یہ اسکل کے ساتھ بمقابلہ اسکل کے بغیر کا موازنہ لکھتا ہے، جو کہ اصل اعداد و شمار ہیں: پاس ہونے کی شرح میں بہتری، جس کا موازنہ ان ٹوکنز اور وقت سے کیا جاتا ہے جو اسکل استعمال کرتی ہے۔

ناکامی کی حالت: skill کبھی ٹرگر نہیں ہوتی

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

• تفصیل میں یہ تو لکھا ہے کہ skill کیا کرتی ہے لیکن یہ نہیں بتایا گیا کہ اسے کب استعمال کرنا ہے، لہذا آپ کی درخواست میں کوئی بھی چیز اس سے مطابقت نہیں رکھتی۔
• تفصیل میں ان الفاظ سے گریز کیا گیا ہے جو آپ ٹائپ کرتے ہیں۔ اگر آپ "nginx" کہتے ہیں، تو تفصیل میں nginx کا ذکر ہونا ضروری ہے۔
• disable-model-invocation: true فرنٹ میٹر میں سیٹ ہے۔ یہ تفصیل کو ماڈل کے سیاق و سباق (context) سے مکمل طور پر باہر رکھتا ہے، اور skill کو صرف آپ کے لیے /name کے ذریعے قابلِ استعمال چھوڑتا ہے۔
• فرنٹ میٹر میں ایک paths گلوب (glob) ایکٹیویشن کو مماثل فائلوں تک محدود کرتا ہے، اور جس فائل پر آپ کام کر رہے ہیں وہ اس سے میل نہیں کھاتی۔
• skill آپ کی ابتدائی ڈائریکٹری کے نیچے ایک نیسٹڈ (nested) .claude/skills/ ڈائریکٹری میں موجود ہے۔ یہ تب ہی لوڈ ہوتی ہیں جب ایجنٹ اس ذیلی ڈائریکٹری کے اندر کسی فائل کو پڑھے یا ایڈٹ کرے، لہذا تب تک skill بالکل دستیاب نہیں ہوتی۔

Failure mode: skill کا مسلسل متحرک ہونا

اس کا الٹ مسئلہ ایک ایسی وسیع تفصیل ہے جس کی وجہ سے skill غیر متعلقہ کاموں پر بھی متحرک ہو جاتی ہے۔ "Use when working on the server" جیسی تفصیل سرور ریپوزٹری میں تقریباً ہر درخواست سے مطابقت رکھتی ہے۔ اس کے بعد باڈی ان کاموں پر لوڈ ہو جاتی ہے جن میں یہ مدد نہیں کر سکتی، اور یہ سیشن کے باقی حصے تک سیاق و سباق میں رہتی ہے۔

تفصیل کو اس شرط تک محدود کریں جو درحقیقت اہمیت رکھتی ہے، اور ان فائلوں یا کمانڈز کے نام بتائیں جن کا یہ احاطہ کرتی ہے۔ جب skill صرف مخصوص فائلوں پر لاگو ہو تو paths glob شامل کریں۔ سائیڈ ایفیکٹس والی کسی بھی چیز کے لیے، جیسے کہ deploy یا commit، disable-model-invocation: true سیٹ کریں اور اسے خود /name کے ساتھ invoke کریں، تاکہ ایجنٹ کبھی بھی خود یہ فیصلہ نہ کرے کہ اب deploy کرنے کا مناسب وقت ہے۔

ناکامی کا طریقہ: مہارت کا تعلق آپ کی rules فائل سے ہے

ایک rules فائل جیسے کہ CLAUDE.md یا AGENTS.md ہر سیشن کے آغاز میں لوڈ ہوتی ہے اور ہر ٹاسک پر لاگو ہوتی ہے۔ مہارت (skill) کی باڈی صرف تب لوڈ ہوتی ہے جب وہ مہارت متحرک ہو۔ فیصلہ فریکوئنسی پر مبنی ہوتا ہے۔ کوئی بھی حقیقت جو ریپوزٹری کے ہر ٹاسک کے لیے درست ہو، جیسے کہ آپ کا استعمال کردہ package manager، وہ rules فائل میں ہونی چاہیے۔ کوئی بھی طریقہ کار جو ٹاسک کے ایک چھوٹے حصے پر لاگو ہو، جیسے اوپر دی گئی nginx رول، وہ ایک مہارت میں ہونا چاہیے، جہاں ان دنوں اس کی کوئی قیمت نہیں ہوتی جب کوئی nginx میں ترمیم نہیں کر رہا ہوتا۔

اصل ناکامی اسے دونوں جگہوں پر رکھنا ہے۔ دو کاپیاں وقت کے ساتھ ایک دوسرے سے مختلف ہو جاتی ہیں، اور جب ایجنٹ غلط کام کرتا ہے تو آپ یہ نہیں بتا سکتے کہ اس نے کون سی کاپی کی پیروی کی۔ ہر ہدایت کے لیے ایک جگہ کا انتخاب کریں۔ skills، MCP سرورز اور rules فائلوں کے درمیان حد بندی مشکل کیسز کا احاطہ کرتی ہے، بشمول تب جب صحیح جواب ایک MCP (model context protocol) سرور ہو جو ایجنٹ کو نئی ہدایت دینے کے بجائے ایک نیا ٹول فراہم کرے۔

جب کوئی مہارت اپنی جگہ بنا لے تو اسے شیئر کریں

جو مہارت ایک ہفتے کے عملی کام میں کارآمد ثابت ہو، اسے محفوظ کرنا فائدہ مند ہے۔ .claude/skills/ میں پروجیکٹ کی مہارتوں کا جائزہ کوڈ کی طرح لیا جاتا ہے اور وہ ریپوزٹری کے ساتھ ہی آتی ہیں، لہذا جو ٹیم ممبر اسے کلون کرتا ہے، اسے آپ کی درستگی بغیر کسی اضافی سیٹ اپ کے مل جاتی ہے۔ کاپی پیسٹ کیے بغیر ایک ریپوزٹری سے دوسری ریپوزٹری میں مہارت منتقل کرنا ایک الگ مسئلہ ہے، جس کا احاطہ how to share agent skills across repos میں کیا گیا ہے۔

پورٹیبلٹی کے حوالے سے ایک اہم نوٹ۔ Claude Code فرنٹ میٹر فیلڈز کی ایک طویل فہرست کو قبول کرتا ہے، لیکن Agent Skills کا معیار صرف چھ فیلڈز کی اجازت دیتا ہے: name، description، license، compatibility، metadata اور allowed-tools۔ اگر آپ کسی مہارت کو claude.ai پر اپ لوڈ کرتے ہیں، یا اسے Skills API کے لیے پیکج کرتے ہیں، اور فرنٹ میٹر میں کوئی اور فیلڈ شامل کرتے ہیں، تو یہ فیلڈ کو نظر انداز کرنے کے بجائے مکمل طور پر ناکام ہو جائے گا:

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

ان چھ فیلڈز کے اندر رہیں تو وہی فائل Claude Code اور معیار کو پڑھنے والے ہر دوسرے ٹول میں لوڈ ہو جائے گی۔ ہدایات کو اس طرح لکھنا کہ وہ کسی دوسرے ماڈل پر منتقلی کے بعد بھی کارآمد رہیں، ایک الگ کام ہے، اور writing skills that work with any model اس کا احاطہ کرتا ہے۔

FAQ

SKILL.md فائل کتنی لمبی ہونی چاہیے؟

اسے 500 لائنوں سے کم رکھیں، اور توقع رکھیں کہ زیادہ تر مفید مہارتیں اس سے کہیں مختصر ہوں گی۔ جب مہارت کو استعمال کیا جاتا ہے تو اس کا مواد گفتگو میں شامل ہو جاتا ہے اور باقی سیشن کے دوران وہیں رہتا ہے، لہذا ہر لائن ایک بار کی قیمت کے بجائے بار بار ادا کی جانے والی قیمت ہے۔ طویل حوالہ جات کو مہارت کی ڈائریکٹری میں الگ فائلوں میں منتقل کریں اور انہیں SKILL.md سے لنک کریں، ایک سطح گہرائی میں، تاکہ ایجنٹ انہیں صرف تب پڑھے جب اسے ضرورت ہو۔ بنڈل اسکرپٹس کو پڑھنے کے بجائے ایگزیکیوٹ کیا جاتا ہے، لہذا ان کی قیمت صرف ان کی آؤٹ پٹ تک محدود ہوتی ہے۔

میری مہارت کبھی ٹرگر (trigger) کیوں نہیں ہوتی؟

اس کی عام وجہ تفصیل (description) ہوتی ہے، کیونکہ جب ماڈل فیصلہ کرتا ہے تو صرف یہی حصہ سیاق و سباق میں ہوتا ہے۔ یقینی بنائیں کہ اس میں یہ لکھا ہو کہ مہارت کب استعمال کرنی ہے، نہ صرف یہ کہ وہ کیا کرتی ہے، اور یہ کہ اس میں وہ الفاظ شامل ہوں جو آپ اپنی درخواستوں میں ٹائپ کرتے ہیں۔ اگر تفصیل درست لگ رہی ہو تو disable-model-invocation: true کے لیے فرنٹ میٹر (frontmatter) چیک کریں، جو مہارت کو ماڈل سے مکمل طور پر چھپا دیتا ہے، اور paths گلوب (glob) چیک کریں جو اسے ان فائلوں تک محدود کرتا ہے جنہیں آپ استعمال نہیں کر رہے۔ آپ کی ابتدائی ڈائریکٹری کے نیچے کسی نیسٹڈ (nested) .claude/skills/ ڈائریکٹری میں موجود مہارت ایک اور وجہ ہو سکتی ہے: یہ تب ہی لوڈ ہوتی ہے جب ایجنٹ اس ذیلی ڈائریکٹری میں کوئی فائل پڑھے یا ایڈٹ کرے۔

کیا اسے ایک مہارت ہونا چاہیے یا میری رولز فائل میں ایک لائن؟

خود سے پوچھیں کہ یہ آپ کے کتنے کاموں پر لاگو ہوتی ہے۔ رولز فائل ہر سیشن میں لوڈ ہوتی ہے، لہذا اس میں وہ حقائق ہونے چاہئیں جو ہر کام کے لیے درست ہوں، جیسے کہ پیکیج مینیجر یا برانچ کا نام رکھنے کا طریقہ کار۔ ایک مہارت صرف تب لوڈ ہوتی ہے جب وہ فائر (fire) ہوتی ہے، لہذا یہ ایسے طریقہ کار کے لیے بہترین جگہ ہے جو کاموں کے ایک چھوٹے حصے پر لاگو ہوتا ہے۔ کبھی بھی ایک ہی ہدایت دونوں جگہ نہ لکھیں، کیونکہ دونوں کاپیاں وقت کے ساتھ بدل سکتی ہیں اور آپ یہ جاننے کی صلاحیت کھو دیں گے کہ ایجنٹ نے کس کی پیروی کی۔

مجھے کیسے معلوم ہوگا کہ مہارت نے واقعی مدد کی؟

اس کا موازنہ ایک بیس لائن (baseline) سے کریں۔ کچھ حقیقی درخواستیں جمع کریں، ہر ایک کو ایک نئے سیشن میں مہارت کی دستیابی کے ساتھ چلائیں، پھر انہیں /skills مینو سے مہارت کو بند کر کے دوبارہ چلائیں، اور دونوں جوابات کو ساتھ رکھ کر پڑھیں۔ نیا سیشن اس لیے اہم ہے کیونکہ جس گفتگو میں آپ نے مہارت لکھی تھی اس میں آپ کی وضاحتیں موجود ہوتی ہیں، جو ایک نامکمل فائل کو مکمل ظاہر کرتی ہیں۔ skill-creator پلگ ان آپ کے لیے یہ موازنہ کرتا ہے اور ٹوکن لاگت کے ساتھ کامیابی کی شرح (pass rate) رپورٹ کرتا ہے۔

کیا میں ایک ہی SKILL.md کو مختلف ایجنٹ کے ساتھ استعمال کر سکتا ہوں؟

جی ہاں، جب تک آپ ان فیلڈز کے اندر رہتے ہیں جن کی Agent Skills اسٹینڈرڈ وضاحت کرتا ہے: name، description، license، compatibility، metadata اور allowed-tools۔ Claude Code بہت سی مزید فیلڈز کو قبول کرتا ہے، اور یہ باڈی فیچرز جیسے کہ شیل کمانڈ انجیکشن کو بھی سپورٹ کرتا ہے جسے دوسرے ٹولز رن نہیں کرتے۔ اسٹینڈرڈ سے باہر کسی فیلڈ کے ساتھ مہارت اپ لوڈ کرنے پر ایک واضح ایرر آتا ہے جس میں اجازت شدہ پراپرٹیز کی فہرست ہوتی ہے، لہذا شروع میں ہی فیصلہ کر لیں کہ آیا مہارت صرف Claude Code میں رہنی ہے یا کہیں اور بھی استعمال ہونی ہے۔