📘 תיעוד 84

יצירה והפצה של marketplace לתוספים

בנה ואחסן שווקי תוספים כדי להפיץ הרחבות Claude Code בין צוותים וקהילות.

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

מעוניין להתקין תוספים מתוך marketplace קיים? ראה גילוי והתקנה של תוספים מוכנים מראש.

#סקירה כללית

יצירה והפצה של marketplace כוללות:

1. יצירת תוספים: בנה תוסף אחד או יותר עם skills, agents, hooks, שרתי MCP או שרתי LSP. מדריך זה מניח שכבר יש לך תוספים להפצה, ראה יצירת תוספים לפרטים על אופן היצירה שלהם.
2. יצירת קובץ ה-marketplace: הגדר קובץ marketplace.json שמפרט את התוספים שלך והיכן למצוא אותם. ראה יצירת קובץ ה-marketplace.
3. אחסון ה-marketplace: דחף ל-GitHub, ל-GitLab או למארח git אחר. ראה אחסון והפצה של שווקים.
4. שיתוף עם משתמשים: משתמשים מוסיפים את ה-marketplace שלך באמצעות /plugin marketplace add ומתקינים תוספים בודדים. ראה גילוי והתקנה של תוספים.

ברגע שה-marketplace שלך פעיל, תוכל לעדכן אותו על ידי דחיפת שינויים למאגר שלך. משתמשים מרעננים את העותק המקומי שלהם באמצעות /plugin marketplace update.

#מדריך מעשי: יצירת marketplace מקומי

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

1. יצירת מבנה התיקיות:

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

2. יצירת ה-skill: צור קובץ SKILL.md שמגדיר מה ה-skill בשם quality-review עושה.

---
description: Review code for bugs, security, and performance
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

3. יצירת מניפסט התוסף: צור קובץ plugin.json שמתאר את התוסף. המניפסט ממוקם בתיקיית .claude-plugin/.

{
  "name": "quality-review-plugin",
  "description": "Adds a quality-review skill for quick code reviews",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

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

4. יצירת קובץ ה-marketplace: צור את קטלוג ה-marketplace שמפרט את התוסף שלך.

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews"
    }
  ]
}

5. הוספה והתקנה: מהתיקייה שמכילה את my-marketplace, הפעל את Claude Code והרץ את הפקודות הבאות. פקודת ההתקנה פותחת תצוגת פרטי תוסף שבה אתה בוחר היקף התקנה (installation scope) כדי לאשר את ההתקנה. בדוק את סיכום ההתקנה: אם מופיע Run /reload-plugins to activate., ראה החלת שינויים בתוספים ללא הפעלה מחדש.

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

6. בדיקה: בחר קוד כלשהו בעורך שלך והרץ את ה-skill החדש שלך. skills של תוספים מקבלים מרחב שמות הכולל את שם התוסף.

/quality-review-plugin:quality-review

כדי ללמוד עוד על מה שתוספים יכולים לעשות, כולל hooks, agents, שרתי MCP ושרתי LSP, ראה תוספים.

כיצד תוספים מותקנים: כאשר משתמשים מתקינים תוסף, Claude Code מעתיק את תיקיית התוסף למיקום מטמון, אלא אם התוסף נטען במקום. מקור מסוג command במצב קישור (link mode) נטען במקום, וכך גם מקור נתיב יחסי ב-marketplace שנוסף מתיקייה מקומית. תוספים מועתקים אינם יכולים להתייחס לקבצים מחוץ לתיקייה שלהם באמצעות נתיבים כמו ../shared-utils, מכיוון שקבצים אלה לא יועתקו.

אם עליך לשתף קבצים בין תוספים, השתמש בקישורים סימבוליים (symlinks). ראה מטמון תוספים ופתרון קבצים לפרטים.

#יצירת קובץ ה-marketplace

צור את הקובץ .claude-plugin/marketplace.json בשורש המאגר שלך. קובץ זה מגדיר את שם ה-marketplace שלך, פרטי הבעלים, ורשימת תוספים יחד עם המקורות שלהם.

כל רשומת תוסף זקוקה לכל הפחות לשדות name ו-source שאומרים ל-Claude Code מאיפה למשוך אותו. ראה את הסכמה המלאה למטה עבור כל השדות הזמינים.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

#סכמת ה-marketplace

#שדות חובה

שמות שמורים: שמות ה-marketplace הבאים שמורים לשימוש רשמי של Anthropic ואינם יכולים לשמש שווקי צד שלישי: claude-code-marketplace, claude-code-plugins, claude-plugins-official, claude-plugins-community, claude-community, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, knowledge-work-plugins, life-sciences, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins, claude-tag-plugins, healthcare. שמות שמתחזים לשווקים רשמיים, כמו official-claude-plugins או anthropic-plugins-v2, חסומים גם הם. שמירת שמות אלה מונעת מ-marketplace של צד שלישי להציג את עצמו כמקור שפורסם על ידי Anthropic.

