📘 תיעוד 90

עיון במניפסט התוסף

עיון מלא ב-plugin.json: כל שדה עם הסוג וערך ברירת המחדל שלו, צורות הנתיב המקובלות, וסכמות userConfig ומשתני הסביבה.

מניפסט תוסף הוא קובץ plugin.json בתיקייה .claude-plugin/ של התוסף. הוא נושא את המטא נתונים של התוסף ואת ערכי userConfig ש-Claude Code מבקש מהמשתמש. הוא גם מצהיר על כל רכיב שאתה מגדיר בשורה או שומר מחוץ למיקום ברירת המחדל שלו.

העיון הזה מיועד ליוצרי תוספים, ולבעלי marketplace שמכניסים שדות רכיב ברשומת marketplace.

[!NOTE]

המקרים האלה מכוסים בדפים אחרים:

• ללמוד לבנות תוסף: התחל ביצירת תוסף
• מה כל רכיב עושה בזמן ריצה: ראה רכיבי תוסף

התחל בסעיף שמתאים למה שאתה מחפש:

• שדה: טבלת השדות נותנת לכל שדה את הסוג, האם הוא חובה, את ברירת המחדל שלו, ומה הוא מקבל. כללי נתיב מכסים את הקידומת ./ ואת ההכלה לכל נתיב רכיב
• אפשרות userConfig או רשומת channels: הסכמות הגדרת משתמש וערוצים
• ${CLAUDE_PLUGIN_ROOT} או משתנה אחר שתוסף יכול להפנות אליו: משתני סביבה
• לאן הולכים הקבצים של כל רכיב: פריסה סטנדרטית
• הודעה מ-claude plugin validate: דף פתרון הבעיות מפרט כל הודעה עם התיקון שלה ומקשר לסעיפים הרלוונטיים בדף הזה

#קובץ המניפסט

המניפסט אופציונלי. בלעדיו, Claude Code טוען את הרכיבים שהוא מוצא בפריסה הסטנדרטית. שם התוסף מגיע אז מרשומת ה-marketplace, או משם התיקייה כשטוענים את התוסף עם --plugin-dir.

כתוב מניפסט כשאתה רוצה מטא נתונים, רכיב מחוץ לתיקיית ברירת המחדל שלו, userConfig, או הגדרת רכיב בשורה.

שמור את המניפסט ב-.claude-plugin/plugin.json מתחת לשורש התוסף. שים כל קובץ תוסף אחר בשורש התוסף, לא בתוך .claude-plugin/. זה כולל את skills/, commands/ ו-hooks/.

הדוגמה הבאה מגדירה את רוב המפתחות בטבלת השדות. היא עוברת אימות בתיקיית תוסף שמכילה כל נתיב שמוזכר.

{
  "name": "deploy-tools",
  "displayName": "Deploy Tools",
  "version": "1.2.0",
  "description": "Deployment commands, a review agent, and a status monitor",
  "author": {
    "name": "Example Team",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/docs/deploy-tools",
  "repository": "https://github.com/example/deploy-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci"],
  "defaultEnabled": true,
  "dependencies": ["secrets-vault"],
  "metadata": { "catalogId": "cat-123" },
  "skills": ["./extra-skills/"],
  "commands": {
    "status": {
      "source": "./commands/status.md",
      "description": "Show the current deployment status"
    },
    "about": {
      "content": "Explain what the deploy-tools plugin provides.",
      "description": "Describe this plugin"
    }
  },
  "agents": ["./agents/reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  },
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for the deployment API",
      "sensitive": true
    }
  }
}

#שדות לא מזוהים

מפתח ברמה העליונה שלא מזוהה מוסר, ומפתח שלא מזוהה בתוך אפשרות userConfig, רשומת channels, הגדרת lspServers או רשומת monitors נדחה:

• שדות ברמה העליונה: השדה מוסר והתוסף נטען. claude plugin validate מדווח על כל שדה ברמה העליונה שלא מזוהה כאזהרה
• אובייקטים מחמירים: אפשרויות userConfig, רשומות channels, הגדרות lspServers ורשומות monitors מחמירים. מפתח לא ידוע בתוך אחד מהם הוא שגיאה, והתוסף לא נטען

#אימות המניפסט

