Gợi ý plugin cho tổ chức

Nếu bạn vận hành một marketplace plugin cho tổ chức, bạn có thể để Claude Code gợi ý các plugin cụ thể cho user dựa trên việc họ đang làm gì. Thêm một block relevance vào entry của plugin trong marketplace.json, sau đó allowlist marketplace đó trong managed settings. Khi tín hiệu trong session của user khớp với một tín hiệu đã khai báo, Claude Code hiện gợi ý cài plugin đó.

Gợi ý do marketplace khai báo là opt-in theo từng marketplace qua managed settings. Không có khai báo relevance nào của bất kỳ marketplace nào tạo ra gợi ý cho tới khi admin thêm nó vào allowlist - kể cả marketplace chính thức của Anthropic. Claude Code còn có một gợi ý tích hợp sẵn độc lập với allowlist này; gợi ý đó và mọi tip do marketplace khai báo đều bị tắt khi spinnerTipsEnabled đặt false.

Ghi chú

Tính năng này yêu cầu Claude Code v2.1.152 trở lên. Client cũ hơn bỏ qua field relevance.

Trang này dành cho người vận hành marketplace và admin tổ chức. Nếu bạn muốn cài plugin, xem Khám phá và cài plugin.

Cách hoạt động

Mỗi entry plugin trong marketplace.json có thể mang một object relevance, đặt tên một topic và một hoặc nhiều tín hiệu (signal). Một signal là một pattern mà Claude Code test với session hiện tại, như thư mục làm việc hoặc file Claude đã đọc.

Việc match tín hiệu diễn ra cục bộ trên máy user. Việc match không tạo network traffic và không báo cáo tín hiệu nào đã khớp, hoặc giá trị của chúng, cho Anthropic hoặc marketplace operator.

Khi một tín hiệu khớp và plugin chưa cài, Claude Code hiện plugin ở ba nơi:

• Spinner tip: thông báo “Working with topic? Install the plugin plugin” kèm lệnh /plugin install, hiện dưới spinner khi Claude đang phản hồi.
• Gợi ý lúc bắt đầu session: nếu tín hiệu cwd khớp thư mục làm việc, một thông báo một dòng plugin suggestion: <name>@<marketplace> · /plugin xuất hiện trước lượt đầu tiên (từ v2.1.153).
• Tab Discover của /plugin: plugin được ghim lên đầu danh sách Discover với chú thích như “suggested for this directory” (từ v2.1.154).

Spinner tip và thông báo session-start thuộc hệ thống spinner-tips. Cả hai bị tắt khi user hoặc project đặt spinnerTipsEnabled là false. Việc ghim ở tab Discover độc lập với các setting tip.

Claude Code không bao giờ tự cài plugin - user luôn phải xác nhận.

Thêm relevance vào entry plugin

Thêm object relevance vào entry plugin trong marketplace.json. Ví dụ sau khai báo plugin terraform-helpers relevant khi Claude đọc file .tf hoặc chạy terraform:

{
  "name": "acme-corp-plugins",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "terraform-helpers",
      "source": "./plugins/terraform-helpers",
      "description": "Quy ước và helper của Acme cho Terraform",
      "relevance": {
        "topic": "Terraform",
        "signals": {
          "cli": ["terraform"],
          "filesRead": ["**/*.tf"]
        }
      }
    }
  ]
}

Một plugin có block relevance nhưng không có tín hiệu nào khớp hoạt động như entry marketplace bình thường: xuất hiện trong danh sách Discover ở vị trí thường và không bao giờ hiện như spinner tip.

Tham chiếu field

relevance

Field	Kiểu	Mô tả
topic	string	Tùy chọn. Cụm từ điền vào “Working with topic?” trong spinner tip. Mặc định là tên plugin viết hoa từng đoạn tách bằng dấu gạch ngang. Tối đa 64 ký tự.
signals	object	Matcher quyết định khi nào plugin relevant. Cần ít nhất một signal để plugin có thể được gợi ý.

relevance.signals