Claude Code בודק מחדש שמות שמורים בכל פעם שהוא טוען marketplace, ולא רק בעת הוספתו. marketplace שנרשם תחת אחד השמות האלה לפני שהשם הפך לשמור מפסיק להיטען ומדווח שהוא נרשם ממקור לא מהימן. הסר את ה-marketplace הזה והוסף אותו מחדש מהמקור הרשמי של Anthropic. marketplace של צד שלישי שהושפע משם שנשמר לאחרונה ייטען שוב ברגע שתוסיף אותו מחדש תחת שם אחר. לפני גרסה v2.1.205, השמות first-party-plugins ו-healthcare לא היו שמורים, ו-marketplace שכבר נרשם תחת שם שמור המשיך להיטען. לפני גרסה v2.1.265, השם claude-tag-plugins לא היה שמור.

אינך יכול גם לקרוא ל-marketplace בשמות npm, pip, uv, cargo, github או gh, בכל שילוב של אותיות גדולות וקטנות. בדיקה זו דורשת Claude Code בגרסה v2.1.275 ומעלה.

#שדות בעלים

#שדות רשות

השדות description ו-version מתקבלים גם תחת metadata לצורך תאימות לאחור.

#רשומות תוספים

כל רשומת תוסף במערך plugins מתארת תוסף והיכן למצוא אותו. ניתן לכלול כל שדה מתוך סכמת מניפסט התוסף, כגון description, version, author, commands ו-hooks, בנוסף לשדות הייחודיים ל-marketplace: source, category, tags, strict, relevance, headers ו-headersHelper.

#שדות חובה

#שדות רשות עבור תוסף

שדות מטא-נתונים סטנדרטיים:

הן הרשומה והן ה-plugin.json של התוסף עצמו יכולים להגדיר את שדות התצוגה displayName, description, author, homepage, repository, license ו-keywords. ברשימות תוספים ובפרטים, לפני ואחרי ההתקנה:

• עבור שדה שאתה מגדיר ברשומה, המשתמשים רואים את ערך הרשומה, גם כאשר plugin.json מגדיר ערך שונה.
• עבור שדה שהרשומה משאירה ללא הגדרה, המשתמשים רואים את הערך מ-plugin.json.

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

שדות תצורת רכיבים:

שדות אימות ארכיון:

הגדר שדות אלה כאשר לרשומה יש מקור מסוג archive בשרת שדורש אישורי גישה.

#מקורות תוספים

מקורות תוספים אומרים ל-Claude Code מהיכן להביא כל תוסף בודד המופיע ב-marketplace שלך. אלה מוגדרים בשדה source של כל רשומת תוסף ב-marketplace.json.

Claude Code מעתיק כל תוסף מותקן לתוך מטמון התוספים בעל הגרסאות המקומי בנתיב ~/.claude/plugins/cache, אלא אם התוסף נטען במקום. מקור מסוג command במצב קישור נטען במקום, וכך גם מקור נתיב יחסי ב-marketplace שנוסף מתיקייה מקומית. Claude Code גם מתקין את תלויות חבילות ה-Node.js הזכאיות של התוסף לתוך העותק השמור במטמון. ראה מטמון תוספים ופתרון קבצים לגבי האופן שבו תוסף שנטען במקום מתוך marketplace של תיקייה מקומית קולט את העריכות שלך.

מקורות marketplace לעומת מקורות תוסף: אלה מושגים שונים השולטים בדברים שונים.

• מקור marketplace: מהיכן למשוך את קטלוג marketplace.json עצמו. נקבע כאשר משתמשים מריצים /plugin marketplace add או בהגדרות extraKnownMarketplaces. מקורות marketplace המבוססים על git תומכים ב-ref (ענף או תגית) אך לא ב-sha.
• מקור תוסף: מהיכן למשוך תוסף בודד הרשום ב-marketplace. נקבע בשדה source של כל רשומת תוסף בתוך marketplace.json. מקורות תוסף המבוססים על git תומכים הן ב-ref (ענף או תגית) והן ב-sha (commit מדויק).

לדוגמה, marketplace המאוחסן ב-acme-corp/plugin-catalog (מקור marketplace) יכול לרשום תוסף שנמשך מ-acme-corp/code-formatter (מקור תוסף). מקור ה-marketplace ומקור התוסף מצביעים על מאגרים שונים ומוצמדים באופן עצמאי.