claude plugin validate הוא הבדיקה הסמכותית למניפסט. הרץ אותו מהמעטפת מול תיקיית התוסף:

claude plugin validate ./my-plugin

הפקודה מדווחת על אחת מהתוצאות האלה:

• Validation passed: המניפסט נטען
• Validation passed with warnings: המניפסט נטען, אבל המאמת מצא משהו לתקן, כמו שדה ברמה העליונה לא ידוע ש-Claude Code מסיר, name שאינו ב-kebab-case, או version, description או author חסרים. העבר את --strict כדי להפוך אזהרות לכשלים ב-CI
• Validation failed: למניפסט יש אי התאמה של סוג, נתיב שחסר או יוצא משורש התוסף, או מפתח לא ידוע בתוך אפשרות userConfig, רשומת channels, הגדרת lspServers או רשומת monitors. Claude Code מדווח על אותה בעיה כשהוא טוען את התוסף

הפקודה גם בודקת כל רשומת שרת MCP שהתוסף מצהיר עליה ב-.mcp.json, בקובץ .json ש-mcpServers מציין, או בשורה ב-plugin.json. בדיקות MCP אלה דורשות Claude Code v2.1.281 או חדש יותר וכוללות:

• שגיאות: רשומה ש-Claude Code היה משמיט כשהוא טוען את התוסף, הפניה ${user_config.KEY} לאפשרות שהמניפסט לא מצהיר עליה, ו-url מרוחק שאינו URL מוחלט תקין
• אזהרות: URL מסוג http:// או ws:// למארח שאינו loopback, וערך header שנראה כמו credential מילולי

#שדות

הטבלה מפרטת את המפתחות ברמה העליונה ב-plugin.json. name הוא המפתח החובה היחיד. כששם שדה הוא קישור, בסעיף המקושר יש את הכללים המלאים שלו.

למפתחות רכיב כמו commands ו-hooks, צורות נתיב של רכיב מציגה כל צורה מקובלת עם דוגמה, וכל נתיב עוקב אחרי כללי הנתיב לקידומת ./, לסיומות ולהכלה.

בעמודת הסוג, נתיב הוא מחרוזת יחסית לשורש התוסף, כמו "./custom/commands".

#name

מזהה התוסף. הוא חייב להיות לא ריק, בלי רווחים, @, :, מפרידי נתיב, תווי בקרה או תווי עיצוב דו כיווני. השתמש ב-kebab-case.

Claude Code נותן לכל רכיב מרחב שמות תחתיו, כך שסוכן reviewer בתוסף deploy-tools מופיע כ-deploy-tools:reviewer.

claude plugin validate גם בודק שהשם לא עובר כאחד מהתוספים של Anthropic עצמה. הבדיקה מתעלמת מרישיות ומתייחסת לכל רצף של מפרידים כאחד:

השגיאה היא Plugin name "<name>" is reserved: it passes as one of Anthropic's own, והאזהרה היא Plugin name "<name>" reads as one of Anthropic's own. claude plugin init ו-claude plugin tag מסרבים לשם שמעורר את השגיאה. Claude Code עדיין מתקין וטוען תוסף שאת שמו הם מסרבים.

#displayName

השם שמוצג בממשק במקום name. הוא יכול להכיל רווחים וכל רישיות, והוא לא משמש למרחב שמות או לחיפוש.

בתוסף שהותקן מ-marketplace, displayName ברשומת ה-marketplace גובר על הערך הזה.

#version

מחרוזת גרסה, שלא נבדקת מול semver. הגדרתה מצמידה את התוסף לגרסה הזו עד שתשנה אותה. ראה גרסאות ועדכונים. תוסף עם מקור command, תוסף מ-marketplace שמתארח ב-claude.ai, ותוסף שנטען במקום מ-marketplace שנוסף מנתיב מקומי לא מוצמדים על ידי השדה הזה.

#metadata

אובייקט חופשי לנתונים שלך, כמו שדות קטלוג או זכאות. Claude Code לא קורא אותו. דורש Claude Code v2.1.222 או חדש יותר.

#שדות רישום במדריך

