درون 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/ یک frontmatter به شکل YAML به‌علاوه نثر است. فایل 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 میزبانی‌شده دارید، به‌جای دستور محلی مقدار "type": "http" را با یک url اعلام کنید. این کار محیط اجرای کاربر را از سطح پشتیبانی شما حذف می‌کند.
• تا وقتی یک افزونه دارید، marketplace.json را در همان مخزن با "source": "./" منتشر کنید و نامی متفاوت از نام افزونه به آن بدهید.
• به هر دستور یک description و یک argument-hint در frontmatter بدهید، نوشته‌شده در پاسخ به این دو پرسش که این چه می‌کند و بعد از آن چه باید تایپ کنم.
• به‌جای اختراع نحو موقعیتی از $ARGUMENTS استفاده کنید. پارسری در کار نیست، فقط جایگزینی.
• بدنه دستورها را به‌شکل درخت تصمیم و با نام صریح ابزارها بنویسید. جمله "اگر فایل پیکربندی وجود دارد app_id را بخوان، وگرنه list_apps را صدا بزن" بهتر از یک پاراگراف نیت دوام می‌آورد.
• معنای شکست‌ها را مکتوب کنید: کدام خطاها پایانی‌اند، کدام قابل تلاش مجددند، و به‌جای تلاش دوباره چه باید گفت.
• ابزارهای مخرب را در متن نام ببرید و تا وقتی درخواست نشده‌اند ممنوعشان کنید.
• مدل دامنه را در SKILL.md و رویه را در دستور نگه دارید. تکرار میان این دو نشانه بدی است.
• پیش از آنکه کسی را به main ارجاع دهید، با /plugin marketplace add روی یک مسیر محلی یا روی فورک خودتان آزمایش کنید.

لبه‌های ناهموار

سه مورد صادقانه، هیچ‌کدام کشنده نیستند. همه چیز انگلیسی است و قالب هیچ قلابی برای اصلاحش پیشنهاد نمی‌کند: کلید locale در frontmatter وجود ندارد، پس بومی‌سازی یعنی فایل‌های دستور تکراری یا پذیرفتن این ناهماهنگی.

روایت «بدون کلید API» یک ستاره کنارش دارد. فایل SKILL.md اعتراف می‌کند ابزارهای تولید رسانه بیرون از اتصال OAuth قرار دارند و به یک توکن ثابت MCP با دسترسی رسانه نیاز دارند که در Studio پلتفرم ساخته و در هدر bearer فرستاده می‌شود. افزونه این را خوب مدیریت می‌کند و به مدل می‌گوید نبودِ آن را توضیح دهد به‌جای آنکه پشت سر هم به دیوار بکوبد، اما این مسیر احراز هویت دوم روی طراحی‌ای پیچ شده که نقطه فروشش داشتن یک مسیر است.

و این نسخه 0.1.0 است، بدون changelog و آزمون و CI. برای markdown این قابل دفاع است، هرچند یک بررسی اسکیمای JSON در hook پیش از کامیت، همان تنها دسته خطایی را می‌گرفت که واقعاً نصب را می‌شکند، یعنی مانیفست خراب. ثبت در دایرکتوری هنگام نوشتن این متن در حال بررسی است، پس فعلاً نصب با ارجاع به مخزن انجام می‌شود.

اول سه فایل دستور را بخوانید، بعد SKILL.md، و بعد دو فایل JSON. به این ترتیب، قالب خودش را توضیح می‌دهد: markdown تصمیم می‌گیرد چه باید رخ دهد و با چه ترتیبی، سرور MCP تصمیم می‌گیرد واقعاً چه چیزی اجرا شود، و مانیفست همان درز باریک میان این دو است.