סוגי המקורות המבוססים על git להלן הם github, url ו-git-subdir. כאשר גם ref וגם sha מוגדרים באחד מהם, sha הוא ההצמדה הקובעת. Claude Code מושך ובודק (checks out) את ה-commit המוצמד ישירות.

ברוב מארחי ה-git, כולל GitHub, GitLab ו-Bitbucket, פירוש הדבר שההתקנה מצליחה גם אם הענף או התגית שצוינו ב-ref נמחקו מאז במקור המרוחק, כל עוד ה-commit עדיין נגיש מהמאגר. שרתים מסוימים, כגון AWS CodeCommit, אינם תומכים במשיכת commits לפי SHA. בשרתים אלה ה-ref חייב עדיין להתקיים וה-commit המוצמד חייב להיות נגיש ממנו.

אם אתה מפיץ תוספים דרך הגדרות ארגון > תוספים (Organization settings > Plugins), רק חלק מסוגי המקורות מורשים. ראה הפצה באמצעות הגדרות ארגון.

#נתיבים יחסיים

עבור תוספים באותו מאגר, השתמש בנתיב שמתחיל ב-./:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

נתיבים נפתרים ביחס לשורש ה-marketplace, שהוא התיקייה המכילה את .claude-plugin/. לפיכך, המקור ./plugins/my-plugin מצביע על <repo>/plugins/my-plugin, אף על פי ש-marketplace.json שוכן בנתיב <repo>/.claude-plugin/marketplace.json. אל תשתמש ב-../ כדי להתייחס לנתיבים מחוץ לשורש ה-marketplace. במערכות macOS ו-Linux, Claude Code דוחה נתיב רשומה עם לוכסן הפוך (backslash) בכל מקום אחרי ה-./ הפותח, לכן כתוב את המפרידים בתור / בכל הפלטפורמות.

שם חשוף (bare name) הוא שם תיקייה יחיד ללא /, כגון "formatter". כדי לכתוב שמות חשופים במקום נתיבי ./, הגדר את metadata.pluginRoot לתיקייה שתחתיה הם נפתרים. עם "pluginRoot": "./plugins", Claude Code פותר את "source": "formatter" ל-./plugins/formatter. דורש Claude Code בגרסה v2.1.239 ומעלה.

השדה metadata.pluginRoot חייב להיות בעצמו נתיב יחסי בתוך ה-marketplace. Claude Code מתעלם ממנו עבור מקור שכבר מתחיל ב-./. מקור המכיל /, כגון team-a/formatter, אינו נחשב לשם חשוף ועדיין זקוק לקידומת ./, גם כאשר metadata.pluginRoot מוגדר.

הערה: Claude Code פותר נתיבים יחסיים כנגד עותק מקומי של ה-marketplace, ולכן הם עובדים כאשר משתמשים מוסיפים את ה-marketplace שלך ממקור git או מתיקייה מקומית. אם משתמשים מוסיפים את ה-marketplace שלך באמצעות כתובת URL ישירה לקובץ marketplace.json, נתיבים יחסיים לא ייפתרו, מכיוון ש-Claude Code מוריד רק את הקובץ הזה. להפצה מבוססת URL, השתמש בכל מקור תוסף אחר במקום זאת. ראה פתרון בעיות לפרטים.

#מאגרי GitHub

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

ניתן להצמיד לענף, לתגית או ל-commit ספציפיים:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

#מאגרי Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

ניתן להצמיד לענף, לתגית או ל-commit ספציפיים:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

#תת-תיקיות Git

השתמש ב-git-subdir כדי להצביע על תוסף שנמצא בתוך תת-תיקייה של מאגר git. Claude Code משתמש בשכפול חלקי (sparse clone) כדי למשוך רק את תת-התיקייה, ובכך ממזער את רוחב הפס עבור monorepos גדולים.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

ניתן להצמיד לענף, לתגית או ל-commit ספציפיים:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

השדה url מקבל גם קיצור של GitHub בפורמט owner/repo או כתובות URL ב-SSH בפורמט [email protected]:owner/repo.git.

#חבילות npm

מקור מסוג npm יכול לציין כל חבילה במאגר הציבורי של npm או במאגר פרטי שהצוות שלך מאחסן. Claude Code פותר את החבילה באמצעות לקוח ה-npm שלך, מוריד את קובץ ה-tarball, ופורק אותו לתוך מטמון התוספים.

סקריפטים של התקנת החבילה, כגון preinstall או postinstall, אינם רצים לעולם, והתלויות שלה אינן מותקנות במהלך המשיכה.

