finestructure-ai/claude-plugin کے اندر: سات فائلوں میں ایک Claude Code پلگ ان

پورا مخزن سات فائلوں کا ہے

اسے clone کیجیے، فائلوں کا شجرہ ایک ہی اسکرین میں آ جاتا ہے:

.claude-plugin/
  plugin.json        686 B
  marketplace.json   507 B
commands/
  deploy.md          3.3 KB
  fs-domain.md       905 B
  fs-status.md       741 B
skills/
  fine-structure/
    SKILL.md         4.0 KB
LICENSE              MIT
README.md            2.3 KB

نہ package.json، نہ لاک فائل، نہ CI، نہ dist۔ کچھ بھی مرتب یا بنڈل نہیں ہوتا، اور اس مخزن کا کوئی ایسا نسخہ ممکن ہی نہیں جس کی بلڈ ناکام ہو۔ اگر آپ یہ سمجھ کر پلگ ان لکھنا ٹالتے رہے ہیں کہ اس کے لیے کوئی ٹول چین درکار ہے، تو تصحیح یہ ہے: فارمیٹ دراصل فولڈروں کا ایک ضابطہ اور دو JSON فائلیں ہے، اور باقی سب نثر ہے۔

فائل plugin.json ایک اشارہ ہے، پروگرام نہیں

مینی فیسٹ میں شناخت کے معمول کے خانے موجود ہیں (name، ورژن 0.1.0، description، author، homepage، repository، license، keywords) اور پھر ایک بلاک جو سارا دلچسپ کام کرتا ہے:

"mcpServers": {
  "finestructure": {
    "type": "http",
    "url": "https://finestructure.ai/api/mcp"
  }
}

دو کلیدیں۔ نہ command، نہ args، نہ env۔ اس کا موازنہ اُس شکل سے کیجیے جو زیادہ تر MCP کنفیگریشنز اختیار کرتی ہیں: ایک مقامی عمل (npx، uvx، یا کسی بائنری کا راستہ)، دلائل کی ایک فہرست، اور ایک env نقشہ جس میں API کلید رکھی ہوتی ہے۔ اس کے بجائے streamable HTTP اینڈ پوائنٹ کا اعلان سرور کو صارف کی مشین سے باہر لے جاتا ہے، اور یہی وجہ ہے کہ 105 ٹولز (یہ تعداد skill فائل بتاتی ہے) 686 بائٹ کے مینی فیسٹ کے پیچھے بیٹھے ہیں۔ صارف کے Node یا Python ورژن میں کوئی چیز تنصیب کو نہیں توڑ سکتی، اور سرور کی طرف کی تبدیلیاں پلگ ان کے نئے اجرا کے بغیر پہنچ جاتی ہیں۔ اس کے بدلے میں قابلِ اعادہ پن جاتا ہے: آپ کلائنٹ کی طرف سے ٹولز کی سطح کو مقفل نہیں کر سکتے۔

فائل marketplace.json مخزن کو اس کا اپنا تقسیمی راستہ بنا دیتی ہے

پلگ ان Claude Code میں مارکیٹ پلیسوں سے نصب ہوتے ہیں، کسی پیکیج رجسٹری سے نہیں، اور مارکیٹ پلیس محض ایک JSON فائل ہے جو پلگ انوں کو ماخذ کے راستے کے ساتھ درج کرتی ہے۔ فولڈر .claude-plugin میں موجود دوسری فائل بالکل یہی کرتی ہے، اور اس کے واحد پلگ ان اندراج میں "source": "./" لکھا ہے۔ مخزن بیک وقت پلگ ان بھی ہے اور وہ مارکیٹ پلیس بھی جو اسے پیش کرتی ہے، چنانچہ اشاعت کا مطلب ایک عوامی git push ہے:

/plugin marketplace add finestructure-ai/claude-plugin
/plugin install finestructure@finestructure

