AI Agents کے لیے Plugins: ایک bundle، آپ کی پوری team

13 Concepts، real use کا 80% · تقریباً 90 منٹ کا concept read · پہلے real plugin کے لیے ایک focused دن · empty folder سے ایسے plugin تک جسے teammate ایک command سے install کرے

First: plugin اصل میں کیا ہے۔ Out of the box، Claude Code یا OpenCode جیسا coding agent ایک capable generalist ہے۔ یہ کسی بھی project میں کام کر سکتا ہے، مگر اسے آپ کا working style نہیں پتا۔ Plugin وہ package ہے جو one install میں یہ gap fix کرتا ہے: یہ وہ playbooks bundle کرتا ہے جنہیں agent follow کرتا ہے (skills)، وہ specialists جنہیں یہ delegate کرتا ہے (subagents)، وہ systems جن تک یہ پہنچ سکتا ہے (MCP servers)، آپ کی standing instructions، اور وہ rules جنہیں یہ skip نہیں کر سکتا (hooks)۔ یہ bundle generic agent کو دیں تو وہ آپ کا بن جاتا ہے، اور teammate اسے install کرے تو اسے exact same one ملتا ہے۔

اب اسے real دیکھیں۔ Anthropic ان کی پوری marketplace ship کرتا ہے۔ دو commands، claude plugin marketplace add anthropics/knowledge-work-plugins پھر claude plugin install finance@knowledge-work-plugins، اور blank Claude finance specialist بن جاتا ہے: skills خود fire ہوتی ہیں، /finance:reconciliation جیسی commands آتی ہیں، اور finance team کے systems سے connectors ملتے ہیں۔ finance کی جگہ sales یا legal رکھیں تو وہ specialist مل جاتا ہے۔ یہی plugin ہے: one install generalist کو exact expert بنا دیتا ہے جس کی آپ کو ضرورت ہے۔ اس course کے آخر تک آپ اپنا plugin بنا چکے ہوں گے، اور وہ direction دیکھ چکے ہوں گے جہاں یہ لے جاتا ہے: اس book کی sellable domain marketplaces، جیسے agentfactory-business (banking، legal-ops، Islamic finance)، جو Anthropic کے اوپر regulated-domain depth layer کرتی ہیں۔

Bundle host-specific ہے؛ اندر کی اکثر چیزیں نہیں۔ Claude Code plugin اور OpenCode plugin وہی pieces مختلف formats میں wrap کرتے ہیں جو ایک دوسرے میں load نہیں ہوتے (Concept 2 بتاتا ہے کیوں)۔ مگر pieces mostly travel کرتے ہیں: skill ہر جگہ وہی SKILL.md ہے، instructions وہی markdown ہیں، MCP server ایک URL ہے جس کی طرف کوئی بھی host point کر سکتا ہے۔ صرف hook truly per-host ہے، کیونکہ وہ host کی internal machinery میں plug ہوتا ہے (Concept 7 میں آپ exact فرق دیکھیں گے)۔ اس لیے آپ اپنے host کے لیے build کرتے ہیں، اور اندر کی اکثر چیزیں پھر بھی claude.ai، Codex، Cursor، حتیٰ کہ OpenClaw جیسے personal agent تک پہنچتی ہیں۔

اور آپ اصل میں یہی سیکھنے آئے ہیں۔ آپ کے agent کو syntax پہلے سے آتا ہے؛ وہ command پر hook یا manifest لکھ سکتا ہے۔ اگر course صرف یہی سکھاتا تو agent اسے pointless بنا دیتا۔ Scarce چیز وہ judgment ہے جو agent کے پاس نہیں: کس job کو کون سا lever چاہیے، کب rule کو hope نہیں guarantee ہونا چاہیے، اور plugin کے claim کو prove کیسے کرنا ہے۔ آپ plain English میں direct کرتے ہیں، empty folder سے ہر lever خود build کرتے ہیں، ساتھ میں complete proven build compare کے لیے موجود ہوتا ہے، اور ایک real plugin ship کرتے ہیں جسے teammate one command سے install کرتا ہے۔ Decisions آپ کرتے ہیں؛ typing agent کرتا ہے۔

سب کچھ ایک fact سے نکلتا ہے: آپ ایسے agent کو extend کرتے ہیں جسے آپ own نہیں کرتے۔ Host loop، model، اور machine own کرتا ہے۔ آپ کا plugin show نہیں چلاتا؛ یہ host کو load کرنے کے pieces دیتا ہے۔ اس سے چار non-negotiables نکلتے ہیں، اور whole course یہی چار build کرتا ہے:

1. Share کرنے کے لیے bundle۔ Plugin customization کی shareable، versioned form ہے۔ اگر یہ صرف آپ کے لیے ایک repo میں ہے، تو آپ کو .claude/ folder چاہیے، plugin نہیں۔ Plugin تب بنائیں جب دوسروں کو بھی یہ ملنا چاہیے۔
2. Job کے لیے right lever۔ Skill وہ knowledge ہے جسے agent choice سے use کرتا ہے؛ subagent وہ work ہے جسے یہ delegate کرتا ہے؛ MCP server tools اور data ہیں جن تک یہ پہنچتا ہے؛ hook code ہے جو fixed moments پر خود چلتا ہے۔ Job کو lever سے match کریں۔
3. Must-always hook ہے، instruction نہیں۔ Skill یا CLAUDE.md میں لکھی بات advice ہے جسے model skip کر سکتا ہے۔ Hook code ہے جو ہر بار چلتا ہے۔ اگر کوئی چیز ہونی ہی ہے، formatter یا safety gate، تو وہ hook ہے۔
4. Plugin user کے trust میں چلتا ہے۔ یہ installer کی machine پر code execute کرتا ہے۔ Least privilege کے ساتھ build کریں، صاف بتائیں یہ کیا touch کرتا ہے، اور install یا ship کرنے کو trust decision سمجھیں۔

ہر Concept پڑھتے وقت پوچھیں: یہ کون سا invariant ہے؟

note

Prerequisites۔ یہ page تین چیزیں assume کرتا ہے۔

1. آپ coding agent drive کرتے ہیں۔ آپ نے Agentic Coding Crash Course کر رکھا ہے: Claude Code یا OpenCode، plan mode، rules file۔ ہم اسی workbench کے ذریعے build کرتے ہیں۔
2. آپ typed code پڑھ سکتے ہیں: shell، تھوڑا JSON، اور TypeScript؛ براہ راست یا blocks اپنے agent کو paste کر کے plain-English explanation لینے کے ذریعے۔
3. Recommended: Connector-Native Apps۔ اس course نے یہی habit سکھائی تھی: جانیں کہ آپ کس layer پر ہیں، اور MCP server build کیا تھا۔ Plugin ایک MCP server bundle کر سکتا ہے (Concept 6)، اس لیے دونوں courses جڑتے ہیں۔

آپ کو پہلے Build AI Agents یا AI Identity کرنے کی ضرورت نہیں۔ دونوں path میں بعد میں آتے ہیں، اور یہ course انہی کی طرف اشارہ کرتا ہے۔

note

یہ کہاں fit ہوتا ہے۔ Mode 2 میں، Connector-Native Apps کے فوراً بعد۔ Path یہ ہے: Connector-Native Apps → یہ course → AI Identity (sign-in & agent access) → Build AI Agents۔ Connector-native apps end users کے لیے chat app کو extend کرتی ہیں؛ plugins builders کے لیے coding agent کو extend کرتے ہیں۔ Same move، دوسرا host۔

تیاری (چند منٹ)

آپ یہاں shell commands ہاتھ سے نہیں چلائیں گے۔ آپ اپنے coding agent کو plain English میں direct کرتے ہیں اور check کرتے ہیں کہ یہ کیا report کرتا ہے؛ یہی loop آپ plugin build کرنے میں use کریں گے۔ Setup اسی کی پہلی rep ہے۔

