finestructure-ai/claude-plugin के भीतर: सात फ़ाइलों में बना एक Claude Code प्लगइन

पूरा रिपॉज़िटरी सात फ़ाइलों का है

क्लोन कीजिए और पूरा फ़ाइल ट्री एक ही स्क्रीन में आ जाता है:

.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, किसी बाइनरी का पथ), आर्ग्युमेंट की सूची, और API कुंजी रखने वाला env मैप। इसकी जगह streamable HTTP एंडपॉइंट घोषित करना सर्वर को उपयोगकर्ता की मशीन से बाहर ले जाता है, और यही वजह है कि 105 टूल (यह संख्या skill फ़ाइल देती है) 686 बाइट के मैनिफ़ेस्ट के पीछे बैठ जाते हैं। उपयोगकर्ता के Node या Python संस्करण से इंस्टॉल टूट नहीं सकता, और सर्वर की ओर के बदलाव बिना नए प्लगइन रिलीज़ के लागू हो जाते हैं। इसका मोल पुनरुत्पादनीयता है: आप क्लाइंट की ओर से टूल सतह को स्थिर नहीं कर सकते।

marketplace.json रिपॉज़िटरी को उसका अपना वितरण चैनल बना देता है

Claude Code प्लगइन marketplace से इंस्टॉल करता है, किसी पैकेज रजिस्ट्री से नहीं, और marketplace एक JSON फ़ाइल है जो प्लगइन और उनका स्रोत पथ सूचीबद्ध करती है। .claude-plugin में मौजूद दूसरी फ़ाइल यही करती है, और उसकी इकलौती प्लगइन प्रविष्टि में "source": "./" लिखा है। रिपॉज़िटरी एक साथ प्लगइन भी है और उसे परोसने वाला marketplace भी, इसलिए प्रकाशन का अर्थ एक सार्वजनिक git push है:

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

दूसरी पंक्ति के दोनों एक जैसे टोकन दरअसल marketplace के नाम पर प्लगइन का नाम हैं, और वे इसलिए टकराते हैं क्योंकि दोनों का नाम finestructure है। अगर आप यह ढाँचा उतारें, तो दोनों के नाम अलग रखिए। इंस्टॉल के निर्देश साफ़ हो जाते हैं और आगे दूसरा प्लगइन जोड़ने की गुंजाइश भी बनी रहती है।

कमांड frontmatter वाले प्रॉम्प्ट टेम्पलेट हैं

commands/ की हर फ़ाइल YAML frontmatter और उसके बाद गद्य है। deploy.md एक description और एक argument-hint घोषित करती है, यानी वे दो पंक्तियाँ जो उपयोगकर्ता चयनकर्ता में देखता है, और फिर एक क्रमांकित निर्णय वृक्ष रखती है: प्रोजेक्ट की जड़ में app_id वाली .finestructure.json देखिए, न मिले तो 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" घोषित कीजिए। इससे उपयोगकर्ता का रनटाइम आपके सपोर्ट दायरे से हट जाता है।
• जब तक एक ही प्लगइन है, marketplace.json उसी रिपॉज़िटरी में "source": "./" के साथ भेजिए, और उसका नाम प्लगइन से अलग रखिए।
• हर कमांड को 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 सर्वर तय करता है कि असल में क्या चलता है, और मैनिफ़ेस्ट दोनों के बीच की पतली सिलाई है।