המדריך של Anthropic קורא את השדות icon, documentationUrl, supportUrl, privacyPolicyUrl ו-termsOfServiceUrl מ-plugin.json עבור הרישום של התוסף שלך כשאתה שולח את התוסף. Claude Code מתעלם מהם בזמן הטעינה. הגדר אותם רק ב-plugin.json. ברשומת marketplace, claude plugin validate מדווח על כל אחד מהם כשדה לא ידוע.

הגדר את icon לנתיב של קובץ תמונה בתוך התוסף, כמו ./logo.png, וכל אחד מארבעת שדות ה-URL לכתובת https://.

[!NOTE]

claude plugin validate לא מדווח על השדות האלה ב-plugin.json כלא ידועים ב-Claude Code v2.1.281 או חדש יותר. גרסאות קודמות מדפיסות אזהרת Unknown field לכל אחד מהם, ולכן הרצה עם --strict נכשלת בגרסאות האלה.

#defaultEnabled

האם התוסף מתחיל מופעל כשהמשתמש לא הגדיר אותו ב-enabledPlugins. ברירת המחדל היא true. תוסף שתוסף מופעל תלוי בו מתחיל מופעל בכל מקרה. אותו שדה ברשומת ה-marketplace דורס את זה.

אחרי שרשומת enabledPlugins של משתמש נכתבת, היא נשמרת לאורך עדכוני תוסף, ולכן שינוי defaultEnabled במהדורה מאוחרת יותר לא משנה את ההגדרה למשתמש קיים.

#dependencies

תוספים שחייבים להיות מופעלים כדי שהתוסף הזה יעבוד. כל רשומה היא "name", "name@marketplace", או { "name": "...", "marketplace": "...", "version": "..." }. שמות חשופים נפתרים מול ה-marketplace של התוסף הזה עצמו. ראה אילוצי תלות.

#settings

הגדרות ש-Claude Code מחיל בזמן שהתוסף מופעל. רק agent ו-subagentStatusLine נכנסים לתוקף. מפתחות אחרים מושמטים בטעינה. settings.json בשורש התוסף גובר על המפתח הזה. ראה הגדרות ברירת מחדל.

#צורות נתיב של רכיבים

כל מפתח רכיב מקבל נתיב יחסי לשורש התוסף. hooks, mcpServers, lspServers ו-experimental.monitors מקבלים גם הגדרה מוטמעת, commands מקבל גם מפת אובייקטים, ו-mcpServers מקבל גם נתיבי חבילת MCP וכתובות URL. הדוגמאות הבאות מציגות כל צורה מקובלת פעם אחת. למה שכל רכיב עושה בזמן ריצה, ראו רכיבי תוסף.

#שדות של נתיב בלבד

agents, skills, outputStyles, workflows ו-experimental.themes מקבלים נתיב אחד או מערך של נתיבים. רשומות agents חייבות להיות קבצי .md, ורשומות skills חייבות להיות ספריות. שלושת האחרים מקבלים ספרייה או קובץ.

{
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"],
  "skills": ["./extra-skills/", "."],
  "outputStyles": "./styles/"
}

#commands

commands מקבל נתיב, מערך של נתיבים, או מפת אובייקטים. נתיב מציין קובץ פקודה שטוח מסוג .md או ספרייה. במפת האובייקטים, כל מפתח הופך לשם הפקודה אחרי קידומת התוסף. לדוגמה, "about" בתוסף deploy-tools רץ כ-/deploy-tools:about.

כל ערך מגדיר בדיוק אחד מבין source או content, ורשומה שמגדירה את שניהם או אף אחד מהם נכשלת באימות. שאר השדות בטבלה הזו הם אופציונליים:

המפה הזו מצהירה על פקודה אחת מקובץ ועל פקודה אחת מתוכן מוטמע:

{
  "commands": {
    "status": { "source": "./commands/status.md", "argumentHint": "[env]" },
    "about": { "content": "Explain what this plugin provides." }
  }
}

#hooks

hooks מקבל נתיב לקובץ .json, אובייקט hooks מוטמע באותה צורה כמו hooks ב-settings.json, או מערך שמערבב את שניהם. לאירועי hook ולשדות מטפל, ראו את הפניית ה-hooks.