1. Base download کریں (plugins-crash-course-base.zip)، unzip کریں، اور plugins-crash-course folder کو Claude Code (یا OpenCode) میں open کریں۔ Open ہوتے ہی agent AGENTS.md پڑھتا ہے: آپ کا brief کہ کیا build کرنا ہے اور proven reference کہاں ہے۔

2. اسے setup کرنے کو کہیں۔ Paste کریں:

Set up my base environment, then tell me what you did and what passed.

اس one line کے پیچھے agent AGENTS.md کے brief کو follow کرتا ہے: Claude Code پر یہ official plugin-structure skill install کرتا ہے تاکہ current spec سے کام کرے؛ OpenCode پر plugin docs پڑھتا ہے؛ پھر reference build کے checks run کرتا ہے۔

3. اب اسے layout explain کروائیں۔ Paste کریں:

Walk me through, in plain English, how a plugin is laid out on my host.

Done when agent report کرے کہ reference build green ہے (guard .env اور rm -rf block کرتا ہے، sample skill اور MCP server check out ہیں) اور یہ آپ کو host کا plugin layout explain کر سکے۔

Box میں کیا ہے۔ ابھی آپ کا تقریباً کچھ نہیں؛ یہی point ہے۔ Plugin آپ build کرتے ہیں؛ starter آپ کو brief اور proven build دیتا ہے جس کے against آپ اپنا کام check کرتے ہیں۔

plugins-crash-course/           ← you build YOUR marketplace + plugin here, from blank
  AGENTS.md                     your brief + how each host lays out a plugin
  CLAUDE.md                     points Claude Code at the same brief (@AGENTS.md)
  reference/                    a COMPLETE, PROVEN build — read it, diff against it, don't copy it
    plugins/agent-factory/      the finished plugin: proven guard, a model skill, a model reviewer
    server/                     a runnable MCP server you point your plugin at
    verify.sh                   one command that proves the reference is sound

آپ ہر lever خود build کرتے ہیں: guard hook، ایک skill جو واقعی آپ کے کام آتی ہے، reviewer subagent، MCP wiring، marketplace۔ آپ plain English میں agent کو direct کرتے ہیں۔ جب کوئی piece غلط آئے، اسے reference/، یعنی known-good version، کے against diff کرتے ہیں۔ آپ direct کرتے ہیں؛ agent type کرتا ہے؛ آپ check کرتے ہیں؛ آپ compare کرتے ہیں۔

---

Build کرنے سے پہلے ایک کو چلتا دیکھیں (5 منٹ)

آپ نے ابھی پڑھا کہ plugin کیا کرتا ہے۔ اب اسے محسوس کریں۔ Concepts سے پہلے starter میں shipped finished plugin install کریں اور دیکھیں کہ یہ کچھ enforce کرتا ہے۔ پہلے دیکھنا ہی باقی course کو land کرواتا ہے۔

Reference plugin کو session میں load کریں:

claude --plugin-dir reference/plugins/agent-factory

OpenCode میں reference/plugins/agent-factory open کریں۔ یہ guard اس folder کی .opencode/plugins/ سے اور skill اس کے skills/ سے load کرتا ہے۔

پھر اسے کام پر لگائیں۔ Paste کریں:

Try to read a file called .env, then use your loop-engineering skill to explain an agent loop in four moves.

آپ کو کیا نظر آنا چاہیے:

• Agent .env پڑھنے سے blocked ہے، اور وجہ بتاتا ہے۔ (hook، جو ایسے tool call پر fire ہوتا ہے جسے model skip نہیں کر سکتا)
• Skill اپنی voice میں answer دیتی ہے، بغیر اس کے کہ آپ اسے name کریں۔ (skill جسے model نے choose کیا)
• (Claude Code) اسے scruffy file fix کرنے کو کہیں تو وہ unasked auto-formatted واپس آتی ہے۔ (second hook)

.env پر یہ hard block وہ چیز ہے جو plain "please don't read secrets" instruction کبھی guarantee نہیں کر سکتی، اور اسے build کرنا اس course کا heart ہے۔ آپ نے per-file کچھ configure نہیں کیا؛ plugin behavior ساتھ لے کر آیا۔ اب concepts کے پاس attach ہونے کے لیے real چیز ہے۔

---

حصہ 1: ساخت

تصور 1: آپ agent کو extend کرتے ہیں؛ اسے own نہیں کرتے

Plugin وہ program نہیں جسے آپ run کرتے ہیں۔ یہ pieces کا set ہے جسے ایک host load اور run کرتا ہے۔ Host، Claude Code یا OpenCode، agent loop own کرتا ہے، یعنی decide-act-repeat cycle؛ model لاتا ہے؛ اور user کی machine پر چلتا ہے۔ آپ کا plugin capabilities اور rules contribute کرتا ہے جنہیں host pick up کرتا ہے۔ یہ picture درست ہو تو باقی detail ہے؛ غلط ہو تو آپ plugin سے وہ چیزیں کروانے کی کوشش کرتے رہیں گے جن کا charge اس کے پاس کبھی تھا ہی نہیں۔

یہاں ایک دلچسپ twist ہے، اور اسے نام دینا worth it ہے: آپ coding agent کو direction دیتے ہیں کہ coding agents کے لیے plugin build کرے۔ آپ Claude Code سے وہی extension لکھواتے ہیں جسے Claude Code خود load کرتا ہے۔ جو چیز اسے build کر رہی ہے اور جس چیز کو یہ extend کر رہا ہے، دونوں ایک ہی kind کے tool ہیں۔ یہ gimmick نہیں؛ یہ plugin build کرنے کا fastest راستہ ہے، اور ہر Manufacturing course یہی pattern follow کرتا ہے: آپ direct کرتے ہیں، agent type کرتا ہے، آپ verify کرتے ہیں۔

تصور 2: دو hosts، ایک idea

یہ course دو hosts cover کرتا ہے۔ وہ extensions کو differently package کرتے ہیں، مگر idea identical ہے: ایک unit جسے host load کرتا ہے۔

• Claude Code ایک declarative bundle لیتا ہے: components کا folder (skills، subagents، hooks، MCP servers) جسے ایک چھوٹا manifest describe کرتا ہے۔ آپ mostly configuration اور scripts لکھتے ہیں؛ Claude Code انہیں wire کرتا ہے۔
• OpenCode ایک code module لیتا ہے: JavaScript/TypeScript file جو agent کے events میں hook کرتی ہے اور tools add کر سکتی ہے۔ آپ functions لکھتے ہیں؛ OpenCode انہیں call کرتا ہے۔

	Claude Code plugin	OpenCode plugin
Form	a folder + plugin.json manifest	a .ts/.js module that exports functions
You write	skills, subagents, hooks config, .mcp.json	event handlers, custom tools
Loaded from	a marketplace, or --plugin-dir	.opencode/plugins/ or an npm package

یہ بہتر یا بدتر extend نہیں کرتے؛ یہ مختلف انداز میں extend کرتے ہیں، اور target choose کرنے سے پہلے یہ فرق جاننا ضروری ہے۔ Claude Code Anthropic کا tool ہے، Claude models سے tied ہے، declarative bundle format رکھتا ہے، اور distribute کرنے کے لیے marketplace ecosystem دیتا ہے۔ OpenCode open-source اور model-agnostic ہے: اپنی API key لائیں، free یا local models چلائیں (Gemini، GPT، local)؛ اس کے plugins code ہیں، یعنی زیادہ fine-grained control ملتا ہے مگر آپ کو زیادہ خود لکھنا پڑتا ہے۔ Cost-sensitive learners کے لیے model freedom ہی headline ہے: وہی skill جو آپ لکھتے ہیں OpenCode میں free model پر چل سکتی ہے۔ دونوں interoperate بھی کرتے ہیں؛ skills direct cross over کرتے ہیں، community plugins credentials اور backends bridge کرتے ہیں؛ مگر یہ tools کو ساتھ use کرنا ہے، plugins author کرنا نہیں، اس لیے یہاں out of scope ہے۔