אם החבילה מספקת קובץ נעילה (lockfile) נתמך לצד קובץ ה-package.json שלה, Claude Code מתקין את אותן תלויות חבילות Node.js בשלב נפרד, גם כן כאשר סקריפטים מושבתים. אחרת, פרסם את התוסף כאשר כל מה שהוא צריך כבר בנוי. שרת MCP הזקוק לחבילות אחרות יכול לפעול באמצעות npx, שמתקין אותן בהרצה הראשונה.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

כדי להצמיד לגרסה ספציפית, הוסף את השדה version:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

כדי להתקין ממאגר פרטי או פנימי, הוסף את השדה registry:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

#ארכיוני Zip

השתמש ב-archive כדי להפיץ תוסף כקובץ zip ש-Claude Code מוריד באמצעות HTTPS, כך שההתקנות פועלות ללא git או npm במחשב המשתמש. אחסן את הקובץ בכל שרת קבצים סטטי או מאגר ארטיפקטים, כגון ארגז (bucket) ב-S3, מאגר כללי ב-Artifactory או nginx. דורש Claude Code בגרסה v2.1.224 ומעלה. בגרסאות v2.1.120 עד v2.1.223, התקנת התוסף נכשלת עם ההודעה This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.; בגרסאות ישנות יותר, marketplace המכיל רשומת archive נכשל בטעינה לחלוטין.

רשומה זו מתקינה את התוסף מקובץ zip בשרת ארטיפקטים:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

כאשר אתה בונה את ה-zip, תוכל לדחוס את תוכן התוסף ישירות או לדחוס את תיקיית התוסף עצמה. Claude Code מחפש את .claude-plugin/ בראש הארכיון, ולאחר מכן בתוך תיקייה יחידה ברמה העליונה, כך ששני המבנים ניתנים להתקנה:

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

Claude Code אינו מחפש עמוק יותר מתיקייה אחת, ולכן תוסף המקונן עמוק יותר ייכשל בהתקנה. Claude Code דוחה ארכיונים הגדולים מ-256 MiB.

כדי להצמיד את הקובץ המדויק, הוסף שדה sha256 עם ה-digest של הארכיון:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

אם הקובץ שהורד אינו תואם להצמדה, Claude Code דוחה את ההתקנה ומדווח על Plugin archive integrity check failed.

מקורות מסוג ארכיון מקבלים שדות אלה:

ערך ה-sha256 משמש גם כגרסת התוסף כאשר לא קובץ ה-plugin.json ולא רשומת ה-marketplace מגדירים גרסה. ראה ניהול גרסאות. אם אתה מגדיר version, מחרוזת גרסה זו היא האות לעדכון, לכן לאחר שינוי קובץ ה-zip וה-digest שלו, קדם גם את הגרסה, אחרת משתמשים ישמרו על העותק שבמטמון.

#אימות הורדות ארכיון

כדי לאמת הורדת ארכיון, כגון הורדה ממאגר פרטי, הגדר את כותרות ה-HTTP ש-Claude Code שולח איתה. הגדר headers במקור ה-url שממנו רשמת את ה-marketplace, כגון רשומת extraKnownMarketplaces. ב-Claude Code בגרסה v2.1.238 ומעלה, ניתן להגדיר זאת ברשומת התוסף עצמה במקום זאת, לצד source.

אם הערך שהיית מציב ב-headers הוא בעל תוקף קצר, כגון אסימון שהמאגר שלך מנפיק לפי דרישה, הגדר פקודת headersHelper באותו מקום במקום זאת. Claude Code מריץ את הפקודה ושולח את אובייקט ה-JSON שהיא מדפיסה בתור הכותרות של אותו מקום. דורש Claude Code בגרסה v2.1.238 ומעלה.

המקום שתבחר קובע אילו הורדות מקבלות את הכותרות ומתי Claude Code מריץ את הפקודה:

כאשר שני המקומות מגדירים כותרת בעלת אותו שם, Claude Code שולח את ערך הרשומה. בתוך אותו מקום, כותרת שהפקודה מדפיסה דורסת כותרת בעלת אותו שם המופיעה ב-headers.

#הוספת headersHelper לרשומת תוסף

רשומה זו מגדירה headersHelper לצד source. היא מגדירה בנוסף "strict": false, דבר ש-Claude Code דורש מרשומת marketplace.json שמגדירה headersHelper. עם "strict": false, רשומת ה-marketplace היא הגדרתו המלאה של התוסף, כך שמשתמש יכול לבדוק מה התוסף מכיל לפני שהוא מאשר את הפקודה:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

כדי לבדוק את הרשומה, הרץ claude plugin install my-plugin@your-marketplace. Claude Code מציג לך את הפקודה ואת כתובת ה-URL של הארכיון, ומוריד את ה-zip לאחר שאתה מאשר.