קובץ hooks עוטף את מפת האירועים במפתח "hooks" ברמה העליונה, הצורה ש-hooks/hooks.json משתמש בה. קובץ שמכיל רק את מפת האירועים, בלי העטיפה הזו, נכשל בטעינה. אובייקט מוטמע הוא מפת האירועים עצמה, בלי עטיפה.

Claude Code ממזג את מה שמצהירים עם hooks/hooks.json כשהקובץ הזה קיים. המערך הזה טוען קובץ hooks אחד ומצהיר על hook מוטמע אחד מסוג PostToolUse:

{
  "hooks": [
    "./config/extra-hooks.json",
    {
      "PostToolUse": [
        {
          "matcher": "Write|Edit",
          "hooks": [
            { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.sh" }
          ]
        }
      ]
    }
  ]
}

הקובץ שהמערך מציין נושא את עטיפת "hooks" סביב מפת האירועים שלו:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/check-command.sh" }
        ]
      }
    ]
  }
}

#mcpServers

mcpServers מקבל נתיב לקובץ .json, נתיב או URL של חבילת MCP, מפה מוטמעת, או מערך שמערבב אותם. לשדות הגדרת שרת, ראו שרתי MCP שמסופקים על ידי תוסף.

Claude Code טוען את .mcp.json בשורש התוסף תחילה, ואחר כך כל צורה מוצהרת לפי הסדר. שם שרת שמוצהר מאוחר יותר מחליף שם קודם.

ערך mcpServers מקבל אחת מהצורות האלה:

נתיב או URL של חבילה חייב להסתיים ב-.mcpb או .dxt. כל סיומת אחרת נכשלת באימות.

#lspServers

lspServers מקבל נתיב לקובץ .json, מפה מוטמעת משם שרת להגדרה, או מערך של אחד מהם.

Claude Code טוען את .lsp.json בשורש התוסף תחילה, ואחר כך כל הגדרה מוצהרת לפי הסדר. שם שרת שמוצהר מאוחר יותר מחליף שם קודם.

כל הגדרת שרת היא אובייקט קשיח עם השדות האלה. מפתח לא מוכר נכשל באימות.

ההגדרה המוטמעת הזו מריצה את gopls עבור קבצי .go:

{
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": { ".go": "go" }
    }
  }
}

לשרתי השפה ש-Anthropic מפרסמת כתוספים ולאופן שבו השרתים מתנהגים בזמן ריצה, ראו אינטליגנציית קוד.

#monitors

experimental.monitors מקבל נתיב לקובץ .json או את המערך המוטמע. כשמשמיטים את המפתח, Claude Code טוען את monitors/monitors.json אם הוא קיים.

כל רשומה היא אובייקט קשיח עם השדות האלה.

המערך המוטמע הזה מצהיר על מוניטור אחד שמתחיל בפעם הראשונה שמיומנות deploy רצה:

{
  "experimental": {
    "monitors": [
      {
        "name": "deploy-status",
        "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
        "description": "Deployment status changes",
        "when": "on-skill-invoke:deploy"
      }
    ]
  }
}

command של מוניטור לא יכול להפנות אל ${user_config.*}. ראו שדות שרצים דרך מעטפת.

#כללי נתיב

כל נתיב רכיב במניפסט הוא יחסי לשורש התוסף וחייב להתחיל ב-./. נתיב כגון commands/foo.md נכשל באימות. skills ו-mcpServers מקבלים כל אחד צורה אחת מחוץ לכלל הזה:

• skills: מקבל גם ".". גם "." וגם "./" מציינים את שורש התוסף. לפני v2.1.221, "." נכשל באימות המניפסט, ולכן השתמש ב-"./" כשהתוסף חייב להיטען בגרסאות מוקדמות יותר
• mcpServers: מקבל גם URL של חבילה מסוג https://

experimental.evals אינו נתיב רכיב, ולכן הכללים בסעיף הזה לא מכסים אותו, ו-claude plugin eval בודק את הערך כשהוא רץ. הוא מציין ספרייה מתחת לשורש התוסף, כגון "quality/evals", עם קידומת ./ או בלעדיה. עם מערך, רק הרשומה הראשונה בשימוש. למה שהערך מקבל ולמה שקורה עם ערך בלתי שמיש, ראו שימוש בספריית eval אחרת.

#הכלה וקיום

