Skillbox کو خود ہوسٹ کریں: AI ایجنٹس کے لیے ورژن شدہ اسکلز لائبریری بنائیں

Skillbox کیا ہے؟

Skillbox، AI ایجنٹس کے لیے MIT لائسنس یافتہ، خود میزبان اسکلز لائبریری ہے۔ یہ دوبارہ قابلِ استعمال اسکل پیکیجز بنانے، درآمد کرنے، ورژن کرنے، تقسیم کرنے اور آڈٹ کرنے کے لیے ایک مرکزی جگہ فراہم کرتی ہے۔ یہ ایپلیکیشن React، Bun، Hono اور PostgreSQL کے ساتھ بنائی گئی ہے۔

نئی تنصیب دانستہ طور پر خالی ہوتی ہے۔ اس میں ذاتی اسکلز، صارف اکاؤنٹس، کلائنٹ کیز، بیرونی سروس اینڈ پوائنٹس یا ادائیگی والے AI فراہم کنندگان کی اسناد شامل نہیں ہوتیں۔ Skillbox اسکل کا مواد تقسیم کرتا ہے، لیکن اپ لوڈ کیے گئے اسکل کوڈ کو کبھی بھی execute نہیں کرتا۔

اہم خصوصیات

• ورژن شدہ تدوین: Markdown اور معاون فائلوں میں immutable revisions، تنازع کی شناخت اور بحالی کے ساتھ ترمیم کریں۔
• محدود دائرہ کار کی رسائی: اسکل یا بنڈل grants والے پروفائلز بنائیں اور create، update، archive اور proposal کی اجازتیں الگ الگ مقرر کریں۔
• منسوخ کیے جا سکنے والے کلائنٹس: انفرادی کلائنٹ کیز جاری کریں، استعمال کا جائزہ لیں اور ضرورت پڑنے پر آئندہ رسائی منسوخ کریں۔
• MCP اور CLI رسائی: HTTP MCP براہِ راست استعمال کریں، Node یا Bun stdio bridge کے ذریعے مربوط ہوں، یا checksum verification کے ساتھ پیکیجز ڈاؤن لوڈ کریں۔
• MCP وسائل: بنیادی MCP resource listing اور reading کے ذریعے مجاز اور compatible اسکلز ظاہر کریں۔
• اختیاری سفارشات: اپنے Vercel AI Gateway یا TypeSafe AI key کے ساتھ Jev استعمال کریں۔
• ڈیٹا کی منتقلی: native فولڈرز درآمد اور برآمد کریں، محفوظ بیک اپ بنائیں اور ڈیٹا واضح طور پر بحال کریں۔
• خود میزبان تعیناتی: Docker Compose کے ساتھ چلائیں، HTTPS کے لیے اختیاری طور پر Caddy کو سامنے رکھیں، یا Umbrel پیکیج تیار کریں۔

Skillbox کو محدود دائرہ کار والے کلائنٹس کے ساتھ واحد مالک کی خود میزبان ایپلیکیشن کے طور پر ڈیزائن کیا گیا ہے۔ یہ عوامی multi-tenant SaaS پلیٹ فارم نہیں ہے۔

ضروریات

تجویز کردہ تنصیب کے لیے Docker Engine یا Docker Desktop بمع Compose v2، نیز Linux، macOS یا WSL پر Bash درکار ہے۔ Docker پر مبنی سیٹ اپ کے لیے میزبان پر Bun یا Node.js انسٹال کرنے کی ضرورت نہیں۔

Skillbox انسٹال اور شروع کریں

1. repository کلون کریں اور اس کی ڈائریکٹری میں جائیں:

   git clone https://github.com/kitze/skillbox.git
   cd skillbox

2. مقامی environment فائل بنائیں:

   bash scripts/skillbox.sh setup

   یہ منفرد بے ترتیب credentials کے ساتھ .env بناتا ہے، اس کا mode 0600 مقرر کرتا ہے اور موجودہ فائل کو overwrite کرنے سے انکار کرتا ہے۔

3. Docker services شروع کریں:

   bash scripts/skillbox.sh start

4. اپنے browser میں http://127.0.0.1:4791 کھولیں۔