לפני גרסה v2.1.238, Claude Code הוריד ארכיון של רשומה ללא שדות ה-headers או ה-headersHelper שלה, ולכן התקנה שהסתמכה עליהם נכשלה עם HTTP 401 while downloading plugin archive from, ולאחר מכן כתובת ה-URL, כאשר קוד המצב של המאגר מופיע במקום 401.

#כתיבת פקודת headersHelper

בין אם הגדרת headersHelper במקור url של marketplace או ברשומת תוסף, כתוב את הפקודה כך שתעמוד בדרישות הבאות:

• טקסט הפקודה: לכל היותר 500 תווים של תווי ASCII ניתנים להדפסה, ללא רצף של ארבעה רווחים או יותר.
• פלט: הדפס אובייקט JSON יחיד של שמות כותרות וערכי מחרוזת ב-stdout, ואז צא עם קוד 0 תוך 10 שניות.
• מעטפת ותיקיית עבודה: Claude Code מריץ את הפקודה באמצעות sh, או cmd.exe ב-Windows, מתוך תיקיית התצורה, ~/.claude או CLAUDE_CONFIG_DIR. ציין נתיב מוחלט או פקודה הקיימת ב-PATH, מכיוון שנתיב יחסי נפתר ביחס לתיקייה זו, ולא ביחס לפרויקט של המשתמש.
• משתנים ש-Claude Code מסיר: מסביבת הפקודה שהוגדרה ברשומת marketplace.json או בקובצי .claude/settings.json או .claude/settings.local.json של הפרויקט, Claude Code מסיר כל משתנה ששמו מכיל מילה כגון TOKEN, SECRET, KEY או AUTH, כולל ANTHROPIC_API_KEY. Claude Code אינו מבצע הסרה זו עבור פקודה שהוגדרה בהגדרות משתמש, בקובץ --settings או בהגדרות מנוהלות.
• משתנים ש-Claude Code מגדיר: CLAUDE_CODE_MARKETPLACE_URL ו-CLAUDE_CODE_MARKETPLACE_NAME עבור פקודה של מקור url, וכן CLAUDE_CODE_PLUGIN_NAME ו-CLAUDE_CODE_PLUGIN_ARCHIVE_URL עבור פקודה של רשומה. המשתנה CLAUDE_CODE_MARKETPLACE_NAME אינו מוגדר במשיכה הראשונה לאחר שמשתמש מוסיף marketplace באמצעות URL, מכיוון שמשיכה זו היא שמספקת את השם.

פקודה שמנפיקה bearer token מדפיסה אובייקט כזה:

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

#מתי Claude Code מדלג על פקודת headersHelper או משמיט את הפלט שלה

Claude Code אינו מריץ פקודת headersHelper, או משמיט כותרות שהגיעו מ-headers או מפלט הפקודה, במצבים הבאים:

• הפקודה נכשלת: אם הפקודה יוצאת עם קוד שאינו אפס, רצה מעבר ל-10 שניות, או מדפיסה דבר שאינו אובייקט JSON של ערכי מחרוזות, Claude Code אינו מבצע את המשיכה או ההורדה שלשמן הוא הריץ את הפקודה.
• כתובת ה-URL של ה-marketplace אינה מתחילה ב-https://: Claude Code אינו מריץ את הפקודה של מקור ה-url ושולח רק את הכותרות הרשומות בשדה headers שלו.
• הפניה אוטומטית (redirect) יוצאת מהמקור (origin): כאשר הורדה מופנית אל מחוץ למקור של כתובת ה-URL של הארכיון, Claude Code משמיט את ערכי ה-headers ופלט הפקודה הן של מקור ה-url של ה-marketplace והן של רשומת התוסף.
• הרשומה מגדירה כותרת ניתוב או זהות: Claude Code משמיט שמות ניתוב בקשות וזהות לקוח כגון Host, Cookie ו-X-Forwarded-* מתוך headers ומפלט הפקודה של רשומה, ושומר על שמות אימות כגון Authorization. Claude Code מסנן כל רשומת marketplace.json באופן זה, וכן רשומת הגדרות מוטמעת (inline) בהתאם לקובץ שמצהיר עליה.
• פקודה מוגדרת בהגדרות של תיקיית --add-dir: Claude Code מתעלם ממנה, הן במקור url והן ברשומת תוסף מוטמעת, ושולח רק את ה-headers של אותו קובץ.
• הגדרות מנוהלות חוסמות את הפקודה: הגדרת disableCommandPluginSources ל-true חוסמת פקודות headersHelper, ו-allowManagedHooksOnly חוסמת אותן גם כן אלא אם disableCommandPluginSources מוגדר במפורש ל-false. תחת כל אחת מהחסימות, Claude Code עדיין מריץ את הפקודה עבור marketplace שההגדרות המנוהלות עצמן מצהירות עליו.