כל נתיב רכיב חייב להיפתר בתוך שורש התוסף וחייב להתקיים. claude plugin validate בודק את הנתיבים תחת כל מפתח רכיב:

• הכלה: נתיב שנפתר מחוץ לשורש התוסף לא נטען, ולשונית Errors של /plugin מציגה <component> path escapes plugin directory: <path>. נתיב שמכיל .. הוא המקרה הרגיל, ו-claude plugin validate מדווח על השגיאה Path contains ".." which could be a path traversal attempt
• קיום: נתיב שלא קיים לא נטען, ולשונית Errors של /plugin מציגה <component> path not found: <path>. claude plugin validate מדווח על השגיאה Path not found

עבור נתיבי outputStyles, lspServers, monitors ו-themes, הבדיקה של claude plugin validate דורשת Claude Code v2.1.283 או חדש יותר.

#איך כל מפתח משתלב עם מיקום ברירת המחדל שלו

כל מפתח רכיב מחליף את מיקום ברירת המחדל שלו, מוסיף אליו, או מתמזג איתו:

• מחליף את ברירת המחדל: commands, agents, outputStyles, workflows, experimental.themes, experimental.monitors. כשמגדירים את commands, ספריית ברירת המחדל commands/ לא נסרקת. כדי לשמור את ברירת המחדל ולהוסיף עוד, פרט אותה במפורש: "commands": ["./commands/", "./extras/"]
• מוסיף לברירת המחדל: skills. ספריית skills/ עדיין נסרקת, והספריות שברשימה נטענות לצידה
• מתמזג: hooks, mcpServers, lspServers. קובץ ברירת המחדל נטען תחילה, ומה שהמניפסט מצהיר מתמזג לתוכו, כפי שמתואר תחת צורות נתיב של רכיבים

אם לתוסף יש תיקיית ברירת מחדל כגון commands/ והוא גם מגדיר את מפתח המניפסט שמחליף אותה, Claude Code טוען את נתיבי המניפסט, והתיקייה לא נטענת. claude plugin list וממשק /plugin מציגים אז את האזהרה Default <folder>/ folder is ignored because the manifest sets "<key>".

כדי להימנע מהאזהרה, הגדר את המפתח לנתיב בתוך התיקייה הזו: "commands": ["./commands/deploy.md"] מציין קובץ בתיקיית ברירת המחדל, בלי אזהרה.

#הגדרת משתמש

userConfig מצהיר על ערכים ש-Claude Code מבקש מהמשתמש כשהתוסף מופעל, כדי שמשתמשים לא יערכו את settings.json בעצמם.

מפתחות הם מזהים שמורכבים מאותיות, ספרות וקווים תחתונים, ולא יכולים להתחיל בספרה.

כל ערך הוא אובייקט קשיח עם השדות האלה. מפתח לא מוכר נכשל באימות.

כל אפשרות של כל תוסף מופעל מופיעה גם כשורה בלוח /config, חוץ מאפשרויות sensitive ורשימות multiple. שורות /config דורשות Claude Code v2.1.269 או חדש יותר.

userConfig הזה מצהיר על נקודת קצה ועל אסימון מוסווה:

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Your team's API endpoint"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "API authentication token",
      "sensitive": true
    }
  }
}

#הגבלת שדה לאפשרויות קבועות

הגדר options על שדה userConfig כדי שמשתמשים יבחרו את הערך שלו מרשימה קבועה.

כדי להגביל שדה tone לשלוש אפשרויות, פרט אותן ב-options והגדר את default לאחת מהן:

{
  "userConfig": {
    "tone": {
      "type": "string",
      "title": "Tone",
      "description": "Voice for generated replies",
      "options": ["neutral", "warm", "formal"],
      "default": "neutral"
    }
  }
}

אם מצהירים על options בכל שדה, משתמשים בגרסאות Claude Code שלפני v2.1.271 לא יכולים לטעון את התוסף.

options חל על שדה string שאינו multiple או sensitive. הגדר את default לאחד מהערכים שברשימה, או הגדר required: true כדי שהמשתמש חייב לבחור אחד. כל אפשרות היא תווית פשוטה של 1 עד 64 תווים, ו-claude plugin validate, שמריצים במעטפת, מדווח על כל דבר אחר שהוא דוחה. תוסף ש-options שלו שובר את הכללים האלה נכשל בטעינה.