5. اپنی مقامی .env فائل سے SKILLBOX_ADMIN_TOKEN پڑھیں اور سائن ان کرنے کے لیے استعمال کریں۔ setup script دانستہ طور پر یہ token ظاہر نہیں کرتی۔

.env کو نجی رکھیں۔ مالک کا token انتظامی رسائی کو کنٹرول کرتا ہے اور محفوظ شدہ integration credentials کے تحفظ میں بھی شامل ہوتا ہے۔

ریموٹ تعیناتی

ریموٹ تنصیب کے لیے SKILLBOX_ORIGIN کو تعیناتی کے HTTPS origin پر مقرر کریں اور TLS reverse proxy تشکیل دیں۔ production instance کو غیر خفیہ HTTP پر ظاہر نہ کریں۔ معاون deployment تفصیلات کے لیے repository کی deployment notes دیکھیں۔

Docker-only application setup کے بغیر مقامی development

اگر آپ کے پاس پہلے سے Bun اور PostgreSQL 16 یا اس سے نیا database موجود ہے تو dependencies انسٹال کریں اور application براہِ راست شروع کریں:

bun install --frozen-lockfile
# Set DATABASE_URL
# Set SKILLBOX_ADMIN_TOKEN to at least 32 random characters
# Set SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

تینوں مطلوبہ values کو source control میں commit کرنے کے بجائے محفوظ environment میں رکھیں۔

اسکلز اور محدود دائرہ کار والے کلائنٹس بنائیں

سائن ان کرنے کے بعد editor میں اسکل بنائیں یا موجودہ اسکل پیکیج درآمد کریں۔ اسکل revisions immutable ہوتی ہیں، اس لیے کلائنٹس تبدیل ہوتے مواد پر انحصار کرنے کے بجائے مخصوص revision لوڈ یا fetch کر سکتے ہیں۔

اس کے بعد profile بنائیں اور اسے مطلوبہ اسکلز یا bundles تک رسائی دیں۔ کلائنٹ کے مقصد کے مطابق create، update، archive اور proposal permissions الگ الگ مقرر کریں۔ آخر میں اس profile کا استعمال کرتے ہوئے client connection بنائیں۔

Client keys صرف ایک بار دکھائی جاتی ہیں اور Skillbox صرف ان کے hashes محفوظ کرتا ہے۔ ہر key کو فوراً محفوظ client configuration میں محفوظ کریں۔ مالک کا token تقسیم کرنے کے بجائے ہر client کے لیے الگ key استعمال کریں۔

CLI تشکیل دیں

CLI ایک JSON configuration پڑھتی ہے جس میں Skillbox URL اور client key شامل ہوتے ہیں۔ اس کا default path ~/.config/skillbox/config.json ہے۔

{
  "url": "https://skills.example.com",
  "token": "YOUR_CLIENT_KEY"
}

فائل کا mode 0600 مقرر کریں۔ SKILLBOX_URL اور SKILLBOX_TOKEN environment variables، configuration file کی values کو override کرتے ہیں۔ اگر کوئی URL configured نہ ہو تو CLI محفوظ طور پر localhost کو target کرتی ہے، نہ کہ کسی دوسرے شخص کی service کو۔

cli/skillbox.mjs اور cli/package.mjs کو ساتھ رکھیں۔ پھر آپ مجاز اسکلز تلاش اور حاصل کر سکتے ہیں:

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs fetch my-skill@REVISION

fetch operation فائلیں atomically لکھنے سے پہلے paths، file hashes، sizes، executable flags اور package checksum کی توثیق کرتی ہے۔ یہ code execute یا dependencies install نہیں کرتی۔

اپ ڈیٹ شدہ اسکل شائع کریں

جس skill ID اور revision کو آپ update کرنے کی توقع رکھتے ہیں، انہیں فراہم کر کے مقامی folder شائع کریں:

node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

متوقع نظرثانی تنازع کا پتا لگانے کی معاونت کرتی ہے۔ اشاعت کا انحصار کلائنٹ پروفائل کو دی گئی اجازتوں پر بھی ہوتا ہے۔

آڈٹ کی مطابقت

مالک غیر تغییری مطابقت آڈٹ چلا سکتا ہے:

node cli/skillbox.mjs audit

جب کمانڈ کو غیر مطابقت پذیر پیکیجز ملتے ہیں تو یہ اسٹیٹس 1 کے ساتھ ختم ہوتی ہے۔ یہ موجودہ پیکیجز کو دوبارہ لکھے بغیر MCP Skills کی مطابقت کا جائزہ لینے کے لیے آپ کو تیار کرتی ہے۔

MCP کے ذریعے AI ایجنٹ مربوط کریں

bootstrap/SKILL.md کو ایجنٹ کے skills-library بوٹسٹریپ کے طور پر انسٹال کریں۔ HTTP MCP کی معاونت کرنے والے کلائنٹس آپ کی انسٹنس کے /mcp اینڈ پوائنٹ سے مربوط ہو سکتے ہیں اور کلائنٹ کلید کو بیئرر ٹوکن کے طور پر بھیج سکتے ہیں:

Authorization: Bearer YOUR_CLIENT_KEY

ایسے MCP کلائنٹ کے لیے جسے stdio درکار ہو، شامل کردہ برج ترتیب دیں:

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": [
        "/absolute/path/to/skillbox/cli/skillbox.mjs",
        "mcp"
      ],
      "env": {
        "SKILLBOX_URL": "https://skills.example.com",
        "SKILLBOX_CONFIG": "/absolute/path/to/protected-client-config.json"
      }
    }
  }
}

بنیادی MCP ٹولز میں search_skills، recommend_skills، load_skill، read_skill_file، اور report_skill_use شامل ہیں۔ تحریری اور تجویزی ٹولز صرف اسی وقت ظاہر ہوتے ہیں جب کلائنٹ کے پروفائل میں متعلقہ اجازتیں دی گئی ہوں۔

Skillbox بنیادی MCP کے resources/list اور resources/read کے ذریعے مجاز مطابقت پذیر اسکلز بھی فراہم کرتا ہے۔ معاون بائنری اور بڑی فائلوں تک بطور وسائل رسائی حاصل کی جا سکتی ہے، لیکن کسی وسیلے کو پڑھنے سے اسکل فعال یا اجرا نہیں ہوتی۔

مکمل io.modelcontextprotocol/skills معاونت ابھی مشتہر نہیں کی گئی۔ موجودہ نفاذ بنیادی MCP پروٹوکول کے ذریعے تیاری کی خصوصیات فراہم کرتا ہے، جبکہ مقامی دریافت اور مذاکرات اب بھی SDK اور پروٹوکول اپ گریڈ پر منحصر ہیں۔

تلاش اور سفارشات درست طریقے سے استعمال کریں

کسی کام کے آغاز پر ایجنٹس کو متعلقہ مجاز اسکلز کی فہرست بنانے کے لیے اب بھی search_skills کال کرنا چاہیے۔ سفارشات اضافی ہیں اور تلاش کے اس مرحلے کی جگہ نہیں لیتیں۔ منتخب اسکل لاگو کرنے سے پہلے اسے Skillbox سے واپس کی گئی غیر تغییری نظرثانی کا استعمال کرتے ہوئے لوڈ کریں۔

بیرونی سفارش فراہم کنندہ کے بغیر، آپ CLI سے تلاش کر سکتے ہیں:

node cli/skillbox.mjs search "database migration"

کام سے آگاہ سفارشات کی درخواست کرنے کے لیے:

node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"

اس کا مساوی MCP آپریشن recommend_skills({task, limit?, offset?}) ہے۔ HTTP کلائنٹس وہی تصدیق شدہ JSON باڈی POST /api/skill-recommendations کو بھیج سکتے ہیں۔

اختیاری Jev سفارشات ترتیب دیں

1. Settings → Jev recommendations کھولیں۔

2. Vercel AI Gateway منتخب کریں، جو طے شدہ انتخاب ہے، یا TypeSafe AI منتخب کریں۔

3. منتخب فراہم کنندہ کے لیے اپنی API کلید درج کر کے محفوظ کریں۔