#כיצד משתמשים מאשרים פקודת headersHelper

משתמש מאשר פקודה של רשומת תוסף בכל פעם שהוא מתקין או מעדכן את התוסף הבודד הזה בפני עצמו, מתוך תצוגת התוסף ב-/plugin או באמצעות claude plugin install או claude plugin update. Claude Code מציג את הפקודה ואת כתובת ה-URL של הארכיון, ומריץ את הפקודה רק לאחר שהמשתמש מאשר.

במעטפת שאינה אינטראקטיבית, העבר --yes כדי לאשר את הפקודה. כדי לאשר רק את הפקודה שהרצת --json קודמת הציגה, העבר --accept-command יחד עם ה-sha256 שההרצה דיווחה עליו.

Claude Code מריץ רק את הפקודה שהוא הציג, עבור כתובת ה-URL של הארכיון שהוא הציג. אם פקודת הרשומה או כתובת ה-URL של הארכיון השתנו בינתיים, Claude Code דוחה את ההתקנה או העדכון. שינוי במחרוזת השאילתה (query string) לבדה אינו נחשב.

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

בכל פעולה שאינה התקנה או עדכון של תוסף יחיד, Claude Code אינו מריץ את פקודת הרשומה ואינו מוריד את הארכיון שלה, כך שהתוסף נשאר בגרסתו המותקנת או נשאר בלתי מותקן. מה שהמשתמש רואה תלוי בפעולה:

• התקנת מספר תוספים בבת אחת, מתוך הצעת תוסף, או כתלות של תוסף אחר: Claude Code דוחה את התוסף שמכיל את הפקודה ומפנה את המשתמש לתצוגת התוסף עצמו ב-/plugin. שאר התוספים בהתקנה מרוכזת (bulk install) עדיין מותקנים. תוסף התלוי בתוסף שנדחה נכשל בהתקנה עד שהמשתמש יתקין את התוסף שנדחה בפני עצמו.
• עדכון אוטומטי ברקע, או הפעלת הפעלה (session start) עבור תוסף שהארכיון שלו מעולם לא הורד: Claude Code מפרט את התוסף בלשונית Errors ב-/plugin כדי שהמשתמש יידע להתקין או לעדכן אותו ידנית. עדכון אוטומטי שמוצא שהרשומה עדיין מפרסמת את הגרסה המותקנת אינו מציג דבר.

#מתי פקודה של מקור url ברמת ה-marketplace רצה

פקודת headersHelper של מקור url ב-marketplace מוצהרת בקובץ הגדרות, כגון רשומת extraKnownMarketplaces, ולא בקטלוג שה-marketplace מפרסם, ולכן Claude Code אינו מבקש מהמשתמש לאשר אותה בכל התקנה או עדכון. קובץ ההגדרות שמצהיר עליה קובע מתי Claude Code מריץ אותה:

בהפעלת -p או בהפעלת SDK, Claude Code אינו יכול להציג את תיבת הדו-שיח לאישור אבטחה. הוא מחיל את שאר ההגדרות שנמסרו, אך משיכת ה-marketplace, וכל הורדת ארכיון הזקוקה לפקודה, נכשלות עד שמשתמש יאשר בהפעלה אינטראקטיבית.

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

#מקורות פקודה

השתמש ב-command כאשר כלי המותקן מקומית מייצר את תיקיית התוסף, כגון סביבת פיתוח (IDE) המרנדרת את התוסף שלה עבור שרשרת הכלים (toolchain) שנבחרה כעת. Claude Code מריץ את הפקודה כאשר המשתמש מתקין את התוסף ומריץ אותה שוב ברקע פעם אחת בכל הפעלה, כך שהמשתמשים שלך מקבלים את הפלט שהשתנה של הכלי מבלי להתקין מחדש. דורש Claude Code בגרסה v2.1.229 ומעלה. בגרסאות v2.1.120 עד v2.1.228, התקנת התוסף נכשלת עם This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again., ובגרסאות ישנות יותר ה-marketplace כולו נכשל בטעינה.

רשומה זו מתקינה את התוסף מכל תיקייה שהכלי מדפיס:

{
  "name": "my-plugin",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path"
  }
}