#איפה הערכים נשמרים

ערכים שאינם רגישים נשמרים תחת pluginConfigs ב-settings.json של המשתמש. ערכים רגישים נשמרים במאגר האישורים המאובטח של הפלטפורמה. עמוד ההגדרות מפרט מאילו קבצי הגדרות נקרא pluginConfigs.

#הפניה לערך שמור

הפנה לערך שמור במקום שבו התוסף צריך אותו, באחת משתי צורות:

• ${user_config.KEY}: מוחלף בהגדרת שרת MCP, בהגדרת שרת LSP, ב-args של hook ב-צורת exec, ובתוכן של מיומנות וסוכן. בתוכן של מיומנות וסוכן, רק ערכים שאינם רגישים מוחלפים, וערך רגיש שם הופך למציין מקום
• CLAUDE_PLUGIN_OPTION_<KEY>: מיוצא לתהליכי hook עבור כל אפשרות, כש-<KEY> באותיות גדולות. hook בצורת מעטפת קורא את $CLAUDE_PLUGIN_OPTION_API_TOKEN עבור api_token

#שדות שרצים דרך מעטפת

פקודות hook בצורת מעטפת, פקודות מוניטור, ו-headersHelper של MCP דוחים את ${user_config.*}. רכיב שמפנה אליו באחד מהשדות האלה נכשל עם שגיאה ולא רץ, כי ערך השדה מועבר למעטפת שהייתה מנתחת מחדש את הערך המוחלף.

הטבלה מראה איך הערך יכול להגיע לכל אחד מהשדות האלה.

#ערוצים

channels מצהיר על ערוצי ההודעות שתוסף מספק, כגון גשר לאפליקציית צ'אט. כשמצהירים על אחד, Claude Code יכול לבקש את הגדרת הערוץ כשהתוסף מופעל. לאופן שבו השרת מזריק הודעות, ראו את הפניית הערוצים.

כל רשומה היא אובייקט קשיח שקשור לאחד משרתי ה-MCP של התוסף, עם השדות האלה:

המניפסט הזה קושר ערוץ לשרת ה-MCP telegram של התוסף ומבקש אסימון בוט שמוחלף ב-env של השרת:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

#משתני סביבה

קלוד קוד מספק שלושה משתני נתיב לרכיבי תוסף. הפנו אליהם כ-${NAME} בשדות שמפורטים תחת איפה כל משתנה נפתר, וקראו אותם כמשתני סביבה בתהליכים שמקבלים אותם.

${CLAUDE_PLUGIN_ROOT} משתנה כשהתוסף מתעדכן, ולכן אל תכתבו שם מצב. למידע על המקום שאליו השורש עובר ומתי הספרייה הישנה מנוקה, ראו את דף הטעינה.

כברירת מחדל, קלוד קוד מוחק את ספריית ${CLAUDE_PLUGIN_DATA} כשמסירים את התוסף מהמקום האחרון שבו הוא מותקן. לגבי --keep-data והמקרים האחרים שבהם היא נשארת, ראו הסרת תוסף.

#איפה כל משתנה נפתר

בכל רכיב תוסף, הפניות ${...} נפתרות בתוך השורה בשדות מסוימים, וחלק מהרכיבים גם מקבלים את המשתנים בסביבת התהליך שלהם:

המשתנים אינם נוכחים בסביבה של פקודות שקלוד מריץ דרך כלי Bash, בסשן הראשי או בסוכן משנה. בתוכן של skill, command ו-agent, כתבו את ההפניה ${...} בגוף ה-Markdown, וקלוד קוד מחליף את הנתיב בתוך השורה כשהוא טוען את התוכן.

#ציטוט ומפרידי נתיב

שמרו על כל נתיב מוחלף כארגומנט יחיד:

• פקודות hook: השתמשו ב-צורת exec עם args, כך שכל נתיב הוא ארגומנט אחד בלי ציטוט
• hooks בצורת shell ופקודות monitor: עטפו את המשתנה במירכאות כפולות, כדי שנתיב עם רווחים יישאר מילה אחת