Course کا زیادہ حصہ shared mental model اور Claude Code form ہے، کیونکہ وہ richer bundle ہے؛ Part 5 اسی job کے لیے OpenCode form دکھاتا ہے۔ وہ host pick کریں جو آپ واقعی use کرتے ہیں؛ چار invariants نہیں بدلتے۔

ایک lever free port ہوتا ہے؛ ایک نہیں۔ Skill صرف SKILL.md file ہے، اور اس course کے تینوں coding agents وہ format natively پڑھتے ہیں: Claude Code، OpenCode، اور Codex۔ OpenCode skills کو .opencode/skills/، .claude/skills/، اور .agents/skills/ سے خود discover کرتا ہے، skills کے لیے plugin کی ضرورت نہیں۔ اس لیے ایک skill folder ہر tool کو serve کر سکتا ہے۔ Hooks opposite ہیں: Claude Code hooks JSON config ہیں؛ OpenCode hooks JavaScript module ہیں؛ shared format نہیں، اس لیے hook ہر host کے لیے الگ لکھنا پڑتا ہے۔ یہ split ذہن میں رکھیں؛ cross-tool plugin کا layout اسی سے بنتا ہے (Concept 4)۔

یہ split دو families تک scale ہوتا ہے۔ جو Claude Code plugin آپ build کرتے ہیں وہ Claude Cowork اور claude.ai میں بھی load ہوتا ہے؛ وہ Anthropic کا plugin format share کرتے ہیں۔ جو OpenCode plugin آپ build کرتے ہیں وہ OpenWork میں بھی load ہوتا ہے، OpenCode-powered desktop agent، same OpenCode format۔ Skills دونوں families cross کرتی ہیں، کیونکہ سب SKILL.md پڑھتے ہیں؛ bundles cross نہیں کرتے، Claude bundle OpenCode module نہیں بنتا۔ لہٰذا آپ جس host کو target کرتے ہیں وہ decide کرتا ہے کہ bundle کتنا travel کرے گا؛ مگر plain skill ہر جگہ travel کرتا ہے۔ یہاں ہم دو coding agents پر رہتے ہیں؛ knowledge-work hosts اپنا الگ course ہیں (ceiling دیکھیں)۔

تصور 3: Share کرنے کے لیے bundle، اپنے پاس رکھنے کے لیے configure نہیں

دونوں hosts آپ کو plugin کے بغیر بھی customize کرنے دیتے ہیں: Claude Code آپ کے project میں .claude/ folder پڑھتا ہے؛ OpenCode .opencode/ پڑھتا ہے۔ جب customization personal ہو اور ایک repo میں رہتی ہو تو یہی right tool ہے۔ Plugin تب بناتے ہیں جب customization travel کرنی چاہیے: teammates تک، projects کے across، community تک، versions اور updates کے ساتھ۔

تو "کیا یہ plugin ہونا چاہیے؟" کا test یہ نہیں کہ یہ کیا کرتا ہے؛ test یہ ہے کہ یہ اور کس کو چاہیے۔ ایک developer، ایک project: .claude/ folder۔ Team، بہت سے projects، یا strangers: plugin (invariant 1)۔

ایک consequence early جان لیں: plugin skills اور commands plugin کے نام سے namespaced ہوتے ہیں۔ repo-tools نام کے plugin میں hello skill کو /repo-tools:hello کے طور پر invoke کیا جاتا ہے۔ اس سے دو installed plugins ایک ہی نام پر clash نہیں کرتے۔

✓ Checkpoint: shape اپنی جگہ ہے۔ آپ جانتے ہیں plugin host-loaded unit ہے، دو hosts اسے differently package کرتے ہیں، اور "plugin" کا مطلب ہے "customization made to share." اب چار levers۔

---

حصہ 2: صلاحیت کے levers

چار levers میں سے تین agent کے کر سکنے میں اضافہ کرتے ہیں۔ چوتھا، hooks، اتنا مختلف ہے کہ اسے اپنا Part ملتا ہے۔

تصور 4: Skills: وہ knowledge جسے agent choice سے use کرتا ہے

Skill ایک folder ہے جس میں SKILL.md file ہوتی ہے: description plus instructions۔ Claude description پڑھتا ہے اور جب task match ہو تو skill کو خود pull کر لیتا ہے؛ یہ model-invoked ہے۔ Skill سے آپ agent کو سکھاتے ہیں کہ آپ کی team کوئی کام کیسے کرتی ہے: آپ کا review checklist، commit-message format، release process کے steps۔

---
description: Review a diff for our team's standards. Use when reviewing code or a PR.
---

When reviewing, check in this order:

1. Does it match the existing patterns in the file?
2. Error handling and edge cases.
3. Tests for the new behavior.
4. Security: secrets, input validation, injection.

Description سب سے اہم line ہے: model اسی کو پڑھ کر decide کرتا ہے کہ skill relevant ہے یا نہیں، اس لیے اسے یہ کب use ہو کے بارے میں لکھیں، نہ کہ صرف skill کیا ہے۔ Body صرف skill fire ہونے پر load ہوتی ہے، اس لیے وہ جتنی ضروری ہو اتنی long ہو سکتی ہے۔

چونکہ skill advice ہے جسے model follow کرنے کا choose کرتا ہے، یہ guidance کے لیے right lever ہے؛ اور کسی ایسی چیز کے لیے wrong lever ہے جس کا ہر حال میں ہونا ضروری ہے۔ وہ hook ہے، Concept 8۔

Skill ایک بار لکھیں، ہر tool اسے پڑھتا ہے۔ یہی skill کی superpower ہے: SKILL.md format Claude Code، OpenCode، اور Codex میں shared ہے۔ Skill portable رکھنے کے لیے اس کی body tool-agnostic رکھیں: frontmatter کے name اور description پر lean کریں، اور $ARGUMENTS، allowed-tools، یا disable-model-invocation جیسے tool-specific constructs نہ use کریں۔ پھر یہی file ہر جگہ کام کرتی ہے: Claude Code اسے plugin کے skills/ سے load کرتا ہے؛ OpenCode اسے .opencode/skills/ یا .claude/skills/ سے natively find کرتا ہے؛ Codex .agents/skills/ سے۔ Starter کا skills/loop-engineering/SKILL.md complete، portable example ہے؛ اسے پڑھیں۔

صرف frontmatter کیوں؟

ہر host skill کا name derive کرتا ہے اور description سے decide کرتا ہے کہ اسے کب invoke کرنا ہے۔ ان دو fields کے بعد hosts diverge کرتے ہیں: جو ایک support کرتا ہے، دوسرا ignore کر سکتا ہے یا fail ہو سکتا ہے۔ اس لیے body میں جو tool-specific چیز ڈالیں گے وہ skill کو دوسرے tools پر quietly break کر دے گی۔ Body میں plain instructions، frontmatter میں دو fields، اور skill universal رہتی ہے۔

تصور 5: Subagents: fresh context کے ساتھ delegate کریں

Subagent helper ہے جسے main agent کوئی job دے سکتا ہے، اس کی اپنی clean context window اور اپنی instructions ہوتی ہیں۔ آپ اسے agents/ folder میں markdown file کے طور پر define کرتے ہیں: frontmatter میں name اور description، body میں brief:

---
name: reviewer
description: Reviews a diff against our standards. Use after a change is written.
---

You review code in your own context. Check, in order: matches existing patterns,
error handling, tests, security. Report findings as a short ordered list.
Do not edit files — only review and report.

Delegation دو وجوہات سے matter کرتی ہے: subagent main conversation سے distract نہیں ہوتا، اور اس کا کام main context کو clog نہیں کرتا۔

Subagent تب use کریں جب task self-contained اور verifiable ہو: "یہ diff review کرو"، "یہ function کہاں کہاں call ہوتا ہے تلاش کرو"، "اس file کے tests لکھو"۔ Main agent through-line پر رہتا ہے؛ subagent deep جاتا ہے اور report واپس کرتا ہے۔