دوسری سطر میں دو ایک جیسے ٹوکن دراصل پلگ ان کا نام اور مارکیٹ پلیس کا نام ہیں، جو اس لیے ٹکرا رہے ہیں کہ دونوں کا نام finestructure ہے۔ اگر آپ یہ ترتیب نقل کریں تو دونوں کے نام الگ رکھیے۔ تنصیب کی ہدایات زیادہ واضح ہو جاتی ہیں اور آپ کے پاس بعد میں دوسرا پلگ ان شامل کرنے کی گنجائش بھی رہتی ہے۔

کمانڈز دراصل frontmatter کے ساتھ پرامپٹ سانچے ہیں

فولڈر commands/ کی ہر فائل YAML frontmatter اور اس کے بعد نثر پر مشتمل ہے۔ فائل deploy.md ایک description اور ایک argument-hint کا اعلان کرتی ہے، یعنی وہ دو سطریں جو صارف کو انتخاب کی فہرست میں نظر آتی ہیں، اور پھر ایک شمار شدہ فیصلہ ساز شجرہ بچھاتی ہے: منصوبے کی جڑ میں .finestructure.json تلاش کرو جس میں app_id ہو، ورنہ list_apps کو پکارو اور نام کی مطابقت ڈھونڈو، ورنہ اسے پہلی تعیناتی سمجھو اور $ARGUMENTS کو ایپ کا نام بناؤ۔ فائل fs-status.md 741 بائٹ کی ہے اور ایک CLI ذیلی کمانڈ کا کام کرتی ہے: ایپ کی شناخت کرو، get_app_status، get_app_links اور get_errors کو پکارو، پھر خلاصہ دو۔ فائل fs-domain.md ترتیب کے ساتھ add_custom_domain، get_domain_verification، check_domain_verification، get_domain_ssl_status اور set_primary_domain سے گزرتی ہے۔

ڈیزائن کا نکتہ یہ ہے: ان میں سے کوئی فائل کسی چیز کو نہیں پکارتی۔ یہ ٹولز کے نام لیتی ہیں، ایک ترتیب طے کرتی ہیں، اور بتاتی ہیں کہ کوئی مرحلہ ناکام ہو تو کیا کرنا ہے۔ عمل درآمد اُس وقت ہوتا ہے جب ماڈل MCP ٹولز چلاتا ہے۔ سلیش کمانڈ ورژن کنٹرول میں محفوظ ایک پرامپٹ ہے، اس لیے اس کا جائزہ لینا یہ سوال نہیں کہ منطق درست ہے یا نہیں، بلکہ یہ سوال ہے کہ ہدایت مبہم تو نہیں۔

بہترین سطریں وہی ہیں جو منع کرتی ہیں۔ فائل deploy.md حذف کرنے والے ٹولز سے روکتی ہے جب تک صارف صراحتاً نہ کہے۔ فائل fs-domain.md بتاتی ہے کہ DNS کا پھیلاؤ منٹوں سے گھنٹوں تک لیتا ہے اور ہدایت دیتی ہے کہ تصدیق کے چکر میں پھنسنے کے بجائے بعد میں دوبارہ کوشش کا مشورہ دیا جائے۔ یہ جملوں کی صورت میں لکھی گئی دوبارہ کوشش کی پالیسی اور حفاظتی جنگلے ہیں، اور یہی وہ چیز ہے جو سادہ لوح پلگ ان چھوڑ دیتے ہیں۔

کھینچنا یا دھکیلنا: skill بمقابلہ command

فائل skills/fine-structure/SKILL.md میں frontmatter کے دو خانے ہیں، name اور description، اور یہ description خلاصے کے بجائے ایک محرک شرط کی طرح پڑھا جاتا ہے: جب بھی صارف کوئی ایپ تعینات، تخلیق یا اپ ڈیٹ کرنا چاہے، ڈومین جوڑنا چاہے، یا ڈیٹا اور خفیہ کلیدیں سنبھالنا چاہے تو اسے استعمال کیا جائے۔ یہ الفاظ جان بوجھ کر چنے گئے ہیں۔ کمانڈ اس لیے چلتی ہے کہ کسی انسان نے اسے ٹائپ کیا۔ skill اس لیے چلتی ہے کہ ماڈل نے تفصیل کو جاری صورتِ حال سے ملا لیا۔