אם משאירים אחד מהמשתנים האלה מחוץ למירכאות בפקודה בצורת shell בקובץ hooks, claude plugin validate מזהיר על כך, אלא אם ה-hook מגדיר את shell ל-"powershell".

ה-hook הזה בצורת shell מריץ סקריפט שמגיע עם התוסף:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

ב-Windows, רוב הנתיבים המוחלפים משתמשים בלוכסנים קדמיים, כמו ב-C:/Users/you/.... הם שומרים על הלוכסנים האחוריים המקוריים שלהם ב-hook בצורת exec וב-hook שרץ דרך PowerShell, שהיא מעטפת ברירת המחדל ב-Windows כש-Git Bash אינו מותקן.

#פריסה סטנדרטית

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

תוסף שמשתמש בכל מיקום ברירת מחדל, ובנוסף בתיקיית scripts/ שה-hooks שלו קוראים לה, פרוס כך:

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── commands/
│   └── status.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── monitors/
│   └── monitors.json
├── output-styles/
│   └── terse.md
├── themes/
│   └── dracula.json
├── workflows/
│   └── release-audit.js
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

כדי לעבור על הפריסה הזו ולקרוא מה כל קובץ עושה, פתחו את סייר התוספים.

CLAUDE.md בשורש התוסף אינו נטען כהקשר, ו-claude plugin validate מזהיר כשהוא מוצא אחד. כדי לכלול הוראות שנטענות להקשר של קלוד, שימו אותן ב-skill.

#רשומות marketplace והמניפסט

רשומת marketplace מקבלת שדות משלה, כולל strict, וכל שדה בדף הזה חוץ משדות רשימת הספריות.

שדה strict קובע אם הרשומה רשאית להוסיף רכיבים לתוסף שיש לו plugin.json משלו. ברירת המחדל היא true.

#איך שדות הרשומה משתלבים עם plugin.json

הרשומה משמשת כמניפסט, מוסיפה אליו רכיבים, או מתנגשת איתו:

• אין plugin.json: הרשומה היא המניפסט, בלי קשר ל-strict. hooks של הרשומה נטען רק בצורת אובייקט בתוך השורה. עבור נתיב קובץ או מערך שם, לשונית Errors של /plugin מציגה שגיאה not yet supported in a marketplace entry
• plugin.json קיים, strict לא מוגדר או true: קלוד קוד טוען את המניפסט ומצרף אליו את commands, agents, skills, outputStyles ו-themes של הרשומה. עבור hooks, ה-matchers של הרשומה לאירוע מחליפים את ה-matchers של המניפסט לאותו אירוע, ואירועים שרק המניפסט מצהיר עליהם שומרים על שלהם
• plugin.json קיים, strict: false: רשומה שמצהירה על אחד מ-commands, agents, skills, hooks, outputStyles או themes היא התנגשות, והתוסף נכשל בטעינה עם Plugin <name> has conflicting manifests

כשרשומת marketplace ש-source שלה הוא שורש ה-marketplace מפרטת תת-ספריות skills מסוימות, רק תת-הספריות האלה נטענות, וספריית skills/ שברירת המחדל של התוסף אינה נסרקת. מפתח skills במניפסט במקום זאת מוסיף לברירת המחדל.

#קדימות מטא-נתונים

לחלק משדות המטא-נתונים יש קדימות קבועה בלי קשר ל-strict:

• defaultEnabled ושדות תצוגה: defaultEnabled של הרשומה ושדות התצוגה שלה, כגון displayName, גוברים על אלה של המניפסט
• version: version של המניפסט גובר על זה של הרשומה
• name: כשהרשומה מפרטת את התוסף תחת name שונה מזה של המניפסט, enabledPlugins משתמש בשם הרשומה, והרכיבים מקבלים מרחב שמות תחת שם המניפסט

לטבלת הקדימות המלאה, ראו מצב strict.

#הצעדים הבאים

• הוספת רכיבים לתוסף: מה כל רכיב עושה בזמן ריצה, עם דוגמה שעוברת אימות
• הפניית marketplace: שדות הרשומה ש-marketplace יכול להגדיר לתוסף שלכם
• הפניית פקודות תוסף: דגלים ופלט של claude plugin validate
• פתרון בעיות בתוספים: כל הודעת אימות עם התיקון שלה