فراہم کنندگان کی کلیدیں الگ الگ محفوظ کی جاتی ہیں۔ TypeSafe منتخب کرنے سے محفوظ Gateway کلید TypeSafe کو نہیں بھیجی جاتی، اور فراہم کنندگان تبدیل کرنے پر پہلے محفوظ کی گئی کلید برقرار رہتی ہے۔ منتخب فراہم کنندہ کی کلید ہٹانے سے اس فراہم کنندہ کے لیے ماڈل کالز غیر فعال ہو جاتی ہیں۔

کلید PostgreSQL میں SKILLBOX_ADMIN_TOKEN سے اخذ کردہ کلیدی مواد کا استعمال کرتے ہوئے AES-256-GCM کے ذریعے خفیہ کی جاتی ہے۔ اسے سیٹنگز API کے ذریعے واپس نہیں کیا جاتا اور نہ ہی براؤزر بنڈلز میں شامل کیا جاتا ہے۔ دستاویزی گردش کے عمل کی پیروی کیے بغیر مالک کا ٹوکن تبدیل کرنے سے محفوظ انٹیگریشن اسناد ناقابلِ مطالعہ ہو جاتی ہیں۔

کلید محفوظ کرنے سے فراہم کنندہ تک رسائی یا کریڈٹس کی خریداری کی تصدیق نہیں ہوتی۔ Jev کام کا متن اور مجاز فعال اسکلز کی وضاحتیں منتخب فراہم کنندہ کو بھیجتا ہے، اس لیے اس فراہم کنندہ کی بلنگ اور ڈیٹا ہینڈلنگ کی شرائط لاگو ہوتی ہیں۔

سفارش کے نتائج اور متبادل طریقوں کو سمجھیں

Jev مکمل مجاز، فعال، غیر محفوظ شدہ لیف کیٹلاگ کا جائزہ لیتا ہے، جو زیادہ سے زیادہ 200 لیف یا 120,000 سیریلائز کردہ حروف تک محدود ہے۔ بڑے کیٹلاگ کسی غیر ظاہر کردہ ذیلی مجموعے کی درجہ بندی کرنے کے بجائے واضح طور پر متبادل طریقے پر چلے جاتے ہیں۔

• متعلقہ ہونے کا اسکور 0 سے 4 تک کا غیر کیلیبریٹڈ اسکور ہے، احتمال نہیں۔
• کم از کم 3 اسکور کرنے والے نتائج پہلے نزولی اسکور اور پھر ID کے لحاظ سے واپس کیے جاتے ہیں۔
• noMatch=true کا مطلب ہے کہ جائزہ لیے گئے کسی امیدوار نے حد حاصل نہیں کی۔
• غائب کلید، فراہم کنندہ کی خرابی، ناقص جواب، شرح کی حد، گنجائش کی حد، یا آٹھ سیکنڈ کی آخری مدت PostgreSQL تلاش کے متبادل طریقے کو فعال کرتی ہے۔
• متبادل نتائج میں method=search، relevance=null، اور ایک fallbackReason استعمال ہوتا ہے۔

عملی سطح کا کیش زیادہ سے زیادہ 128 اندراجات پانچ منٹ تک رکھتا ہے۔ Skillbox بیک وقت دو جائزوں اور ہر اسکوپ کے لیے فی منٹ دس غیر کیش شدہ درخواستوں کی اجازت دیتا ہے، خودکار دوبارہ کوششوں کے بغیر۔ اجازتوں کے اجرا، لائف سائیکل کی حالت، اور نظرثانیوں کی جانچ ماڈل کالز سے پہلے اور بعد میں، کیش ہٹس سمیت، کی جاتی ہے۔

ڈیٹا درآمد، برآمد اور بیک اپ کریں

اگر Bun دستیاب ہو تو اسکلز کا فولڈر اس طرح درآمد کریں:

bun scripts/import.ts /path/to/skills

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

اسکل کا مواد خالی منزل پر برآمد کریں:

SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts

PostgreSQL ڈیٹا بیس اصل ماخذ برقرار رہتا ہے۔ برآمد کردہ فولڈر میں ترمیم کرنے سے ڈیٹا بیس تبدیل نہیں ہوتا جب تک مواد دوبارہ شائع نہ کیا جائے۔