Claude Code מריץ את הפקודה דרך מעטפת הפלטפורמה, sh ב-macOS וב-Linux או cmd.exe ב-Windows, מתוך תיקיית הבית של המשתמש. הפקודה חייבת להדפיס בדיוק שורה אחת ב-stdout ולצאת עם קוד 0. שורה זו היא הנתיב המוחלט של תיקייה המכילה את התוסף השלם עד למועד יציאת הפקודה, והנתיב עשוי להשתנות בין הרצות.

Claude Code עוצר פקודה שרצה זמן רב יותר מ-timeout שניות, וההתקנה או העדכון נכשלים. Claude Code דוחה בנוסף את הנתיב שהודפס במקרים הבאים, וההתקנה או העדכון נכשלים באותו אופן:

• התיקייה אינה מכילה תוכן של תוסף ברמה העליונה שלה, כגון תיקיית .claude-plugin/ או תיקיית skills/, commands/, agents/ או hooks/
• התיקייה היא זו שבה Claude Code הופעל, או אחת מתיקיות האב שלה
• ב-Windows, הנתיב הוא נתיב UNC

מקורות מסוג פקודה מקבלים שדות אלה:

#מצב העתקה ומצב קישור

עם ברירת המחדל "mode": "copy", Claude Code מעתיק את התיקייה שהודפסה לתוך מטמון התוספים בעל הגרסאות וגוזר את גרסת התוסף מ-hash של תוכן התיקייה. הכלי שלך יכול למחוק או לכתוב מחדש את התיקייה לאחר יציאת הפקודה, והרצה מחדש המייצרת תוכן זהה נחשבת למעודכנת. Claude Code דוחה התקנה של תיקייה הגדולה מ-256 MiB או המכילה יותר מ-20,000 רשומות.

הגדר "mode": "link" עבור תיקיות תוסף גדולות שאין להעתיקן, כגון ייצוא SDK מרונדר. Claude Code ממלא את רשומת המטמון של התוסף בקישור לכל רשומה ברמה העליונה של התיקייה שהודפסה ומשתמש בקבצים במקומם, כך ששום דבר אינו מועתק, תוכן הקבצים אינו עובר hashing, ומגבלות הגודל אינן חלות. ההתקנה נכשלת אם רשומה ברמה העליונה היא symlink המצביע מחוץ לתיקייה שהודפסה. Claude Code מדלג בנוסף על התקנת תלויות חבילות Node.js עבור תוסף במצב link, לכן הדפס תיקייה שכבר מכילה את כל ה-node_modules שהתוסף צריך.

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

Claude Code אינו תומך במצב קישור ב-Windows ודוחה התקנת תוסף במצב קישור שם. הצהר על "mode": "copy" במקום זאת.

#כיצד משתמשים מאשרים את הפקודה

Claude Code מריץ את הפקודה שלך במחשב של המשתמש, ולכן הוא קושר כל הרצה לאישור מפורש של המשתמש:

• כאשר משתמשים מתקינים את התוסף ממסך הפרטים שלו ב-/plugin, או מתקינים או מעדכנים אותו עם claude plugin install או claude plugin update בטרמינל אינטראקטיבי, Claude Code מציג להם תחילה את מחרוזת הפקודה המדויקת ורושם את הפקודה שאושרה עבור אותה התקנה. הפקודה claude plugin update שיכולה להמשיך על בסיס האישור הרשום של אותה פקודה אינה מציגה דבר.
• במעטפת שאינה אינטראקטיבית, כגון סקריפט התקנה (provisioning script), העבר --yes אל claude plugin install או claude plugin update כדי לאשר את הפקודה שהיא מדפיסה. כדי לאשר רק את הפקודה שהרצת --json קודמת הציגה, העבר --accept-command יחד עם ה-sha256 שההרצה דיווחה עליו.
• כל נתיב אחר מריץ רק את הפקודה שהמשתמש כבר אישר. זה כולל עדכונים שהחלו מתוך /plugin ואת הרצות הרקע המתוארות בסעיף מתי Claude Code מריץ מחדש את הפקודה. כאשר אף פקודה לא אושרה, Claude Code מסרב להריץ את הפקודה ואומר למשתמש כיצד לבדוק אותה. Claude Code לעולם אינו מתקין תוסף שמקורו בפקודה כתלות של תוסף אחר, ולכן משתמשים מתקינים אותו בעצמם תחילה.
• אם אתה משנה את ה-command של הרשומה, או מחליף את ה-mode שלה, המשתמשים שומרים על הגרסה שכבר יש להם ו-Claude Code מפסיק להריץ את הפקודה מחדש. בהפעלות אינטראקטיביות, לשונית Errors ב-/plugin מציגה את הפקודה החדשה עד שהמשתמש יבדוק ויאשר אותה על ידי הרצת claude plugin update <plugin>@<marketplace>.

