בתוך 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, נתיב לקובץ הרצה), רשימת ארגומנטים, ומפת 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 ולא במאגר הקוד. פיצול של המאגר בטוח מעצם המבנה, ביטול הרשאה מתבצע בצד השרת ולא כעריכת קונפיגורציה שצריכה להגיע לכל מכונה, ואיש אינו מתבקש להדביק מפתח ארוך טווח לתוך קובץ שנמצא במרחק קומיט רשלני אחד מדיף פומבי.

מה כדאי להעתיק לתוסף שלכם

הנחיות מעשיות, פחות או יותר לפי סדר הבנייה:

• התחילו מ-.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 ואת הנוהל בפקודה. כפילות בין השניים היא סימן אזהרה.
• בדקו עם /plugin marketplace add מול נתיב מקומי או מול הפיצול שלכם לפני שאתם מפנים מישהו ל-main.

פינות מחוספסות

שלוש כאלה, בכנות, ואף אחת מהן אינה קטלנית. הכול באנגלית, והפורמט לא מציע וו לתלות עליו תיקון: אין מפתח locale ב-frontmatter, ולכן לוקליזציה פירושה קבצי פקודה כפולים או השלמה עם חוסר ההתאמה.

לסיפור שאין כאן מפתחות API יש כוכבית. הקובץ SKILL.md מודה שכלי יצירת המדיה יושבים מחוץ לחיבור ה-OAuth וזקוקים לאסימון MCP סטטי עם הרשאות מדיה, שנוצר ב-Studio של הפלטפורמה ונשלח בכותרת bearer. התוסף מטפל בזה יפה ומורה למודל להסביר את החוסר במקום להתנגח בקיר בניסיונות חוזרים, אבל זהו נתיב אימות שני שהוברג על תכנון שכל נקודת המכירה שלו היא נתיב אחד.

וזו גרסה 0.1.0 בלי changelog, בלי בדיקות ובלי CI. עבור markdown זה מוצדק, אם כי בדיקת סכמת JSON ב-hook של pre-commit הייתה תופסת את מחלקת השגיאות היחידה שבאמת שוברת התקנות, מניפסט פגום. ההגשה לספרייה נמצאת בבדיקה נכון לכתיבת שורות אלה, ולכן בינתיים מתקינים לפי הפניה למאגר.

קראו קודם את שלושת קבצי הפקודות, אחר כך את SKILL.md, ולבסוף את שני קבצי ה-JSON. בסדר הזה הפורמט מסביר את עצמו: ה-markdown מחליט מה צריך לקרות ובאיזה סדר, שרת ה-MCP מחליט מה באמת רץ, והמניפסט הוא התפר הדק ביניהם.