مواد کی تقسیم اسی سے نکلتی ہے۔ فائل SKILL.md ایک ذہنی خاکہ ہے، کاموں کی فہرست نہیں: یہاں ایپ کیا ہے (JSX صفحات، مشترکہ اجزا، اینٹیٹی اسکیمے، من مانی سرور کوڈ نہیں)، اینٹیٹیز کیا ہیں، اور کون سے عمل کریڈٹ خرچ کرتے ہیں۔ پھر ورک فلو ٹولز کی زنجیروں کی صورت میں، get_app_files سے read_app_file، پھر write_app_file، پھر validate_app اور پھر publish_app تک، اور کئی فائلوں کی ترامیم کے لیے چینج سیٹ۔ پھر غلطیوں کے معنی، جو فی بائٹ سب سے زیادہ وزن رکھتے ہیں: توثیق کی غلطیوں کا مطلب دوبارہ جڑنا ہے، کریڈٹ کی غلطیوں کا مطلب رقم بھروانا ہے، اور ان میں سے کوئی بھی دوبارہ کوشش کے قابل نہیں۔ جس ایجنٹ کو یہ علم نہ ہو وہ ناقابلِ اعادہ ناکامی کو چکر میں دہراتا رہتا ہے، اور جہاں استعمال کا حساب لگتا ہو وہاں اس چکر کی قیمت ہوتی ہے۔

آپ کے اپنے پلگ ان کا اصول یہیں سے صاف نکل آتا ہے۔ اگر کوئی کمانڈ فائل یہ سمجھا رہی ہے کہ آپ کی مصنوعات ہے کیا، تو وہ پیراگراف skill میں جانا چاہیے۔ کمانڈز طریقۂ کار ہی رہیں۔

مینی فیسٹ میں کوئی راز نہ ہونے کی وجہ OAuth ہے

اینڈ پوائنٹ متحرک کلائنٹ رجسٹریشن کے ساتھ OAuth 2.1 کے ذریعے توثیق کرتا ہے، اس لیے پہلی ٹول کال براؤزر میں رضامندی کا صفحہ کھولتی ہے اور ٹوکن Claude Code کے اسنادی ذخیرے میں جاتا ہے، مخزن میں نہیں۔ فورک بنانا ساخت ہی کی وجہ سے محفوظ ہے، اجازت کی منسوخی سرور کی طرف ہوتی ہے، نہ کہ کسی ایسی کنفیگریشن ترمیم کے طور پر جسے ہر مشین تک پہنچنا پڑے، اور کسی سے یہ نہیں کہا جاتا کہ وہ طویل المدت کلید ایسی فائل میں چسپاں کرے جو ایک بےدھیان کمٹ کے فاصلے پر عوامی diff بن سکتی ہے۔

اپنے پلگ ان کے لیے کیا نقل کریں

ٹھوس اشارے، تقریباً بنانے کی ترتیب سے:

• آغاز .claude-plugin/plugin.json سے کریں جس میں name، version اور description ہوں۔ باقی سب اختیاری ہے۔
• اگر آپ میزبان MCP اینڈ پوائنٹ چلاتے ہیں تو مقامی کمانڈ کے بجائے url کے ساتھ "type": "http" کا اعلان کریں۔ اس سے صارف کا رن ٹائم آپ کی معاونت کی سطح سے حذف ہو جاتا ہے۔
• جب تک آپ کا ایک ہی پلگ ان ہے، اسی مخزن میں "source": "./" کے ساتھ marketplace.json رکھیں، اور اس کا نام پلگ ان کے نام سے مختلف رکھیں۔
• ہر کمانڈ کو frontmatter میں ایک description اور ایک argument-hint دیں، اور انہیں ان دو سوالوں کے جواب کی طرح لکھیں کہ یہ کرتی کیا ہے اور اس کے بعد کیا ٹائپ کرنا ہے۔
• مقامی ترتیبی نحو ایجاد کرنے کے بجائے $ARGUMENTS استعمال کریں۔ یہاں کوئی پارسر نہیں، صرف تبدیلی ہے۔
• کمانڈ کے متن کو فیصلہ ساز شجرے کی طرح لکھیں اور ٹولز کے نام صراحت سے دیں۔ جملہ "اگر کنفیگ فائل موجود ہو تو app_id پڑھو، ورنہ list_apps کو پکارو" ارادوں کے ایک پیراگراف سے بہتر ٹھہرتا ہے۔
• ناکامی کے معنی تحریر میں لائیں: کون سی غلطیاں حتمی ہیں، کون سی دوبارہ کوشش کے قابل ہیں، اور دوبارہ کوشش کے بجائے کیا کہنا ہے۔
• اپنے تباہ کن ٹولز کے نام نثر میں لکھیں اور جب تک کہا نہ جائے ان سے منع کریں۔
• دائرۂ کار کا خاکہ SKILL.md میں رکھیں اور طریقۂ کار کمانڈ میں۔ دونوں کے درمیان تکرار ایک خراب علامت ہے۔
• کسی کو main کی طرف بھیجنے سے پہلے /plugin marketplace add کو کسی مقامی راستے یا اپنے فورک کے ساتھ آزمائیں۔

ناہموار کنارے

دیانت داری سے تین، اور ان میں سے کوئی مہلک نہیں۔ سب کچھ انگریزی میں ہے، اور فارمیٹ اسے درست کرنے کے لیے کوئی گنجائش نہیں دیتا: frontmatter میں locale کی کوئی کلید نہیں، اس لیے مقامی کاری کا مطلب یا تو کمانڈ فائلوں کی نقل ہے یا اس عدم مطابقت کو قبول کر لینا۔

کوئی API کلید نہ ہونے والی کہانی پر ایک ستارہ لگا ہوا ہے۔ فائل SKILL.md تسلیم کرتی ہے کہ میڈیا بنانے والے ٹولز OAuth کنکشن سے باہر ہیں اور انہیں میڈیا اختیارات والا ایک ساکت MCP ٹوکن درکار ہے، جو پلیٹ فارم کے Studio میں بنتا ہے اور bearer ہیڈر میں بھیجا جاتا ہے۔ پلگ ان اسے اچھے طریقے سے سنبھالتا ہے اور ماڈل سے کہتا ہے کہ دیوار سے ٹکرانے کے بجائے اس کمی کی وضاحت کرے، مگر یہ توثیق کا دوسرا راستہ ہے جو ایسے ڈیزائن پر جوڑا گیا ہے جس کی سب سے بڑی خوبی ایک ہی راستہ ہونا ہے۔

اور یہ ورژن 0.1.0 ہے، نہ changelog، نہ ٹیسٹ، نہ CI۔ markdown کے لیے یہ قابلِ دفاع ہے، اگرچہ pre-commit hook میں JSON اسکیما کی جانچ اُسی واحد قسم کی غلطی پکڑ لیتی جو واقعی تنصیب توڑتی ہے، یعنی خراب مینی فیسٹ۔ ڈائریکٹری میں شمولیت کی درخواست ان سطور کے لکھے جانے تک زیرِ غور ہے، اس لیے فی الحال تنصیب مخزن کے حوالے سے ہوتی ہے۔

پہلے تینوں کمانڈ فائلیں پڑھیں، پھر SKILL.md، اور پھر دونوں JSON فائلیں۔ اسی ترتیب میں فارمیٹ خود اپنی وضاحت کر دیتا ہے: markdown طے کرتا ہے کہ کیا ہونا چاہیے اور کس ترتیب سے، MCP سرور طے کرتا ہے کہ اصل میں چلتا کیا ہے، اور مینی فیسٹ ان دونوں کے درمیان باریک جوڑ ہے۔