Field	Kiểu	Mô tả
cwd	array of strings	Glob pattern match với thư mục làm việc của session (từ v2.1.153). Match như đường dẫn tuyệt đối, và khi trong git repo, cả đường dẫn tương đối repo root. Tối đa 10 pattern, 256 ký tự mỗi pattern. Đây là signal duy nhất có thể match lúc bắt đầu session.
cli	array of strings	Tên lệnh từ shell command Claude đã chạy trong session, ví dụ ["stripe"]. Match chính xác. Tối đa 10 entry, 64 ký tự mỗi entry.
hosts	array of strings	Hostname thấy trong URL http:///https:// của Bash command trong session, ví dụ ["api.stripe.com"]. Chỉ hostname trần, không scheme/port/path. Match chính xác, không phân biệt hoa/thường. Tối đa 20 entry, 128 ký tự mỗi entry.
filesRead	array of strings	Glob pattern match với đường dẫn file Claude đã đọc trong session, ví dụ ["**/*.tf"] (từ v2.1.153). Tối đa 10 pattern, 256 ký tự mỗi pattern.
manifestDeps	array of objects	Dependency khai báo trong package manifest Claude đã đọc trong session. Mỗi entry là { "file": "...", "pattern": "..." }, file là regex match đường dẫn file manifest, pattern là regex match nội dung file đó. File manifest lớn hơn 512 KB bị bỏ qua. Tối đa 10 entry.

Tín hiệu cli, hosts, filesRead, manifestDeps cần lịch sử session, nên chỉ có thể khớp ở spinner tip và tab Discover. Chỉ cwd có thể khớp lúc bắt đầu session.

Ví dụ dùng manifestDeps để gợi ý plugin Stripe khi Claude đọc một package.json phụ thuộc stripe:

{
  "name": "stripe-helpers",
  "source": "./plugins/stripe-helpers",
  "relevance": {
    "topic": "Stripe",
    "signals": {
      "manifestDeps": [
        {
          "file": "[/\\\\]package\\.json$",
          "pattern": "\"stripe\"\\s*:"
        }
      ]
    }
  }
}

Ghi chú

Claude Code bỏ qua field không nhận diện dưới relevance và relevance.signals lúc load, nên client cũ hơn vẫn load được marketplace của bạn. Chạy claude plugin validate ./my-marketplace để hiện chúng dưới dạng cảnh báo.

Bật gợi ý trong managed settings

Khai báo relevance trong marketplace.json chưa đủ. Admin phải allowlist marketplace trong managed settings trước khi gợi ý xuất hiện với user.

Thêm tên marketplace vào pluginSuggestionMarketplaces. Với marketplace khác marketplace chính thức của Anthropic, cũng khai báo nguồn marketplace trong cùng managed settings, dưới dạng entry của tên đó trong extraKnownMarketplaces hoặc strictKnownMarketplaces. Tên allowlist bị bỏ qua nếu marketplace đăng ký trên máy đến từ nguồn khác - ngăn một nguồn không liên quan đăng ký dưới tên allowlist để plugin của nó được gợi ý toàn tổ chức.

{
  "extraKnownMarketplaces": {
    "acme-corp-plugins": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

Marketplace chính thức được miễn yêu cầu khai báo nguồn vì tên của nó chỉ có thể đăng ký từ nguồn Anthropic chính thức:

{
  "pluginSuggestionMarketplaces": ["claude-plugins-official"]
}

Điều user thấy

Khi tín hiệu khớp trong một session, spinner tip hiện:

Working with Terraform? Install the terraform-helpers plugin:
/plugin install terraform-helpers@acme-corp-plugins

Lúc bắt đầu session, tín hiệu cwd khớp hiện thông báo một dòng:

plugin suggestion: terraform-helpers@acme-corp-plugins · /plugin

Gợi ý cho một plugin xuất hiện nhiều nhất một lần mỗi ba session (tính chung spinner tip và thông báo session-start), và không lặp lại sau khi plugin đã cài.

Validate marketplace của bạn

claude plugin validate ./my-marketplace

Validator báo cảnh báo key không nhận diện dưới relevance/relevance.signals, đánh dấu giá trị relevance không phải object, và từ chối entry signals.hosts có scheme/port/path.

Nguồn

Dịch và biên soạn từ Recommend plugins for your org.