מנהלי מערכת יכולים לחסום מקורות פקודה בכל רחבי הארגון באמצעות ההגדרה המנוהלת disableCommandPluginSources. אם ארגון מגדיר allowManagedHooksOnly, Claude Code חוסם מקורות פקודה כברירת מחדל.

#מתי Claude Code מריץ מחדש את הפקודה

התיקייה שהודפסה משקפת את מצב הכלי בזמן שהפקודה רצה, ולכן Claude Code מריץ את הפקודה שוב בזמנים הבאים:

• בכל פעם שהמשתמש מתקין או מעדכן את התוסף
• פעם אחת בכל הפעלה עבור כל תוסף מופעל שמקורו בפקודה, ברקע, זמן קצר לאחר תחילת ההפעלה. הרצה זו אינה עוברת דרך עדכון אוטומטי של ה-marketplace, ולכן אינה תלויה בהגדרת העדכון האוטומטי של ה-marketplace
• בעת הפעלה או ב-/reload-plugins, כאשר גרסה מותקנת של תוסף מופעל חסרה במטמון התוספים

Claude Code מדלג על שתי הרצות הרקע כאשר המשתמש מגדיר CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. התקנות ועדכונים מפורשים עדיין מריצים את הפקודה כאשר משתנה זה מוגדר.

כאשר הפלט שעבר hash של הפקודה השתנה, Claude Code מתקין את התוצאה כגרסה חדשה וטוען אותה מחדש בהפעלה האינטראקטיבית הפעילה, תוך החלפת אותם רכיבים ש-/reload-plugins מחליף. המשתמש רואה הודעה שהתוסף נטען מחדש. אם טעינה מחדש במקום הייתה מבטלת את תוקף מטמון הפרומפטים (prompt cache) של ההפעלה, Claude Code מנחה את המשתמש במקום זאת להריץ /reload-plugins, אשר מתריע על עלות המטמון ומוחל כאשר מורץ מחדש עם --force.

#רשומות תוסף מתקדמות

דוגמה זו מציגה רשומת תוסף המשתמשת ברבים משדות הרשות, כולל נתיבים מותאמים אישית עבור commands, agents, hooks ושרתי MCP:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

נקודות עיקריות שיש לשים לב אליהן:

• commands ו-agents: באפשרותך לציין מספר תיקיות או קבצים בודדים. נתיבים הם יחסיים לשורש התוסף וחייבים להישאר בתוכו.
  • Claude Code דוחה נתיב שנפתר מחוץ לתיקיית התוסף, כגון ./../shared.md, עם שגיאת path escapes plugin directory, ועדיין טוען את התוסף ללא אותו רכיב
• ${CLAUDE_PLUGIN_ROOT}: השתמש במשתנה זה בפקודות hook ובתצורות שרתי MCP כדי להתייחס לקבצים בתוך תיקיית ההתקנה של התוסף.
  • ראה את טבלת ההחלפות לגבי אילו שדות תצורה מחליפים אותו לפי סוג שרת
  • עבור תלויות או מצב שאמורים לשרוד עדכוני תוסף, השתמש ב-${CLAUDE_PLUGIN_DATA} במקום זאת
• strict: false: מכיוון שזה מוגדר כ-false, התוסף אינו זקוק ל-plugin.json משלו. רשומת ה-marketplace מגדירה הכל. ראה מצב קפדני (Strict mode) להלן.

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

"skills": ["./skills/", "./extra-skills/"]

כאשר מספר רשומות תוסף חולקות תיקיית skills/ אחת בשורש ה-marketplace (source: "./"), רשום תת-תיקיות ספציפיות במקום זאת כך שכל רשומה תטען רק את ה-skills שלה:

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

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

#מצב קפדני (Strict mode)

השדה strict קובע האם plugin.json הוא הסמכות להגדרות רכיבים (skills, agents, hooks, שרתי MCP, סגנונות פלט).

מתי להשתמש בכל מצב:

• strict: true: לתוסף יש plugin.json משלו והוא מנהל את הרכיבים שלו בעצמו. רשומת ה-marketplace יכולה להוסיף skills או hooks נוספים מעל. זוהי ברירת המחדל והיא מתאימה לרוב התוספים.
• strict: false: מפעיל ה-marketplace מעוניין בשליטה מלאה. מאגר התוסף מספק קבצים גולמיים, ורשומת ה-marketplace מגדירה אילו מקבצים אלה נחשפים כ-skills, כ-agents, כ-hooks וכו'. שימושי כאשר ה-marketplace מבנה מחדש או אוצר את רכיבי התוסף באופן שונה ממה שהתכוון מחבר התוסף.