CHƯƠNG 11 / 16

Plugins và cách phân phối

Đóng gói commands, agents, Skills, Hooks và MCP thành plugin dùng lại cho team.

Cập nhật 21 tháng 7, 202613 phút đọc

Plugin là cách đóng gói và chia sẻ phần mở rộng cho Claude Code: gộp commands/agents/skills/hooks/MCP servers vào một thư mục tự chứa (self-contained), phân phối qua marketplace và cài đặt bằng một lệnh. Chương này là tra cứu nhanh về cấu trúc plugin, plugin.json, cài đặt, marketplace, dependencies và cách tự tạo/phân phối.

Plugin là gì

Một plugin là một thư mục tự chứa các component mở rộng Claude Code. Component gồm: skills, agents, hooks, MCP servers, LSP servers, monitors, output styles, themes, và các executable trong bin/.

Điểm khác biệt so với cấu hình standalone trong .claude/:

Tiêu chí	Standalone (`.claude/`)	Plugin
Tên skill	`/hello`	`/plugin-name:hello` (namespaced)
Phạm vi	Một project	Tái sử dụng nhiều project, chia sẻ team/community
Phân phối	Copy tay	Cài qua marketplace, versioned, auto-update
Phù hợp cho	Cá nhân, thử nghiệm nhanh	Chia sẻ, phát hành có version

Namespacing (/plugin-name:skill-name) tránh xung đột khi nhiều plugin có skill trùng tên. Đổi tiền tố bằng field name trong plugin.json.

Mẹo: bắt đầu bằng standalone trong .claude/ để lặp nhanh, rồi convert thành plugin khi sẵn sàng chia sẻ.

Cấu trúc plugin

Chỉ plugin.json nằm trong .claude-plugin/. Mọi thư mục component khác phải ở plugin root (không được đặt trong .claude-plugin/).

enterprise-plugin/
├── .claude-plugin/
│   └── plugin.json          # manifest (tùy chọn)
├── skills/                  # skills dạng <name>/SKILL.md
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                # skills dạng file .md phẳng (dùng skills/ cho plugin mới)
├── agents/                  # định nghĩa subagent (.md)
├── hooks/
│   └── hooks.json           # event handlers
├── .mcp.json                # cấu hình MCP servers
├── .lsp.json                # cấu hình LSP servers
├── monitors/
│   └── monitors.json        # background monitors
├── output-styles/
├── themes/
├── bin/                     # executable thêm vào PATH của Bash tool khi plugin bật
├── settings.json            # default settings khi plugin bật
├── scripts/                 # script cho hooks/tiện ích
├── LICENSE
└── CHANGELOG.md

Bảng vị trí mặc định của từng component:

Component	Vị trí mặc định	Ghi chú
Manifest	`.claude-plugin/plugin.json`	Tùy chọn
Skills	`skills/<name>/SKILL.md`	Có thể kèm file phụ trợ
Commands	`commands/*.md`	Legacy; ưu tiên `skills/` cho plugin mới
Agents	`agents/*.md`	Subagent definitions
Hooks	`hooks/hooks.json`	Hoặc inline trong `plugin.json`
MCP servers	`.mcp.json`	Hoặc inline
LSP servers	`.lsp.json`	Hoặc inline
Monitors	`monitors/monitors.json`	Component experimental
Output styles	`output-styles/`
Themes	`themes/`	Component experimental
Executables	`bin/`	Gọi như lệnh trần trong Bash tool
Settings	`settings.json`	Chỉ hỗ trợ key `agent` và `subagentStatusLine`

Lưu ý:

Plugin chỉ có một skill có thể đặt SKILL.md ngay tại plugin root, không cần thư mục skills/. Tên gọi lấy từ field name trong frontmatter (từ v2.1.142 tự nhận diện layout này).
File CLAUDE.md ở plugin root không được nạp làm project context. Muốn nạp chỉ dẫn vào context của Claude, đặt vào một skill.

Manifest: plugin.json

Manifest ở .claude-plugin/plugin.json. Nếu bỏ qua, Claude Code auto-discover component ở vị trí mặc định và lấy tên plugin từ tên thư mục. Nếu có manifest, chỉ name là bắt buộc.

Schema đầy đủ (rút gọn):

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": { "name": "Author Name", "email": "author@example.com" },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "lspServers": "./.lsp.json",
  "experimental": { "themes": "./themes/", "monitors": "./monitors.json" },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Các field đáng chú ý:

Field	Vai trò
`name`	Bắt buộc. Kebab-case, không dấu cách. Là namespace cho component (agent `reviewer` → `plugin-name:reviewer`)
`displayName`	Tên hiển thị trong UI `/plugin` (cho phép dấu cách/hoa). Không dùng để lookup. Cần v2.1.143+
`version`	Semver. Đặt sẽ pin version: user chỉ nhận update khi bump field. Bỏ qua → dùng git commit SHA
`description`	Hiển thị khi browse/cài
`author`, `homepage`, `repository`, `license`, `keywords`	Metadata tùy chọn
`defaultEnabled`	`false` để cài ở trạng thái disabled cho tới khi user bật. Cần v2.1.154+
Component path fields	`skills`, `commands`, `agents`, `hooks`, `mcpServers`, `lspServers`, ... trỏ tới đường dẫn tùy biến
`userConfig`	Giá trị hỏi user lúc enable (thay cho sửa tay `settings.json`)
`dependencies`	Plugin khác mà plugin này cần

Field không nhận diện được sẽ bị bỏ qua (giúp một manifest kiêm cả package.json/VS Code extension). claude plugin validate báo là warning; thêm --strict để coi warning là error. Field sai kiểu (ví dụ keywords là string) vẫn là load error.

Quy tắc đường dẫn component

Thay thế default: commands, agents, outputStyles, experimental.themes, experimental.monitors. Muốn giữ default và thêm nữa, liệt kê tường minh: "commands": ["./commands/", "./extras/"].
Cộng thêm default: skills — thư mục skills/ luôn được quét, path khai báo thêm được nạp cùng.
Mọi path phải tương đối với plugin root và bắt đầu bằng ./. Không dùng ../ để trỏ ra ngoài root (file ngoài không được copy vào cache).

Biến môi trường

Biến	Trỏ tới	Dùng cho
`${CLAUDE_PLUGIN_ROOT}`	Thư mục cài của plugin	Script, binary, config đóng gói kèm plugin
`${CLAUDE_PLUGIN_DATA}`	Thư mục dữ liệu bền, sống sót qua update (`~/.claude/plugins/data/{id}/`)	`node_modules`, venv, cache, code sinh ra
`${CLAUDE_PROJECT_DIR}`	Project root	Script/config theo project

${CLAUDE_PLUGIN_ROOT} đổi khi plugin update — đừng ghi state ở đó, hãy dùng ${CLAUDE_PLUGIN_DATA}. Trong hook command dạng shell hoặc monitor, bọc biến trong dấu nháy kép: "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh".

Các loại component chính