جس mistake سے بچنا ہے: ہر چیز کو subagent بنا دینا۔ Delegation کی cost ہے، fresh context کو وہ سب بتایا جانا پڑتا ہے جو اسے چاہیے۔ اسے تب use کریں جب focus اور clean slate واقعی worth it ہوں، ہر چھوٹے step کے لیے نہیں۔

تصور 6: MCP servers: وہ external reach جو plugin ship کر سکتا ہے

چوتھا lever agent کو وہ reach دیتا ہے جو پہلے اس کے پاس نہیں تھی: آپ کی internal API، database، یا service۔ یہ MCP server کی طرف point کر کے ہوتا ہے، اور آپ ایسا server Connector-Native Apps میں پہلے ہی build کر چکے ہیں۔ یہاں آپ دوسرا نہیں بناتے۔ Plugin کا whole job اسے wire کرنا ہے۔

Plugin اپنے root پر .mcp.json file کے ذریعے connect کرتا ہے: server کا name، اس کا URL، اور user کی key header میں۔ Plugin enabled ہو تو host connect کرتا ہے اور server کے tools agent کو نظر آتے ہیں۔

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer ${MY_API_KEY}" }
    }
  }
}

Server design سے remote ہے: logic، data، اور secrets اس infrastructure پر رہتے ہیں جسے آپ control کرتے ہیں، اور plugin صرف pointer ship کرتا ہے۔ یہی reach کو durable، اور (Concept 10) gateable/sellable بناتا ہے۔ Plugin thin client ہے؛ value URL کے پیچھے رہتی ہے۔ اس header کی key simplest gate ہے: server اسے check کرتا ہے، اور cancelled key کام کرنا بند کر دیتی ہے۔ اس سے مضبوط route sign-in ہے، جسے آپ connector course میں دیکھ چکے ہیں؛ اگلا course، AI Identity، agents کو bounded access دینے پر ہے۔ یہاں اس کی ضرورت نہیں۔

Server کہاں سے آتا ہے؟ وہی جو آپ نے پہلے build کیا۔ پچھلے course کا connector open کریں، agent سے اسے run کروائیں، اور جو URL print ہو اسے اوپر والی .mcp.json میں copy کریں۔ Same server، second front door: connector نے chat app serve کی؛ یہ plugin coding agent serve کرتا ہے۔ Connector handy نہیں؟ Starter میں reference/server/ کے اندر tiny runnable server ہے جس کے against wire کر سکتے ہیں۔ دونوں cases میں آپ server کی طرف point کرتے ہیں؛ plugin کے اندر server نہیں لکھتے۔

Local server کیوں نہیں؟

Claude Code local MCP servers بھی support کرتا ہے، یعنی ایسا command جسے host user کی machine پر process کے طور پر run کرے۔ ہم انہیں deliberately skip کرتے ہیں۔ Local server اپنا code plugin کے ساتھ ship کرتا ہے اور کسی دوسرے کے computer پر run ہوتا ہے: skill کی طرح copyable، اور runtime آپ own نہیں کرتے۔ Plugin کے لیے remote server تقریباً ہمیشہ right call ہے: اسے ایک بار build اور host کریں، پھر جتنے چاہیں plugins کو URL سے اس کی طرف point کریں۔

ایک چیز دونوں cases میں carry ہوتی ہے: وہ server آپ کا code run کرتا ہے اور آپ کے secrets hold کرتا ہے۔ ایسا plugin ship کرنا جو اسے wire کرے، اسے آپ کے shipped trust کا part بناتا ہے (invariant 4)، اب users تک extended۔

✓ Checkpoint: capability levers covered۔ Skills knowledge add کرتی ہیں، subagents focused help add کرتے ہیں، MCP servers reach add کرتے ہیں؛ اور تینوں advisory ہیں: model decide کرتا ہے کب use کرنا ہے۔ اگلا lever وہ ہے جو optional نہیں۔

---

حصہ 3: قطعی lever

تصور 7: Hooks: code جو ہر بار چلتا ہے

Hook ایک command ہے جسے host agent lifecycle کے fixed point پر خودکار طور پر run کرتا ہے۔ یہ model کو suggestion نہیں؛ یہ آپ کا code ہے، host کے ذریعے execute ہوتا ہے، ایسے schedule پر جسے model بدل نہیں سکتا۔ یہی single property hooks کو پہلے دکھائی دینے سے زیادہ important بناتی ہے۔

Lifecycle points، یعنی events، تین cadences میں آتے ہیں:

• Session میں ایک بار: SessionStart, SessionEnd۔
• Turn میں ایک بار: UserPromptSubmit (agent کے نیا prompt دیکھنے سے پہلے)، Stop (agent finish کرے تو)۔
• ہر tool call پر: PreToolUse (tool چلنے سے پہلے؛ یہی point اسے block کر سکتا ہے) اور PostToolUse (بعد میں)۔

Command hook ہر بار اسی طرح کام کرتا ہے: host standard input پر event کی JSON description بھیجتا ہے؛ آپ کا script اسے پڑھتا ہے، اپنا کام کرتا ہے، اور exit code سے signal واپس دیتا ہے۔

• Exit 0: allow / done۔
• PreToolUse پر exit 2: tool call block کریں۔ Standard error پر جو بھی print کریں وہ model کو reason کے طور پر دیا جاتا ہے، تاکہ وہ adjust کر سکے۔
• کوئی بھی دوسرا non-zero: non-blocking error؛ log ہو جاتا ہے، action پھر بھی proceed کرتا ہے۔

Guardrails کے لیے exit-2 rule ہی whole game ہے، اور یہی سب سے common چیز ہے جسے لوگ غلط کرتے ہیں: exit 1 block نہیں کرتا۔ Plugin میں hooks hooks/hooks.json میں رہتے ہیں:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/format.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/block-secrets.sh"
          }
        ]
      }
    ]
  }
}

matcher pattern ہے کہ hook کن tools پر fire ہوگا (Write|Edit = file writes؛ Bash = shell commands)۔ Plugin-root path variable آپ کے plugin folder کی طرف point کرتا ہے تاکہ host scripts find کرے؛ اپنے Claude Code version کے خلاف اس کا exact name confirm کریں، کیونکہ SDK اور plugin paths move ہوتے رہتے ہیں۔

تصور 8: Must-always چیز hook ہے، instruction نہیں

Course کا سب سے important idea یہ ہے۔ Instructions کے طور پر آپ جو بھی لکھتے ہیں، skill یا CLAUDE.md line، وہ advisory ہے۔ Model عموماً follow کرتا ہے، مگر بھول سکتا ہے، context ختم ہو سکتا ہے، یا وہ decide کر سکتا ہے کہ conversation آگے بڑھ چکی ہے۔ Most guidance کے لیے یہ ٹھیک ہے۔ مگر جو چیز ہر single time hold کرنی ہو، اس کے لیے advice کافی نہیں۔ Hook کافی ہے۔

Real value کے زیادہ تر cases دو patterns اٹھاتے ہیں:

Format on write: PostToolUse۔ ہر file edit کے بعد formatter چلائیں۔ Model output کو perfectly styled ہونا ضروری نہیں رہتا، کیونکہ formatter ہر بار normalize کر دیتا ہے:

#!/usr/bin/env bash
# hooks/format.sh — runs after every Write/Edit
path=$(jq -r '.tool_input.file_path // empty')   # read the edited file's path from the event
[[ -n "$path" ]] && npx --yes prettier --write "$path" 2>/dev/null
exit 0

جو کبھی نہیں ہونا چاہیے اسے block کریں: PreToolUse, exit 2۔ Tool call inspect کریں؛ اگر یہ line cross کرے، block کریں اور model کو بتائیں کیوں۔ یہ guard secret files اور destructive commands دونوں cover کرتا ہے، اس لیے event سے دو fields پڑھتا ہے:

#!/usr/bin/env bash
# hooks/block-secrets.sh — runs before Read/Edit/Write/Bash
input=$(cat)                                                   # read the event ONCE (see note)
path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')

if [[ "$path" == *.env* || "$path" == */secrets/* ]]; then
  echo "Blocked: $path is a secret file. Do not read or edit it." >&2   # stderr → the model
  exit 2                                                                  # exit 2 → blocked
fi
if [[ "$cmd" == *"rm -rf"* || "$cmd" == *"git push --force"* ]]; then
  echo "Blocked: refusing to run a destructive command ($cmd)." >&2
  exit 2
fi
exit 0

One-line gotcha: event کو ONCE پڑھیں

Host event کو standard input پر بھیجتا ہے، اور standard input stream ہے: جو چیز اسے پہلے پڑھتی ہے وہ اسے drain کر دیتی ہے۔ اگر آپ jq کو direct دو بار call کریں (path=$(jq …) پھر cmd=$(jq …))، پہلی call پورا event consume کر لیتی ہے اور دوسری کو کچھ نہیں ملتا، اس لیے cmd silently empty رہتا ہے اور command guard کبھی fire نہیں کرتا۔ اسے ایک بار input=$(cat) سے capture کریں اور اوپر کی طرح اسی variable کو parse کریں۔ یہی exact bug starter کا test catch کرتا ہے؛ ورنہ ایسا guard ship ہو جاتا جو دیکھنے میں right ہوتا مگر rm -rf پر quietly fail کرتا۔

ایسی skill جو کہتی ہے ".env کبھی نہ پڑھنا" ایک امید ہے۔ یہ hook guarantee ہے۔

اسے run کریں۔ اپنے coding agent کو یہ paste کریں:

add a PostToolUse hook that formats files after Write/Edit, and a PreToolUse hook (matched on Read|Edit|Write|Bash) that blocks reads/edits of .env/secrets/ and blocks rm -rf in Bash, all with exit 2. Read the event once with input=$(cat). Then try to read my .env and run rm -rf and show me both are blocked, and edit a file and show me it got formatted.

(آپ یہاں one hook build کرتے ہیں تاکہ mechanics دیکھیں۔ Worked example میں آپ starter کا already-proven version use کریں گے، اسے rewrite نہیں کریں گے؛ ایک بار خود build کرنا اس لیے ہے کہ آپ اسے trust کر سکیں۔)

Terminal میں خود run کریں (raw commands)۔ Hook کو ویسے test کریں جیسے host اسے call کرتا ہے: fake event pipe کریں اور exit code check کریں:

echo '{"tool_input":{"file_path":"/app/.env"}}' | ./hooks/block-secrets.sh; echo "exit: $?"   # expect: exit 2
echo '{"tool_input":{"command":"rm -rf /"}}'    | ./hooks/block-secrets.sh; echo "exit: $?"   # expect: exit 2
echo '{"tool_input":{"file_path":"/app/main.ts"}}' | ./hooks/block-secrets.sh; echo "exit: $?" # expect: exit 0

Verify کریں۔ تینوں exit codes match ہوں: .env blocked (2)، rm -rf blocked (2)، normal file allowed (0)۔ اگر secret read pass ہو جائے تو hook exit 1 کر رہا ہے، 2 نہیں؛ یہی single most common mistake ہے۔ اگر rm -rf pass ہو جائے مگر .env پکڑا جائے، تو آپ stdin twice پڑھ رہے ہیں (اوپر gotcha دیکھیں)۔ Exit 2، read once؛ ورنہ یہ block نہیں کرتا۔

✓ Checkpoint: deterministic lever کام کرتا ہے۔ آپ ہر edit پر کچھ happen کروا سکتے ہیں، اور ہر tool call پر کچھ stop کر سکتے ہیں۔ یہی فرق ہے plugin کے بیچ جو suggest کرتا ہے اور plugin جو enforce کرتا ہے۔

جب hook misbehave کرے (وہ حصہ جو guides skip کرتے ہیں)

Hooks ہر matching tool call پر run ہوتے ہیں، اس لیے bad hook فوراً محسوس ہوتا ہے۔ چار rules انہیں راستے سے ہٹاتے ہیں:

• انہیں fast رکھیں۔ PreToolUse hook ہر matching call کو gate کرتا ہے، اس لیے slow logic (network round-trip، ہر edit پر full test suite) agent کو stall کر دیتی ہے۔ Well under a second aim کریں؛ heavy work Stop پر کریں، per call نہیں۔
• Fail safe، on purpose۔ Decide کریں کہ جب hook خود error کرے تو کیا ہوگا۔ Formatter نہ چل سکے تو exit 0 ہونا چاہیے، edit کو رہنے دیں؛ اسی لیے format.sh آخر میں exit 0 کرتا ہے اور prettier errors swallow کرتا ہے۔ Guard opposite ہے: اگر یہ decide نہ کر سکے تو block prefer کریں۔ Crashing guard کو کبھی silently exit 0 پر fall through نہ کرنے دیں۔
• Block کرتے وقت ہر بار وجہ بتائیں۔ Bare exit 2 بغیر message کے model کو عمل کے لیے کچھ نہیں دیتا، اور وہ same چیز retry کرے گا۔ stderr line fix instruction ہے؛ اسے specific بنائیں، مثلاً "generated file نہیں، source edit کریں"۔
• Debug اسی طرح کریں جیسے host call کرتا ہے۔ Fake event pipe کریں اور exit code پڑھیں (اوپر raw-command test)۔ اگر hook too often fire ہوتا لگے، matcher check کریں: Write|Edit narrow ہے؛ empty یا broad matcher ہر چیز پر fire کرتا ہے۔

---

حصہ 4: اسے ship کریں

تصور 9: منشور اور ساخت

Claude Code plugin ایک folder ہے جسے manifest describe کرتا ہے: .claude-plugin/plugin.json۔ Claude Code standard component folders کو اس کے بغیر بھی auto-discover کر سکتا ہے، مگر manifest ship کریں؛ یہی آپ کا name، version، اور description carry کرتا ہے۔

{
  "name": "agent-factory",
  "description": "A portable skill, guard hooks, and a reviewer subagent.",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

باقی سب کچھ plugin root پر بیٹھتا ہے، .claude-plugin/ کے اندر نہیں؛ یہی structural mistake لوگ کرتے ہیں:

agent-factory/
├── .claude-plugin/
│   └── plugin.json          # the manifest (this, and only this, goes here)
├── skills/                  # skills as <name>/SKILL.md
├── agents/                  # subagent definitions
├── hooks/
│   └── hooks.json           # event → command wiring
└── .mcp.json                # optional: MCP servers to load

version updates کے لیے matter کرتا ہے: جب آپ اسے bump کرتے ہیں، installers کو new version ملتا ہے؛ اگر آپ اسے omit کرتے ہیں اور git کے ذریعے distribute کرتے ہیں، تو ہر commit new version count ہوتا ہے۔ Share کرنے سے پہلے claude plugin validate چلائیں؛ marketplace review بھی یہی check چلاتا ہے۔

اوپر tree plugin itself ہے، یہ جہاں بھی بیٹھا ہو۔ Starter میں یہ marketplace repo کے اندر plugins/agent-factory/ پر رہتا ہے؛ یہی next Concept ہے۔

تصور 10: Marketplaces: teammate اسے کیسے لیتا ہے

Marketplace صرف git repository ہے جس میں catalog file (marketplace.json) ایک یا زیادہ plugins list کرتی ہے۔ Distribution story یہی ہے: آپ package registry پر publish نہیں کرتے، لوگوں کو repo کی طرف point کرتے ہیں۔

{
  "name": "agent-factory",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "agent-factory",
      "source": "./plugins/agent-factory",
      "description": "A portable skill, guard hooks, and a reviewer."
    }
  ]
}

Teammate پھر Claude Code کے اندر دو commands run کرتا ہے:

/plugin marketplace add your-org/agent-factory   # the git repo with marketplace.json
/plugin install agent-factory@agent-factory       # plugin@marketplace

tip

Develop کرتے وقت marketplace چھوڑ دیں۔ اپنی machine پر دو faster loops ہیں: plugin کو disk سے direct claude --plugin-dir ./plugins/agent-factory کے ساتھ load کریں (یہ .zip بھی accept کرتا ہے)، یا claude plugin init <name> سے scaffold کریں، جو اسے ~/.claude/skills/<name>/ میں ڈالتا ہے اور next session میں <name>@skills-dir کے طور پر auto-load کرتا ہے، بغیر marketplace اور بغیر install کے۔ Marketplace share کرنے کے لیے ہے؛ build اور test کرنے کے لیے اس کی ضرورت نہیں۔

note

دو manifests کو confuse نہ کریں۔ Plugin کے پاس .claude-plugin/plugin.json ہوتا ہے؛ marketplace کے پاس .claude-plugin/marketplace.json۔ Documented layout انہیں الگ رکھتا ہے: marketplace.json repo root پر ہوتا ہے، اور ہر plugin اپنے subfolder (./plugins/<name>/) میں اپنی plugin.json کے ساتھ رہتا ہے۔ Starter exactly یہی use کرتا ہے: plugins/agent-factory/۔ ایک repo marketplace بھی ہو سکتا ہے اور ایک plugin بھی host کر سکتا ہے، مگر plugin کو ./plugins/<name> subfolder میں رکھنا وہ pattern ہے جو official examples use کرتے ہیں؛ اسے prefer کریں۔

Pinning اور sources: updates اصل میں کیسے کام کرتے ہیں۔ Plugin کا source relative path ہو سکتا ہے (اوپر) یا object جو کسی separate repository کی طرف point کرے؛ marketplace many repos سے plugins list کر سکتی ہے، ہر ایک independently pinned:

{
  "name": "code-formatter",
  "source": { "source": "github", "repo": "acme/formatter", "ref": "v2.1.0" }
}

ref branch یا tag pin کرتا ہے، sha exact commit pin کرتا ہے، اور جب دونوں set ہوں تو sha wins۔ یہی، catalog file خود نہیں، decide کرتا ہے کہ teammate کو specific version کیسے ملتا ہے اور آپ updates کیسے ship کرتے ہیں۔ url source GitLab اور دوسرے git hosts cover کرتا ہے؛ local path testing کے لیے handy ہے۔

Publish کرنے سے پہلے دو footguns جان لیں:

• Relative paths صرف تب resolve ہوتے ہیں جب marketplace Git کے ذریعے add ہو (GitHub/GitLab/git URL)۔ اگر کوئی اسے marketplace.json file کے direct URL سے add کرے تو ./plugins/... resolve نہیں ہوگا؛ پھر github یا url source use کریں۔
• Installed plugins cache میں copy ہوتے ہیں، اس لیے plugin اپنے folder کے باہر ../ سے files reach نہیں کر سکتا۔ Plugin کو جو کچھ چاہیے وہ اسی کے اندر رکھیں؛ symlinks copy کے دوران follow ہوتے ہیں جب تک وہ plugin کے اندر اپنی files کی طرف point کریں؛ اسی لیے starter کے دو symlinks plugin کی اپنی files target کرتے ہیں۔

Anthropic اپنے official catalogs بھی چلاتا ہے: claude-plugins-official (curated) اور community claude-community، جس کا repo anthropics/claude-plugins-community add کر کے آپ اس سے @claude-community کے طور پر install کرتے ہیں۔ اس لیے اپنے marketplace کے لیے distinct name pick کریں، ان names کو shadow نہ کریں۔ Naming اور submission rules young ہیں؛ publish سے پہلے current reserved-name policy plugins reference کے خلاف confirm کریں۔

Team یا non-coders تک distribute کرنا۔ Team اور Enterprise plans پر owners Organization settings → Plugins سے marketplace publish کرتے ہیں؛ Knowledge Work marketplace by default add ہوتا ہے، اور جو plugins آپ distribute کرتے ہیں وہ chat اور Claude Cowork میں appear ہوتے ہیں: same bundle knowledge workers تک پہنچتا ہے، صرف builders تک نہیں۔ Ceiling اور Cowork and OpenWork course دیکھیں۔

Share کرنے سے پہلے claude plugin validate چلائیں۔ اوپر schema mid-2026 تک current ہے؛ publish سے پہلے Claude Code plugins reference کے خلاف field names re-verify کریں، کیونکہ یہ surface young اور moving ہے۔

کیا آپ اس کے پیسے لے سکتے ہیں؟ ہاں، مگر files کے نہیں۔ Marketplace catalog ہے، store نہیں: payment layer نہیں، licence check نہیں، subscription primitive format میں نہیں۔ Billing اور access enforcement آپ کو plugin system کے باہر build کرنا ہے۔ اور sharp edge یہ ہے: skill plaintext SKILL.md ہے، DRM نہیں۔ Customer install کرتے ہی source hold کرتا ہے، اس لیے static files کو subscription کے پیچھے gate کرنا ہر customer سے one churn event invite کرتا ہے (pay once، clone، cancel)، اور curriculum جہاں value readable text ہے وہاں آپ first download پر IP دے دیتے ہیں۔

اس لیے real subscription کو support کرنے والا model hosted access ہے: valuable logic اپنے control والے server پر رکھیں اور entry server کی sell کریں، files کی نہیں۔ Installed plugin thin، free client ہے جس کی .mcp.json user key header میں رکھ کر آپ کے hosted MCP server کی طرف point کرتی ہے (Concept 6 کی wiring)؛ key subscription gate ہے، اور revoke کرتے ہی access cut ہو جاتی ہے۔ Free SKILL.md funnel ہے؛ paid moat وہ چیز ہے جو clone copy نہیں کر سکتا: hosted server، retrieval quality، URL کے پیچھے live data۔

یہ اسی pattern کا plugins-only version ہے جو آپ پہلے build کر چکے ہیں۔ Connector-native app copyable-files problem میں نہیں پڑتی، کیونکہ وہ pure hosted server ہے جس کی کچھ file user disk پر نہیں ہوتی۔ Clean shape دونوں together ہے: free plugin client اور funnel ہے، subscription اس کے پیچھے connector-native server پر ride کرتی ہے۔ Same server، second front door۔ مگر یہ دونوں طرف trust کاٹتا ہے: users اب آپ کے server کو اپنی requests کے ساتھ trust کر رہے ہیں، اس لیے trust contract دونوں directions میں چلتا ہے (Concept 11)۔

Bill کرنے سے پہلے دو cautions

• Anthropic کی usage policies نہ توڑیں۔ اگر students آپ کی hosted service کے ذریعے Claude consume کرتے ہیں، تو usage کیسے licensed اور billed ہے یہ legitimate ہونا چاہیے؛ وہی reasoning جو personal Pro/Max subscription کو third-party tools میں route کرنے کو problem بناتی ہے۔ اگر یہ real revenue بنے، تو Anthropic کی commercial terms direct پڑھیں، blog نہیں، اور server جو Claude usage trigger کرتا ہے اس billing path کو confirm کریں۔
• Hosting کا مطلب ہے security surface آپ own کرتے ہیں۔ Paid، gated MCP server attack target ہے، اور paying customers stability expect کرتے ہیں؛ اس لیے کسی بھی write/delete/network action کے لیے tool permissions اور confirmations optional نہیں رہتے۔ یہ invariant 4 ہے، اب money riding on it۔

note

Human-only step۔ Git repo create کرنا اور marketplace میں submit کرنا آپ کا کام ہے؛ coding agent files لکھتا ہے مگر accounts نہیں کھول سکتا یا آپ کے نام سے push نہیں کر سکتا۔ Teammate کا /plugin install بھی human step ہے؛ یہ ان کا trust decision ہے (next Concept)۔

تصور 11: Plugin user کے trust میں چلتا ہے

ایک قدم پیچھے ہو کر دیکھیں کہ installed plugin machine پر کیا کر سکتا ہے: hooks shell commands run کرتے ہیں، اس کا bin/ path میں add ہوتا ہے، اس کے MCP servers run ہوتے ہیں اور باہر reach کرتے ہیں۔ Plugin install کرنا کسی اور کا code run کرنا ہے۔ یہ دونوں طرف cut کرتا ہے، اور دونوں آپ کی job ہیں:

• Author کے طور پر: least privilege۔ صرف وہ hooks جن کی ضرورت ہے، as narrowly as possible matched۔ Job سے باہر network یا filesystem تک reach نہ کریں۔ Trust کو legible بنائیں: ایسا README ship کریں جو plain words میں بتائے plugin installer کی machine پر کیا کرتا ہے:

  README.md — the trust contract
    What this plugin installs   (skills, subagents, hooks, MCP servers)
    What hooks run, and when    (e.g. PostToolUse formatter on Write/Edit)
    What files they inspect     (e.g. reads tool_input.file_path; never opens .env)
    What commands they execute  (e.g. prettier; no network calls)
    What network access they use (ideally: none)

  جو installer اسے دس seconds میں پڑھ لے، وہ آپ پر دس seconds میں trust کر سکتا ہے۔

• Installer کے طور پر: install سے پہلے review کریں، جیسے dependency review کرتے ہیں۔ Trusted marketplaces prefer کریں؛ hooks کیا کرتے ہیں پڑھیں؛ یاد رکھیں PreToolUse hook ہر tool call دیکھتا ہے۔ کسی plugin پر trust کرنے سے پہلے claude plugin details <plugin> چلائیں: یہ کچھ enable کیے بغیر component inventory دکھاتا ہے، یعنی کون سی skills، subagents، hooks، اور MCP servers ساتھ ship ہو رہے ہیں، اور متوقع token cost بھی۔ Hooks وہ line ہیں جسے سب سے پہلے پڑھنا چاہیے۔

یہ invariant 4 ہے، اور یہ paperwork نہیں: formatter hook جو quietly آپ کی files upload کرے، آپ کو تب تک invisible رہے گا جب تک آپ اسے پڑھ نہ لیں۔ وہ plugins ship کریں جنہیں آپ خود install کرنے میں comfortable ہوں۔

✓ Checkpoint: آپ ship کر سکتے ہیں۔ Manifest، structure، marketplace جس سے teammate install کرے، اور trust کے بارے میں clear-eyed view۔ ایک host اور، پھر full build۔

---

حصہ 5: OpenCode plugins

تصور 12: OpenCode plugins: hooks as code

OpenCode انہی ideas کو different form میں لیتا ہے: plugin JavaScript/TypeScript module ہے جو function export کرتا ہے۔ Host آپ کے function کو context object کے ساتھ call کرتا ہے اور آپ hooks return کرتے ہیں: agent کے events کے handlers۔ Separate manifest نہیں؛ file کو .opencode/plugins/ میں drop کریں یا npm package install کریں۔

warning

اس section کو اپنے version کے خلاف verify کریں۔ OpenCode کا plugin API Claude Code کے declarative API سے young اور زیادہ code-level ہے، اس لیے exact event names اور signatures (tool.execute.before, session.idle, tool helper) باقی course سے faster move کرتے ہیں۔ یہ mid-2026 تک current ہیں، مگر اس section سے teach یا ship کرنے سے پہلے installed @opencode-ai/plugin کے خلاف check کریں۔

Claude Code سے key difference: OpenCode میں plugin hooks اور tools کے لیے ہے، skills کے لیے نہیں۔ OpenCode directories (.opencode/skills/, .claude/skills/, .agents/skills/) سے skills natively discover کرتا ہے، اس لیے آپ کی portable SKILL.md files کو یہاں plugin یا shim بالکل نہیں چاہیے۔ Plugin اس part کے لیے ہے جو port نہیں کرتا: hooks۔

// .opencode/plugins/block-secrets.ts
import type { Plugin } from "@opencode-ai/plugin";

export const BlockSecrets: Plugin = async ({
  project,
  client,
  $,
  directory,
}) => {
  return {
    // runs before any tool — throw to block it (the OpenCode equivalent of exit 2)
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath?.includes(".env")) {
        throw new Error("Blocked: .env files are off-limits.");
      }
    },
  };
};

Mental model Claude Code سے straight map ہوتا ہے: tool.execute.before آپ کا PreToolUse ہے، tool.execute.after آپ کا PostToolUse، اور error throw کرنا call block کرتا ہے جیسے exit 2 کرتا ہے۔ OpenCode session اور file events بھی fire کرتا ہے (session.idle, file.edited, اور مزید)، اور plugin tool helper کے ساتھ custom tool add کر سکتا ہے؛ وہی "add reach" idea جو MCP server میں تھا، مگر inline written۔

Context object آپ کو وہ دیتا ہے جو چاہیے: project اور directory (آپ کہاں ہیں)، $ (shell commands run کرنا)، اور client (agent سے talk/log کرنا)۔ Form مختلف ہے؛ چار invariants نہیں۔ Must-always rule یہاں بھی hook ہے: بس script کی جگہ function ہے جو throw کرتا ہے۔

---

حصہ 6: مکمل worked example: agent-factory plugin build کریں

آپ نے Quick Win میں finished agent-factory پہلے ہی run کیا ہے۔ اب آپ اسے blank سے خود build کرتے ہیں: lever by lever، plain English میں agent کو direct کرتے ہوئے۔ جب piece غلط آئے تو اسے reference/، proven build، کے against diff کرتے ہیں۔ آپ stubs fill نہیں کر رہے؛ آپ calls کر رہے ہیں (کون سا lever، hope یا guarantee، کیا travel کرتا ہے) اور ہر ایک prove کر رہے ہیں۔ Rhythm وہی ہے: plan → review → execute → verify۔

Done ہونے پر آپ کا agent-factory چاروں levers دکھاتا ہے: real job کے لیے portable skill، reviewer subagent، guard hook plus format-on-write hook، URL سے wired MCP server، اور teammate کے لیے installable marketplace entry۔ Must-always guard پہلے آتا ہے، کیونکہ یہی part right ہونا لازمی ہے۔

1. Empty plugin scaffold کریں۔ Prompt آپ کے agent کو host کے authoritative layout کی طرف point کرتا ہے۔ اپنے host والا paste کریں:

Using the Plugin Structure skill you installed in setup, scaffold an empty plugin called agent-factory, set up the right way for Claude Code. Show me the layout.

Read the OpenCode plugin docs at https://opencode.ai/docs/plugins, then scaffold an empty OpenCode plugin called agent-factory the way they describe. Show me the layout.

Done when: shell آپ کے host کے layout سے match کرے (uncertain ہو تو agent reference build سے diff کر سکتا ہے)۔ Claude Code پر claude plugin validate empty plugin پر pass ہو۔

2. Guard hook پہلے build کریں، یعنی must-always lever، اور prove کریں کہ یہ block کرتا ہے۔ یہ وہ part ہے جسے right ہونا ہے، اس لیے build کریں، prove کریں، پھر proven one کے against check کریں۔ Paste کریں:

Add two house rules my agent can't skip: auto-format any file right after it's changed, and hard-block anything that reads my secrets or runs a destructive command. Prove both live: have it try a secret read and a destructive command and show me they're stopped, then edit a file and show me it came back formatted.

پھر اپنے work کو trust کرنے کے بجائے proven build سے compare کریں:

Compare my guard against the proven one and tell me if I missed anything that would keep it from actually blocking.

Done when: guard .env اور destructive command live block کرتا ہے، اور reference comparison کوئی important gap نہیں نکالتا۔ (Guard ہر host میں different form لیتا ہے: Claude Code میں shell script، OpenCode میں throwing function؛ reference build دونوں رکھتا ہے۔ Agent وہ form build کرتا ہے جو آپ کا host use کرتا ہے۔)

3. ایسی skill build کریں جو واقعی آپ کے کام آئے۔ Toy نہیں: کوئی real repetitive thing pick کریں، جیسے review checklist، commit-message format، release steps۔ Paste کریں:

Look at the model skill in the reference build first. Then write me a skill for [a real, repetitive job you do]: a clear description of when to use it and the steps to follow. Keep it portable so it works in any agent, not just this one. Show it firing on a real example.

Done when: skill task match ہونے پر خود fire کرتی ہے، اور body portable ہے (agent نے اسے plain instructions رکھا، tool-specific constructs نہیں)۔

4. Reviewer subagent add کریں۔ Paste کریں:

Add a subagent that reviews a change in its own context and only reports, never edits. Run it on a real diff, show me what it finds, then compare it to the model reviewer.

Done when: subagent clean context میں review کرتا ہے اور ordered list report کرتا ہے؛ reference comparison کوئی important missing thing نہیں دکھاتا۔

5. MCP server wire کریں، plugin کو running server کی طرف point کریں۔ آپ server نہیں لکھتے۔ آپ ایک existing server کی طرف point کرتے ہیں: پچھلے course کا connector، یا starter کا runnable sample۔ Paste کریں:

Start the sample MCP server in the starter and wire my plugin to it, then show me the agent can call one of its tools.

(اپنا prefer کرتے ہیں؟ Agent سے last course والا connector run کروائیں اور وہ URL use کریں۔) Agent جو wiring لکھتا ہے وہ جگہ ہے جہاں دو hosts واقعی differ کرتے ہیں؛ shape یہ ہے:

Plugin root پر .mcp.json ship کریں (یہ plugin کے ساتھ travel کرتا ہے):

{
  "mcpServers": {
    "agent-factory": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer ${AGENT_FACTORY_KEY}" }
    }
  }
}

/mcp سے confirm کریں: server connected دکھتا ہے اور tool callable ہے۔

opencode.json میں remote block add کریں:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-factory": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "enabled": true
    }
  }
}

Done when: host server کو connected دکھاتا ہے اور tool callable ہے۔

6. اسے installable بنائیں، اور prove کریں کہ یہ travel کرتا ہے۔ Paste کریں:

Make this installable from a marketplace. Then prove it travels: install it into a different project and show the guard blocks a secret read there too, with no extra setup.

Done when: second project one install سے same hook کے ذریعے protected ہے۔ Plugin کا whole point یہی ہے: rule travel کرتا ہے۔

Notice کریں rhythm: plan → review → execute → verify، must-always guard پہلے build اور prove ہوا کیونکہ یہی part right ہونا لازمی ہے، ہر piece proven reference کے against check ہوا۔ Judgment آپ کا تھا؛ typing agent نے کی۔

---

حصہ 7: Ceiling، اور یہ کہاں grow ہوتا ہے

تصور 13: Ceiling، اور باہر کے bridges

Plugin کی edge محسوس کریں۔ Plugin builder's agent کو بہتر بناتا ہے: sharper، safer، more yours۔ مگر تین چیزیں اب بھی آپ own نہیں کرتے، اور ہر ایک اگلا course name کرتی ہے۔

Loop آپ کا نہیں۔ Hooks host کے loop کے around fire ہوتے ہیں؛ اپنا loop نہیں چلاتے۔ Plugin خود wake up ہو کر many steps across goal pursue نہیں کر سکتا، یا آپ کے سوتے ہوئے job نہیں کر سکتا۔ جب آپ کو ایسا worker چاہیے جو اپنا loop own کرے، آپ agent لکھتے ہیں: path میں آگے Build AI Agents۔

Identity آپ کی نہیں۔ Plugin host چلانے والے person کے طور پر act کرتا ہے۔ اس کی اپنی credential نہیں، اور کسی کے behalf پر bounded، revocable authority سے act کرنے کا way نہیں۔ جب agent کو اپنی identity چاہیے، اور person کو اسے safely authority delegate کرنی ہے، تو وہ AI Identity ہے (Better Auth پر built): sign-in own کریں، پھر agent کو scoped، time-boxed، human-approved access دیں۔

Reach borrowed ہے۔ Plugin remote MCP server wire کر سکتا ہے، مگر server itself، وہ durable user-facing thing جسے stranger chat app میں paste کرتا ہے، اپنی state اور sign-in کے ساتھ، وہ connector-native app ہے جو آپ نے last course میں build کیا۔ Plugins اور connectors same server کو دو hosts سے point کرتے ہیں؛ together they cover both۔

مگر دیکھیں limits کس طرف run کرتے ہیں، اور یہ کہاں grow کرتا ہے۔ جو آپ نے build کیا وہ coding agent سے آگے پہنچتا ہے۔ Anthropic family کے اندر وہی .claude-plugin bundle Claude Cowork اور claude.ai chat میں بھی load ہوتا ہے؛ OpenCode plugin OpenWork میں بھی load ہوتا ہے۔ اور portable piece، یعنی skill، اس سے بھی آگے personal agent جیسے OpenClaw تک travel کرتی ہے۔ اس لیے builder's agent کے لیے لکھی skill unchanged knowledge-worker's agent تک move کر سکتی ہے: lawyer، analyst، ops lead۔ (Shell hook exception ہے۔ اسے real shell چاہیے، اس لیے guard coding side پر رہتا ہے جبکہ skill chat hosts تک cross کرتی ہے۔) جہاں knowledge-work hosts bonus نہیں بلکہ whole story ہوں، وہ اپنا course ہے: Cowork and OpenWork۔

آپ نے step waste نہیں کیا۔ آپ نے agent کو deterministically extend کرنا اور team کو ship کرنا سیکھا؛ یہی skills دوبارہ use ہوں گی جب agent، اور اس کی identity، آپ کی اپنی ہو گی۔

وہی skeleton، دوسرے plugins

agent-factory ایک shape ہے۔ Levers نہیں بدلتے؛ صرف job بدلتا ہے:

• House-style plugin: آپ کے writing یا code conventions والی skill، PostToolUse formatter، reviewer subagent۔ (Team کے لیے جو one consistent voice چاہتی ہے۔)
• Safety plugin: production targets، secrets، اور destructive commands کے لیے PreToolUse guards؛ nothing else۔ (Least privilege، invariant 4۔)
• Service plugin: آپ کی hosted API کے لیے remote MCP server (.mcp.json)، plus ایسی skill جو agent کو اسے use کرنا سکھاتی ہے۔
• Workflow plugin: Stop hook جو agent finish ہونے پر test suite run کرتا ہے، اور release steps کے لیے skill۔

اپنی team کے real pain کے closest one کو pick کریں؛ build worked example جیسی ہی ہے۔

آخری project

اپنا plugin ship کریں۔ اپنی team coding agent کے ساتھ کیسے کام کرتی ہے، اس میں ایک real friction pick کریں۔ ایسا plugin build کریں جو right levers سے اسے fix کرے: کم از کم ایک hook جو must-always rule enforce کرے (exit 2 یا thrown error)، اور کم از کم ایک capability lever (skill، subagent، یا MCP server)۔ اسے marketplace پر publish کریں اور کسی اور سے install کروائیں۔ Confirm کریں hook ان کے project میں، no extra setup، fire ہوتا ہے۔

1Your Work

اپنا plugin describe کریں: یہ کون سی friction fix کرتا ہے، آپ نے کون سے levers کیوں use کیے، must-always rule hook کیسے بنا (اور کیسے block کرتا ہے)، teammate اسے آپ کے marketplace سے کیسے install کرتا ہے، اور proof کہ یہ second project تک travel ہوا۔ اگر آپ کے پاس hooks.json، hook script، یا marketplace.json ہے تو paste کریں۔

2Get Your Score

Discuss with an AI. Question your scores.
Come back when you have your BEST evaluation.