محفوظ بیک اپ بنائیں:

bash scripts/backup.sh

ایکسپورٹس اور بیک اپس میں نجی اسکل کا مواد شامل ہو سکتا ہے۔ انہیں عوامی ایپلیکیشن سورس سے الگ رکھیں۔ اختیاری GitHub ایکسپورٹ اسکرپٹ کے لیے واضح طور پر تشکیل دیا گیا، مخصوص نجی ایکسپورٹ چیک آؤٹ درکار ہے اور یہ خودکار طور پر فعال نہیں ہوتا۔

اعلیٰ درجے کی عملی تجاویز

ہر انٹیگریشن کے لیے ایک کلائنٹ کی استعمال کریں

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

محدود دائرہ کار والے پروفائلز کو ترجیح دیں

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

اونر ٹوکن اور بیک اپس کو محفوظ رکھیں

اونر ٹوکن انتظامی رسائی فراہم کرتا ہے اور محفوظ کردہ انٹیگریشن اسناد کے لیے انکرپشن مواد اخذ کرتا ہے۔ اسے ڈیٹابیس اور کنفیگریشن بیک اپس کے ساتھ محفوظ رکھیں، اور اسے تبدیل کرنے سے پہلے دستاویزی روٹیشن طریقۂ کار پر عمل کریں۔

اسکلز کو مواد سمجھیں، قابلِ اعتماد پروگرام نہیں

Skillbox پیکیج فائلوں کی توثیق اور تقسیم کرتا ہے، انہیں چلاتا نہیں۔ ایجنٹ ورک فلو میں ڈاؤن لوڈ کردہ ہدایات اور کوڈ استعمال کرنے سے پہلے ان کا جائزہ لیتے رہیں۔

سفارشات کا محتاط انداز میں بینچ مارک کریں

ڈیولپرز اپنی فراہم کنندہ کی کے ذریعے اختیاری، قابلِ معاوضہ بینچ مارک چلا سکتے ہیں:

bun scripts/benchmark-recommendations.ts --live --provider vercel
bun scripts/benchmark-recommendations.ts --live --provider typesafe

Vercel کے لیے AI_GATEWAY_API_KEY یا TypeSafe کے لیے TYPESAFE_API_KEY یا JEV_KEY استعمال کریں۔ یہ اسکرپٹ ایپلیکیشن کو تشکیل نہیں دیتا اور نہ ہی اسناد محفوظ کرتا ہے۔ اس کا مصنوعی نمونہ پروڈکشن لیٹنسی کی ضمانت یا امکانات کی کیلیبریشن نہیں ہے۔

ڈیپلائمنٹ یا شراکت کی توثیق کریں

تبدیلیاں ڈیپلائے کرنے سے پہلے ٹائپ چیکنگ اور الگ تھلگ ٹیسٹ سوٹ چلائیں:

bun run typecheck
bash scripts/test-isolated.sh

الگ تھلگ سوٹ اپنا Docker Compose PostgreSQL انسٹنس بناتا اور ختم کرتا ہے، اور ڈیٹابیس پورٹس شائع نہیں کرتا۔ یہ اجازت، نظرثانیاں، API اور MCP کا رویہ، CLI، انکرپٹڈ سیٹنگز، اور سفارشات کا احاطہ کرتا ہے۔ ڈیٹابیس ٹیسٹس کو کبھی بھی پروڈکشن کی طرف مت بھیجیں۔

نتیجہ

Skillbox دوبارہ قابلِ استعمال AI-agent اسکلز کے انتظام کے لیے ایک کنٹرول شدہ، خود میزبان ورک فلو فراہم کرتا ہے۔ Docker سیٹ اپ سے شروع کریں، ورژن شدہ اسکلز بنائیں، محدود دائرہ کار والے پروفائلز تفویض کریں، اور ہر ایجنٹ کو اس کی اپنی کلائنٹ کی سے مربوط کریں۔ اس کے بعد آپ اپنے کیٹلاگ اور اسناد کی ملکیت برقرار رکھتے ہوئے MCP رسائی، اختیاری Jev سفارشات، پورٹیبلٹی ورک فلو، اور بیک اپس شامل کر سکتے ہیں۔