Skills: tạo shortcut /name mà bạn hoặc Claude gọi được, model-invoked theo description. Đặt trong skills/<name>/SKILL.md (frontmatter YAML + hướng dẫn).
Agents: subagent trong agents/*.md. Hỗ trợ frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, isolation (chỉ "worktree"). Vì lý do bảo mật, plugin agent không hỗ trợ hooks, mcpServers, permissionMode.
Hooks: event handler trong hooks/hooks.json (hoặc inline). Cùng bộ lifecycle event như user hooks (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, ...). Kiểu hook: command, http, mcp_tool, prompt, agent.
MCP servers: .mcp.json (hoặc inline mcpServers). Tự khởi động khi plugin bật, hiện như tool MCP chuẩn.
LSP servers: .lsp.json — cho Claude code intelligence (diagnostics, go-to-definition, find references). User phải tự cài binary language server.
Monitors: monitors/monitors.json — chạy nền suốt session, mỗi dòng stdout thành notification cho Claude.

Ví dụ hook chạy script kèm plugin:

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

Tự tạo plugin

Quickstart

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Thêm một skill tại my-first-plugin/skills/hello/SKILL.md:

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.

Test cục bộ không cần cài đặt bằng cờ --plugin-dir:

claude --plugin-dir ./my-first-plugin

Trong session, gọi skill (namespaced) với argument:

/my-first-plugin:hello Alex

$ARGUMENTS bắt text người dùng nhập sau tên skill.
--plugin-dir nhận cả file .zip (v2.1.128+) và có thể lặp lại để nạp nhiều plugin. Dùng --plugin-url <zip-url> để nạp archive từ URL cho một session.
Sau khi sửa, chạy /reload-plugins để nạp lại mà không restart (reload plugins, skills, agents, hooks, MCP, LSP).

Scaffold nhanh và skills-directory plugin

claude plugin init my-tool --with skills hooks

Lệnh này tạo ~/.claude/skills/my-tool/ với plugin.json và SKILL.md mẫu. Session sau nó tự nạp thành my-tool@skills-dir — không cần marketplace, không bước install. Bất kỳ thư mục nào dưới skills directory có .claude-plugin/plugin.json đều được nạp kiểu này.

Bạn có	Là gì
`<skills-dir>/foo/SKILL.md` (không manifest)	Một skill thường tên `foo`
`<skills-dir>/foo/.claude-plugin/plugin.json`	Một plugin `foo@skills-dir`
`<plugin>/skills/bar/SKILL.md`	Skill `bar` đóng trong plugin

Phạm vi nạp: ~/.claude/skills/ = personal (mọi project); <cwd>/.claude/skills/ = project (chỉ sau khi trust workspace, và project-scope không walk-up lên repo root — hãy khởi động từ repo root).

Gỡ bằng cách xóa thư mục hoặc claude plugin disable my-tool@skills-dir (không có bước uninstall vì không cài từ marketplace).

Convert cấu hình standalone thành plugin

Standalone (`.claude/`)	Plugin
Chỉ dùng trong một project	Chia sẻ qua marketplace
`.claude/commands/`	`plugin-name/commands/`
Hooks trong `settings.json`	`hooks/hooks.json` (cùng format, copy object `hooks`)
Copy tay để chia sẻ	Cài bằng `/plugin install`

Sau khi convert, xóa file gốc trong .claude/ để tránh trùng: định nghĩa agent trong .claude/agents/ override agent cùng tên của plugin. Riêng skill được namespaced nên /skill-name gốc và bản plugin cùng tồn tại.

Validate và debug

claude plugin validate ./my-plugin           # kiểm tra manifest, frontmatter, hooks.json
claude plugin validate ./my-plugin --strict  # coi warning là error (dùng trong CI)
claude --debug                                # xem chi tiết nạp plugin

Lỗi thường gặp: đặt component trong .claude-plugin/ (phải ở root); script hook không executable (chmod +x); dùng path tuyệt đối (phải tương đối, ./); quên ${CLAUDE_PLUGIN_ROOT} cho path MCP; thiếu binary LSP (Executable not found in $PATH).

Marketplace: phân phối plugin

Một marketplace là catalog liệt kê plugin và nơi lấy chúng, cho phép discovery tập trung, version tracking và auto-update. File catalog là .claude-plugin/marketplace.json ở gốc repo.

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

Field bắt buộc: name (kebab-case, public-facing, mỗi user chỉ đăng ký một marketplace/tên), owner, plugins. Mỗi plugin entry cần tối thiểu name và source, có thể kèm bất kỳ field nào từ manifest schema cộng field riêng của marketplace: source, category, tags, strict, relevance.

Plugin sources

Source	Kiểu	Fields	Ghi chú
Relative path	`string` `"./my-plugin"`	—	Thư mục trong repo marketplace, phải bắt đầu `./`, resolve từ marketplace root
`github`	object	`repo`, `ref?`, `sha?`	`owner/repo`
`url`	object	`url`, `ref?`, `sha?`	Git URL bất kỳ
`git-subdir`	object	`url`, `path`, `ref?`, `sha?`	Sparse clone subdirectory (monorepo)
`npm`	object	`package`, `version?`, `registry?`	Cài qua `npm install`

Với source git, khi có cả ref và sha thì sha là pin hiệu lực. Phân biệt marketplace source (nơi lấy marketplace.json, hỗ trợ ref không sha) với plugin source (nơi lấy từng plugin, hỗ trợ cả ref và sha).

strict (mặc định true): plugin.json là nguồn định nghĩa component, marketplace entry chỉ bổ sung. strict: false: marketplace entry định nghĩa toàn bộ, plugin không cần plugin.json.

Cài đặt và quản lý

Thêm marketplace rồi cài từng plugin:

/plugin marketplace add anthropics/claude-code        # GitHub owner/repo
/plugin marketplace add https://gitlab.com/co/p.git   # git URL bất kỳ
/plugin marketplace add ./my-marketplace              # local path
/plugin install code-formatter@company-tools
/reload-plugins

Marketplace của Anthropic: claude-plugins-official (tự có khi khởi động, cài <name>@claude-plugins-official); claude-community (thêm tay anthropics/claude-plugins-community, cài <name>@claude-community). Gửi plugin lên community marketplace qua form claude.ai hoặc Console; chạy claude plugin validate trước khi nộp.

Scope cài đặt quyết định plugin ghi vào file settings nào:

Scope	File	Dùng cho
`user` (mặc định)	`~/.claude/settings.json`	Cá nhân, mọi project
`project`	`.claude/settings.json`	Team, chia sẻ qua version control
`local`	`.claude/settings.local.json`	Riêng project, gitignored
`managed`	Managed settings	Admin quản lý (read-only)

CLI không tương tác (dùng cho script/CI):

claude plugin install formatter@my-marketplace --scope project
claude plugin list --json
claude plugin details <name>          # inventory component + ước tính token cost
claude plugin enable/disable <plugin>
claude plugin update <plugin>
claude plugin uninstall <plugin> --prune   # gỡ kèm dependency mồ côi

/plugin mở panel tương tác với 4 tab: Discover, Installed, Marketplaces, Errors.

Version resolution — Claude Code lấy version từ, theo thứ tự: (1) version trong plugin.json, (2) version trong marketplace entry, (3) git commit SHA. Đặt version sẽ pin: phải bump mỗi lần phát hành, nếu không user không nhận thay đổi. Bỏ version (chỉ với source git) → mỗi commit là version mới, hợp cho plugin nội bộ/đang phát triển tích cực.

Auto-update: marketplace chính thức của Anthropic bật sẵn; third-party và local tắt mặc định (bật trong tab Marketplaces của /plugin).

Dependencies

Một plugin có thể phụ thuộc plugin khác qua mảng dependencies trong plugin.json (hoặc marketplace entry). Khi cài, Claude Code tự resolve và cài dependency.

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Entry là string (tên plugin, dùng version bất kỳ marketplace cung cấp) hoặc object với name (bắt buộc), version (semver range: ~2.1.0, ^2.0, >=1.4, =2.1.0), marketplace (marketplace khác — chỉ được phép nếu nằm trong allowCrossMarketplaceDependenciesOn của root marketplace).
Bundle: một manifest chỉ có name + dependencies là cách gói một bộ plugin curated sau một lần install (ví dụ backend-standard kéo về cả bộ tool cho backend).

Version constraint resolve theo git tag của repo marketplace, theo convention {plugin-name}--v{version}. Tag phát hành bằng:

claude plugin tag --push

Khi nhiều plugin ràng buộc cùng dependency, Claude Code giao (intersect) các range và chọn version cao nhất thỏa mãn tất cả. Không có version thỏa mãn → cài thất bại với range-conflict.

Enable/disable với dependency (cần v2.1.143+): enable một plugin cũng enable dependency của nó cùng scope; disable bị chặn nếu còn plugin enabled khác cần nó (error kèm lệnh chained để disable đúng thứ tự). Dọn dependency mồ côi: claude plugin prune (hoặc uninstall --prune).

Lỗi dependency thường gặp: dependency-unsatisfied (chưa cài/đang disabled), range-conflict (range không giao được), dependency-version-unsatisfied (version ngoài range), no-matching-tag (repo chưa tag đúng convention). Xem bằng claude plugin list --json (field errors).

Bảo mật và quản trị

Plugin và marketplace là highly trusted — chạy code tùy ý với quyền của user. Chỉ cài từ nguồn tin cậy. Anthropic không kiểm soát nội dung plugin third-party.
Marketplace-installed plugin được copy vào cache ~/.claude/plugins/cache (versioned). Vì thế path trỏ ra ngoài plugin root (../shared-utils) không hoạt động sau khi cài; chia sẻ file trong cùng marketplace bằng symlink.
Admin kiểm soát nguồn qua managed settings: strictKnownMarketplaces (allowlist hoặc [] để khóa hoàn toàn), extraKnownMarketplaces (đăng ký sẵn cho team), blockedMarketplaces, disableSideloadFlags. Một số tên marketplace được reserve cho Anthropic.
Container/CI: pre-populate bằng CLAUDE_CODE_PLUGIN_SEED_DIR (read-only, không clone lúc runtime). Tăng timeout git bằng CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS.

Xem thêm

content/en/docs/claude-code/plugins.md — hướng dẫn tạo plugin
content/en/docs/claude-code/plugins-reference.md — spec kỹ thuật đầy đủ (schema, CLI, component)
content/en/docs/claude-code/plugin-marketplaces.md — tạo và phân phối marketplace
content/en/docs/claude-code/plugin-dependencies.md — ràng buộc version dependency
content/en/docs/claude-code/discover-plugins.md — tìm và cài plugin có sẵn
content/en/docs/claude-code/skills.md, sub-agents.md, hooks.md, mcp.md — chi tiết từng loại component
content/en/docs/claude-code/settings.md — plugin settings, configuration scopes