Tham chiếu Plugin

Bài viết được dịch tự động từ bài viết gốc, chưa được kiểm tra lại bởi con người. Chỉ những bài viết có dấu tick xanh cạnh tiêu đề là đã được kiểm tra.

Trang này là tham chiếu kỹ thuật đầy đủ cho hệ thống plugin của Claude Code: schema từng component, lệnh CLI, và công cụ phát triển.

Một plugin là một thư mục tự chứa gồm các component mở rộng Claude Code với chức năng tùy chỉnh. Component của plugin gồm skill, agent, hook, MCP server, LSP server, và monitor.

Tham chiếu component của plugin

Skills

Plugin thêm skill vào Claude Code, tạo shortcut /name mà bạn hoặc Claude có thể gọi.

Vị trí: thư mục skills/ hoặc commands/ ở gốc plugin, hoặc một file SKILL.md duy nhất ở gốc plugin

Định dạng file: Skill là thư mục chứa SKILL.md; command là file markdown đơn giản

Cấu trúc skill:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

Hành vi tích hợp:

Skill và command được tự động phát hiện khi plugin được cài
Claude có thể gọi chúng tự động dựa trên ngữ cảnh tác vụ
Skill có thể kèm theo các file hỗ trợ bên cạnh SKILL.md

Nếu một plugin không có thư mục skills/ và không có field skills trong manifest, file SKILL.md ở gốc plugin được nạp như một skill đơn. Đặt field name trong frontmatter để kiểm soát tên gọi của skill. Nếu bỏ trống, Claude Code dùng tên thư mục cài đặt làm fallback - với plugin cài từ marketplace, đó là một chuỗi version thay đổi sau mỗi lần cập nhật. Với plugin có nhiều hơn một skill, dùng cấu trúc thư mục skills/ như trên.

Trong skill và command của plugin, các field frontmatter kiểu Boolean như disable-model-invocation chấp nhận yes, no, on, off, 1, 0 ở mọi kiểu chữ, ngoài true/false. Trước v2.1.218, Claude Code chỉ nhận true và false.

Chi tiết đầy đủ xem Skills.

Agents

Plugin có thể cung cấp subagent chuyên biệt cho các tác vụ cụ thể mà Claude có thể tự động gọi khi phù hợp.

Vị trí: thư mục agents/ ở gốc plugin

Định dạng file: file Markdown mô tả năng lực của agent

Cấu trúc agent:

---
name: agent-name
description: What this agent specializes in and when Claude should invoke it
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Detailed system prompt for the agent describing its role, expertise, and behavior.

Agent của plugin hỗ trợ các field frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, và isolation. Giá trị hợp lệ duy nhất cho isolation là "worktree". Vì lý do bảo mật, hooks, mcpServers, và permissionMode không được hỗ trợ cho agent do plugin cung cấp.

Điểm tích hợp:

Agent xuất hiện trong danh sách gợi ý @-mention dưới tên có scope, ví dụ my-plugin:code-reviewer, ngay khi plugin được bật
Claude có thể tự gọi agent dựa trên ngữ cảnh tác vụ
Người dùng có thể gọi agent thủ công
Agent của plugin hoạt động song song với agent built-in của Claude

Chi tiết đầy đủ xem Subagents.

Hooks

Plugin có thể cung cấp trình xử lý sự kiện phản ứng tự động với các sự kiện của Claude Code.

Vị trí: hooks/hooks.json ở gốc plugin, hoặc khai báo inline trong plugin.json

Định dạng: cấu hình JSON với matcher sự kiện và hành động

Cấu hình hook:

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

Hook của plugin phản ứng với cùng các sự kiện vòng đời như hook do người dùng định nghĩa:

Sự kiện	Khi nào xảy ra
`SessionStart`	Khi một phiên bắt đầu hoặc resume
`Setup`	Khi bạn khởi động Claude Code với `--init-only`, hoặc với `--init`/`--maintenance` trong chế độ `-p`. Dùng để chuẩn bị một lần trong CI hoặc script
`UserPromptSubmit`	Khi bạn submit một prompt, trước khi Claude xử lý
`UserPromptExpansion`	Khi một command do người dùng gõ mở rộng thành prompt, trước khi tới Claude. Có thể chặn việc mở rộng
`PreToolUse`	Trước khi một lệnh gọi tool thực thi. Có thể chặn nó
`PermissionRequest`	Khi một lệnh gọi tool cần quyết định về quyền
`PermissionDenied`	Khi một lệnh gọi tool bị auto mode classifier từ chối. Trả về `{retry: true}` để báo model có thể thử lại
`PostToolUse`	Sau khi một lệnh gọi tool thành công
`PostToolUseFailure`	Sau khi một lệnh gọi tool thất bại
`PostToolBatch`	Sau khi cả một batch lệnh gọi tool song song hoàn tất, trước lượt gọi model tiếp theo
`Notification`	Khi Claude Code gửi thông báo
`MessageDisplay`	Trong lúc nội dung message của assistant được hiển thị
`SubagentStart`	Khi một subagent được sinh ra
`SubagentStop`	Khi một subagent hoàn tất
`TaskCreated`	Khi một tác vụ được tạo qua `TaskCreate`
`TaskCompleted`	Khi một tác vụ được đánh dấu hoàn thành
`Stop`	Khi Claude hoàn tất phản hồi
`StopFailure`	Khi lượt hội thoại kết thúc do lỗi API. Output và exit code bị bỏ qua
`TeammateIdle`	Khi một teammate trong agent team sắp chuyển sang idle
`InstructionsLoaded`	Khi một file CLAUDE.md hoặc `.claude/rules/*.md` được nạp vào context. Xảy ra lúc bắt đầu phiên và khi file được nạp lazy trong phiên
`ConfigChange`	Khi một file cấu hình thay đổi trong phiên
`CwdChanged`	Khi thư mục làm việc thay đổi, ví dụ khi Claude thực thi lệnh `cd`. Hữu ích để quản lý môi trường phản ứng với công cụ như direnv
`FileChanged`	Khi một file được theo dõi thay đổi trên đĩa. Field `matcher` chỉ định tên file cần theo dõi
`WorktreeCreate`	Khi một worktree được tạo qua `--worktree`, `isolation: "worktree"`, hoặc cho một phiên background. Thay thế hành vi git mặc định
`WorktreeRemove`	Khi một worktree bị xóa lúc thoát phiên, khi một subagent hoàn tất, hoặc khi bạn xóa một phiên background
`PreCompact`	Trước khi nén context
`PostCompact`	Sau khi nén context hoàn tất
`Elicitation`	Khi một MCP server yêu cầu input từ người dùng trong lúc gọi tool
`ElicitationResult`	Sau khi người dùng phản hồi một MCP elicitation, trước khi phản hồi được gửi lại server
`SessionEnd`	Khi một phiên kết thúc

Các loại hook:

command: thực thi lệnh shell hoặc script
http: gửi JSON sự kiện dưới dạng POST request tới một URL
mcp_tool: gọi một tool trên MCP server đã cấu hình
prompt: đánh giá một prompt bằng LLM (dùng placeholder $ARGUMENTS cho ngữ cảnh)
agent: chạy một agentic verifier với tool cho các tác vụ xác minh phức tạp

Hook nhắm vào MCP server đi kèm của chính plugin phải dùng tên có scope. Matcher tool và field if dùng tên tool có scope mcp__plugin_<plugin-name>_<server-name>__<tool>, và field server của hook mcp_tool dùng plugin:<plugin-name>:<server-name>. Matcher viết theo tên server trần không bao giờ khớp. Xem Khớp MCP tool và MCP server do plugin cung cấp.

MCP servers

Plugin có thể đóng gói MCP server (Model Context Protocol) để kết nối Claude Code với công cụ và dịch vụ bên ngoài.

Vị trí: .mcp.json ở gốc plugin, hoặc inline trong plugin.json

Định dạng: cấu hình MCP server chuẩn

Cấu hình MCP server:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"]
    }
  }
}

Hành vi tích hợp:

MCP server của plugin tự khởi động khi plugin được bật
Server xuất hiện như tool MCP chuẩn trong bộ công cụ của Claude
Năng lực của server tích hợp liền mạch với tool có sẵn của Claude
Server của plugin có thể cấu hình độc lập với MCP server của người dùng
Nếu bạn chạy /reload-plugins giữa phiên, Claude Code giữ nguyên kết nối sống của các server mà cấu hình không đổi

LSP servers

Plugin có thể cung cấp Language Server Protocol (LSP) server để Claude có code intelligence thời gian thực khi làm việc trên codebase của bạn.

Tích hợp LSP mang lại:

Chẩn đoán tức thì: Claude thấy lỗi và cảnh báo ngay sau mỗi lần chỉnh sửa
Điều hướng code: nhảy tới định nghĩa, tìm tham chiếu, và thông tin hover
Nhận biết ngôn ngữ: thông tin kiểu và tài liệu cho các ký hiệu code

Vị trí: .lsp.json ở gốc plugin, hoặc inline trong plugin.json

Định dạng: cấu hình JSON ánh xạ tên language server tới cấu hình của nó

Định dạng file .lsp.json:

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

Inline trong plugin.json:

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

Field bắt buộc:

Field	Mô tả
`command`	Binary LSP cần thực thi (phải có trong PATH)
`extensionToLanguage`	Ánh xạ đuôi file tới định danh ngôn ngữ

Field tùy chọn:

Field	Mô tả
`args`	Tham số dòng lệnh cho LSP server
`transport`	Giao thức truyền tải: `stdio` (mặc định) hoặc `socket`
`env`	Biến môi trường khi khởi động server
`initializationOptions`	Tùy chọn truyền cho server lúc khởi tạo
`settings`	Cài đặt truyền qua `workspace/didChangeConfiguration`
`workspaceFolder`	Đường dẫn workspace folder cho server
`startupTimeout`	Thời gian chờ tối đa khi server khởi động (mili-giây)
`shutdownTimeout`	Thời gian chờ tối đa để tắt êm (mili-giây). Khi hết thời gian, Claude Code kết thúc tiến trình server. Nếu không đặt, không có timeout
`restartOnCrash`	Có khởi động lại server sau khi crash hay không. Mặc định `true`. Đặt `false` để server crash thì dừng luôn thay vì tự khởi động lại
`maxRestarts`	Số lần thử khởi động lại tối đa trước khi bỏ cuộc
`diagnostics`	Có đẩy chẩn đoán vào context của Claude sau mỗi lần sửa hay không (mặc định `true`). Đặt `false` để giữ điều hướng code nhưng tắt việc tự động đẩy chẩn đoán

restartOnCrash và shutdownTimeout yêu cầu Claude Code v2.1.205 trở lên. Trước v2.1.205, schema cấu hình vẫn chấp nhận cả hai tùy chọn nhưng đặt bất kỳ cái nào cũng khiến Claude Code bỏ qua hoàn toàn LSP server đó lúc khởi động, lý do chỉ hiện trong output claude --debug.

Nhiều server cho cùng một đuôi file: khi nhiều hơn một LSP server đang bật khai báo cùng đuôi file trong extensionToLanguage, dù đến từ cùng một plugin hay khác plugin, server đăng ký đầu tiên xử lý file có đuôi đó, các server còn lại không bao giờ khởi động. Giao diện /plugin hiện cảnh báo nêu tên plugin có server đang hoạt động.

Server khởi tạo lỗi: Claude Code bỏ qua server có cấu hình không hợp lệ, ví dụ thiếu command hoặc extensionToLanguage, và các server khác vẫn khởi động bình thường. Chạy claude --debug để xem lý do server bị bỏ qua.

Một server bị bỏ qua không “giữ” đuôi file của nó, nên một server hợp lệ khác khai báo cùng đuôi, dù từ cùng plugin hay plugin khác, vẫn xử lý được các file đó. Trước v2.1.205, một server khởi tạo lỗi vẫn giữ đuôi file của nó và chặn một server hợp lệ khác cùng đuôi.

Plugin LSP có sẵn:

Plugin	Language server	Lệnh cài
`pyright-lsp`	Pyright (Python)	`pip install pyright` hoặc `npm install -g pyright`
`typescript-lsp`	TypeScript Language Server	`npm install -g typescript-language-server typescript`
`rust-analyzer-lsp`	rust-analyzer	Xem hướng dẫn cài rust-analyzer

Cài language server trước, rồi mới cài plugin từ marketplace.

Monitors

Plugin có thể khai báo monitor chạy nền mà Claude Code tự khởi động khi plugin đang hoạt động. Mỗi monitor chạy một lệnh shell suốt vòng đời phiên và đưa từng dòng stdout về cho Claude dưới dạng thông báo, để Claude phản ứng với log, thay đổi trạng thái, hoặc sự kiện polling mà không cần được yêu cầu bắt đầu theo dõi.

Monitor của plugin dùng cùng cơ chế với tool Monitor và chia sẻ các ràng buộc về khả năng dùng. Chúng chỉ chạy trong phiên CLI tương tác, chạy không sandbox ở cùng mức tin cậy với hook, và bị bỏ qua trên các host không hỗ trợ tool Monitor.

Vị trí: monitors/monitors.json ở gốc plugin, hoặc inline trong plugin.json

Định dạng: mảng JSON gồm các entry monitor

monitors/monitors.json sau theo dõi một endpoint trạng thái deploy và một file log lỗi cục bộ:

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Deployment status changes"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log",
    "when": "on-skill-invoke:debug"
  }
]

Để khai báo monitor inline, đặt experimental.monitors trong plugin.json bằng cùng mảng đó. Để nạp từ đường dẫn không mặc định, đặt experimental.monitors thành một chuỗi đường dẫn tương đối như "./config/monitors.json". Monitor là một component thử nghiệm.

Field bắt buộc:

Field	Mô tả
`name`	Định danh duy nhất trong plugin. Tránh trùng tiến trình khi plugin reload hoặc một skill được gọi lại
`command`	Lệnh shell chạy như tiến trình nền thường trực, trong thư mục làm việc của phiên
`description`	Tóm tắt ngắn về thứ đang được theo dõi. Hiện trong task panel và trong tóm tắt thông báo

Field tùy chọn:

Field	Mô tả
`when`	Kiểm soát khi nào monitor khởi động. `"always"` khởi động lúc bắt đầu phiên và khi plugin reload, và là mặc định. `"on-skill-invoke:<skill-name>"` khởi động lần đầu tiên skill được nêu tên trong plugin này được dispatch

Giá trị command hỗ trợ các thay thế đường dẫn ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, và ${CLAUDE_PROJECT_DIR}, cộng thêm bất kỳ ${ENV_VAR} nào từ môi trường. Thêm tiền tố cd "${CLAUDE_PLUGIN_ROOT}" && nếu script cần chạy từ chính thư mục của plugin.

Một command của monitor không thể tham chiếu giá trị ${user_config.*}. Lệnh chạy qua shell, nên Claude Code từ chối monitor đó với một lỗi thay vì thay thế giá trị. Tiến trình monitor không nhận biến môi trường CLAUDE_PLUGIN_OPTION_<KEY>, nên hãy để script monitor đọc giá trị từ một file cấu hình mà nó tự sở hữu. Trước v2.1.207, lệnh monitor có thay thế giá trị ${user_config.*}.

Nếu bạn tắt một plugin giữa phiên, Claude Code không dừng các monitor đang chạy; chúng dừng khi phiên kết thúc.

Themes

Plugin có thể đóng gói theme màu xuất hiện trong /theme cùng với preset built-in và theme cục bộ của người dùng. Một theme là file JSON trong themes/ với một preset base và một map overrides thưa các token màu. Theme là một component thử nghiệm.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Khi người dùng chọn một theme của plugin, Claude Code lưu custom:<plugin-name>:<slug> vào cấu hình của họ. Theme của plugin là chỉ đọc: khi người dùng nhấn Ctrl+E trên một theme trong /theme, Claude Code sao chép nó vào ~/.claude/themes/ để họ chỉnh sửa bản sao.

Phạm vi cài đặt plugin

Khi cài một plugin, bạn chọn một scope quyết định plugin có sẵn ở đâu và ai khác dùng được:

Scope	File settings	Trường hợp dùng
`user`	`~/.claude/settings.json`	Plugin cá nhân, dùng được ở mọi project (mặc định)
`project`	`.claude/settings.json`	Plugin nhóm, chia sẻ qua version control
`local`	`.claude/settings.local.json`	Plugin riêng cho project, bị gitignore khi Claude Code lưu một setting vào đó
`managed`	Managed settings	Plugin do tổ chức quản lý (chỉ đọc, chỉ update)

Plugin dùng chung hệ thống scope với các cấu hình khác của Claude Code. Hướng dẫn cài đặt và flag scope xem Cài plugin. Giải thích đầy đủ về scope xem Configuration scopes.

Plugin từ skills-directory

Bất kỳ thư mục con nào trong một skills directory chứa manifest .claude-plugin/plugin.json được nạp như một plugin tên <name>@skills-dir ở phiên kế tiếp, không cần marketplace, không cần bước cài đặt. Scaffold một plugin như vậy bằng plugin init. Khác với cài từ marketplace, plugin này được phát hiện tại chỗ thay vì được sao chép vào plugin cache.

Một cây skills directory hỗ trợ ba thứ khác nhau:

Bạn có	Đó là gì
`<skills-dir>/foo/SKILL.md` không có manifest	Một skill thuần tên `foo`
`<skills-dir>/foo/.claude-plugin/plugin.json`	Một plugin `foo@skills-dir`, có thể đóng gói skill, agent, hook riêng và nhiều hơn
`<plugin>/skills/bar/SKILL.md`	Một skill `bar` đóng gói bên trong một plugin

Chọn nơi plugin được nạp

Skills directory	Scope	Nạp
`~/.claude/skills/`	personal	Ở mọi project, vì vị trí này chỉ thuộc về bạn
`<cwd>/.claude/skills/`	project	Chỉ sau khi bạn chấp nhận hộp thoại trust cho thư mục đó

Một plugin scope project được checkin vào repository và tới được mọi người clone nó. Vì nội dung đó tới từ repository chứ không phải từ bạn, nó chỉ nạp sau cùng cổng trust quản lý .claude/settings.json, và các component chạy code bị giới hạn thêm:

MCP server nó khai báo đi qua cùng bước phê duyệt theo từng server như một .mcp.json project
LSP server chỉ khởi động sau khi bạn trust workspace
Monitor nền không được nạp

Plugin scope personal không có các giới hạn này.

Sửa, reload, và tắt một plugin skills-directory

Thay đổi trong SKILL.md của một skill có hiệu lực ngay trong phiên hiện tại. Thay đổi ở các component khác của plugin, như hooks/, .mcp.json, agents/, và output-styles/, thì không. Chạy /reload-plugins hoặc khởi động lại Claude Code để áp dụng. Xem Phát hiện thay đổi trực tiếp.

Để ngừng nạp một plugin skills-directory, xóa thư mục của nó hoặc tắt theo tên. Không có bước uninstall vì không có gì được cài từ marketplace cả.

claude plugin disable my-tool@skills-dir

Schema manifest của plugin

File .claude-plugin/plugin.json định nghĩa metadata và cấu hình của plugin. Phần này ghi lại toàn bộ field và tùy chọn được hỗ trợ.

Manifest là tùy chọn. Nếu bỏ trống, Claude Code tự phát hiện component ở các vị trí mặc định và suy ra tên plugin từ tên thư mục. Dùng manifest khi bạn cần cung cấp metadata hoặc đường dẫn component tùy chỉnh.

Schema đầy đủ

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "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",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

Field bắt buộc

Nếu bạn có manifest, name là field bắt buộc duy nhất.

Field	Kiểu	Mô tả	Ví dụ
`name`	string	Định danh duy nhất (kebab-case, không dấu cách). Khi một entry marketplace liệt kê plugin dưới tên khác, tên entry marketplace mới là thứ `enabledPlugins` và `/plugin` dùng làm khóa	`"deployment-tools"`

Tên này dùng để namespace các component. Ví dụ, trong UI, agent agent-creator của plugin tên plugin-dev sẽ hiện thành plugin-dev:agent-creator.

Field không nhận diện được

Claude Code bỏ qua các field cấp cao nhất mà nó không nhận diện. Bạn có thể giữ metadata từ hệ sinh thái khác trong plugin.json và plugin vẫn nạp bình thường. Điều này giúp bạn duy trì một manifest kiêm luôn manifest extension của VS Code hay Cursor, package.json của npm, hoặc manifest bundle MCPB/DXT.

claude plugin validate báo field không nhận diện là warning, không phải error. Nếu một field sai lệch một hoặc hai ký tự so với tên nhận diện được, warning gợi ý tên đúng có khả năng cao. Một plugin chỉ có warning về field không nhận diện vẫn pass validation và vẫn nạp lúc runtime.

Field sai kiểu dữ liệu thì vẫn lỗi. Ví dụ, keywords là string thay vì array là một lỗi nạp, và claude plugin validate báo nó là lỗi.

Truyền --strict để coi warning là error. Dùng trong CI để bắt lỗi đánh máy tên field hoặc field sót lại từ manifest công cụ khác trước khi publish, dù plugin vẫn nạp được lúc runtime.

claude plugin validate ./my-plugin --strict

Field metadata

Field	Kiểu	Mô tả	Ví dụ
`$schema`	string	URL JSON Schema cho autocomplete và validate trong editor. Claude Code bỏ qua field này lúc nạp	`"https://json.schemastore.org/claude-code-plugin-manifest.json"`
`displayName`	string	Tên dễ đọc hiện trong picker `/plugin` và các UI khác. Fallback về `name` nếu bỏ trống. Khác `name`, có thể chứa dấu cách và mọi kiểu chữ. Không dùng để namespace hay tra cứu. Yêu cầu Claude Code v2.1.143 trở lên	`"Deployment Tools"`
`version`	string	Tùy chọn. Semantic version. Đặt field này ghim plugin vào chuỗi version đó, người dùng chỉ nhận update khi bạn tăng nó. Nếu bỏ trống, Claude Code dùng git commit SHA, nên mỗi commit được coi là một version mới. Nếu cũng đặt trong entry marketplace, `plugin.json` thắng. Xem Quản lý version	`"2.1.0"`
`description`	string	Giải thích ngắn về mục đích của plugin	`"Deployment automation tools"`
`author`	object	Thông tin tác giả	`{"name": "Dev Team", "email": "dev@company.com"}`
`homepage`	string	URL tài liệu	`"https://docs.example.com"`
`repository`	string	URL source code	`"https://github.com/user/plugin"`
`license`	string	Định danh giấy phép	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Tag để khám phá	`["deployment", "ci-cd"]`
`defaultEnabled`	boolean	Plugin có khởi động ở trạng thái bật khi người dùng chưa đặt gì hay không. Mặc định `true`. Xem Trạng thái bật mặc định. Yêu cầu Claude Code v2.1.154 trở lên	`false`

Trạng thái bật mặc định

Đặt defaultEnabled: false trong plugin.json để phát hành một plugin cài xong ở trạng thái tắt. Người dùng tự bật bằng claude plugin enable <plugin> hoặc giao diện /plugin. Dùng cho các plugin tốn chi phí hoặc phạm vi mà người dùng nên tự chọn tham gia, ví dụ plugin kết nối tới dịch vụ ngoài. Yêu cầu Claude Code v2.1.154 trở lên. Phiên bản trước bỏ qua field này và bật plugin ngay khi cài.

defaultEnabled là fallback khi không có gì khác đã quyết định trạng thái của plugin. Hai thứ sau ưu tiên hơn nó:

Setting của người dùng: một entry cho plugin trong enabledPlugins ở bất kỳ scope settings nào. Một khi đã ghi, nó tồn tại qua các lần plugin update và cài lại, nên đổi defaultEnabled ở bản phát hành sau không ảnh hưởng người dùng hiện có.
Yêu cầu dependency: khi một plugin được yêu cầu bởi một plugin khác đang active, Claude Code ghi true cho nó lúc cài hoặc bật. Điều đó tạo ra một setting rõ ràng, nên default của chính nó không còn áp dụng. Xem Bật hoặc tắt một plugin có dependency.

Field tương tự có thể xuất hiện trong entry marketplace của một plugin, ở đó nó ưu tiên hơn giá trị trong plugin.json. Xem Field plugin tùy chọn.

Field đường dẫn component

Field	Kiểu	Mô tả	Ví dụ
`skills`	string\|array	Thư mục skill tùy chỉnh chứa `<name>/SKILL.md`. Bổ sung thêm vào scan mặc định `skills/`. Xem Quy tắc hành vi đường dẫn cho ngoại lệ marketplace-root	`"./custom/skills/"`
`commands`	string\|array	File `.md` skill dạng phẳng hoặc thư mục tùy chỉnh (thay thế `commands/` mặc định)	`"./custom/cmd.md"` hoặc `["./cmd1.md"]`
`agents`	string\|array	File agent tùy chỉnh (thay thế `agents/` mặc định)	`"./custom/agents/reviewer.md"`
`workflows`	string\|array	File script hoặc thư mục workflow tùy chỉnh (thay thế `workflows/` mặc định)	`"./custom/workflows/"`
`hooks`	string\|array\|object	Đường dẫn cấu hình hook hoặc cấu hình inline	`"./my-extra-hooks.json"`
`mcpServers`	string\|array\|object	Đường dẫn cấu hình MCP hoặc cấu hình inline	`"./my-extra-mcp-config.json"`
`outputStyles`	string\|array	File/thư mục output style tùy chỉnh (thay thế `output-styles/` mặc định)	`"./styles/"`
`lspServers`	string\|array\|object	Cấu hình Language Server Protocol cho code intelligence (nhảy tới định nghĩa, tìm tham chiếu, v.v.)	`"./.lsp.json"`
`experimental.themes`	string\|array	File theme màu (thay thế `themes/` mặc định). Xem Themes	`"./themes/"`
`experimental.monitors`	string\|array	Cấu hình Monitor nền tự khởi động khi plugin active. Xem Monitors	`"./monitors.json"`
`userConfig`	object	Giá trị do người dùng cấu hình, hỏi lúc bật plugin. Xem Cấu hình người dùng	Xem bên dưới
`channels`	array	Khai báo channel để bơm message (kiểu Telegram, Slack, Discord). Xem Channels	Xem bên dưới
`dependencies`	array	Plugin khác mà plugin này cần, có thể kèm ràng buộc semver. Xem Ràng buộc version dependency của plugin	`[{ "name": "secrets-vault", "version": "~2.1.0" }]`

Component thử nghiệm

Các component dưới key experimental - themes và monitors - có schema manifest có thể thay đổi giữa các bản phát hành khi chúng còn đang ổn định dần. Nơi bạn khai báo chúng là một cuộc di trú riêng: cấp cao nhất vẫn hoạt động, claude plugin validate cảnh báo, và một bản phát hành tương lai sẽ yêu cầu experimental.*.

Cấu hình người dùng

Field userConfig khai báo các giá trị Claude Code hỏi người dùng khi plugin được bật. Dùng cái này thay vì bắt người dùng tự sửa tay settings.json.

{
  "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
    }
  }
}

Key phải là định danh hợp lệ. Mỗi option hỗ trợ các field:

Field	Bắt buộc	Mô tả
`type`	Có	Một trong `string`, `number`, `boolean`, `directory`, hoặc `file`
`title`	Có	Nhãn hiện trong hộp thoại cấu hình
`description`	Có	Văn bản trợ giúp hiện bên dưới field
`sensitive`	Không	Nếu `true`, che input và lưu giá trị vào secure storage thay vì `settings.json`
`required`	Không	Nếu `true`, validate thất bại khi field trống
`default`	Không	Giá trị dùng khi người dùng không nhập gì
`multiple`	Không	Với kiểu `string`, cho phép một mảng chuỗi
`min` / `max`	Không	Giới hạn cho kiểu `number`

Mỗi giá trị có thể được thay thế dưới dạng ${user_config.KEY} trong cấu hình MCP, LSP server, và lệnh hook. Giá trị không sensitive cũng có thể thay thế trong nội dung skill và agent. Mọi giá trị được export tới tiến trình hook dưới dạng biến môi trường CLAUDE_PLUGIN_OPTION_<KEY>, với <KEY> là tên option viết hoa.

Các field chạy trong shell từ chối ${user_config.*}: thay giá trị đã cấu hình vào một lệnh shell sẽ cho phép shell chạy bất cứ gì giá trị đó chứa, nên component đó lỗi với một error thay vì thay thế. Mỗi field bị từ chối có một cách thay thế khác để truyền giá trị:

Field bị từ chối	Cách truyền giá trị
Lệnh hook dạng shell-form	Dùng exec form với `args`, hoặc đọc `CLAUDE_PLUGIN_OPTION_<KEY>` từ môi trường của hook
Lệnh Monitor	Đọc giá trị từ một file cấu hình trong script
MCP `headersHelper`	Đọc giá trị từ một file cấu hình trong script

Trước v2.1.207, các field này có thay thế giá trị ${user_config.KEY}; hãy cập nhật plugin dựa vào hành vi cũ này.

Giá trị không sensitive được lưu dưới key pluginConfigs trong settings.json người dùng, ở dạng pluginConfigs[<plugin-id>].options.

Giá trị sensitive đi vào macOS Keychain, hoặc ~/.claude/.credentials.json trên nền tảng không có keychain hỗ trợ. Keychain storage dùng chung với OAuth token và có giới hạn tổng khoảng 2 KB, nên giữ giá trị sensitive nhỏ gọn.

Claude Code chỉ đọc giá trị pluginConfigs từ ba nguồn settings:

User settings: ~/.claude/settings.json, file mà prompt lúc bật ghi vào
--settings: flag CLI hoặc settings inline của SDK
Managed settings: chính sách do tổ chức kiểm soát

Khi nhiều nguồn cùng đặt một key, managed settings thắng trước, rồi tới --settings, rồi tới user settings. Flag --setting-sources thu hẹp danh sách này thêm.

Entry trong .claude/settings.json hoặc .claude/settings.local.json của một project bị bỏ qua. Cả hai file này nằm trong workspace, nên một repository được clone có thể cung cấp giá trị ở đó, và những giá trị đó sẽ chảy vào lệnh hook, cấu hình MCP server, lệnh LSP, và lệnh monitor của plugin. Trước v2.1.207, các entry này được đọc. Giới hạn này chỉ áp dụng riêng cho pluginConfigs: enabledPlugins vẫn tôn trọng project và local settings.

Channels

Field channels cho phép một plugin khai báo một hoặc nhiều message channel bơm nội dung vào cuộc hội thoại. Mỗi channel gắn với một MCP server mà plugin cung cấp.

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Your Telegram user ID"
        }
      }
    }
  ]
}

Field server bắt buộc và phải khớp một key trong mcpServers của plugin. userConfig theo từng channel là tùy chọn, dùng cùng schema với field cấp cao nhất, cho phép plugin hỏi bot token hay owner ID khi plugin được bật.

Quy tắc hành vi đường dẫn

Một đường dẫn tùy chỉnh thay thế hay bổ sung thư mục mặc định của plugin tùy vào field:

Thay thế mặc định: commands, agents, workflows, outputStyles, experimental.themes, experimental.monitors. Ví dụ, khi manifest chỉ định commands, thư mục commands/ mặc định không được scan nữa. Để giữ mặc định và thêm nữa, liệt kê rõ ràng: "commands": ["./commands/", "./extras/"]
Bổ sung vào mặc định: skills. Thư mục skills/ mặc định luôn được scan, và các thư mục liệt kê trong skills được nạp thêm cùng với nó. Ngoại lệ: với một entry marketplace mà source trỏ về gốc marketplace, khai báo thư mục con cụ thể sẽ thay thế scan skills/ mặc định
Quy tắc merge riêng: hooks, MCP servers, và LSP servers. Xem từng phần để biết cách nhiều nguồn kết hợp

Khi một plugin có cả thư mục mặc định lẫn key manifest tương ứng, Claude Code v2.1.140 trở lên cảnh báo về thư mục bị bỏ qua trong claude plugin list và view chi tiết /plugin. Plugin vẫn nạp dùng đường dẫn từ manifest. Claude Code không cảnh báo khi key manifest trỏ vào chính thư mục mặc định, ví dụ "commands": ["./commands/deploy.md"], vì đường dẫn đó nêu tên thư mục rõ ràng.

Với mọi field đường dẫn:

Mọi đường dẫn phải tương đối so với gốc plugin và bắt đầu bằng ./
Component từ đường dẫn tùy chỉnh dùng cùng quy tắc đặt tên và namespace
Có thể chỉ định nhiều đường dẫn dưới dạng mảng
Khi một đường dẫn skill trỏ tới một thư mục chứa SKILL.md trực tiếp, ví dụ "skills": ["./"] trỏ về gốc plugin, field name trong frontmatter của SKILL.md quyết định tên gọi của skill. Điều này cho tên ổn định bất kể thư mục cài đặt. Nếu name không được đặt trong frontmatter, tên thư mục (basename) được dùng làm fallback

Một plugin có SKILL.md ở gốc, không có thư mục con skills/, và không có field skills trong manifest được tự động nạp như một plugin skill-đơn trong Claude Code v2.1.142 trở lên. Bạn không cần đặt "skills": ["./"] trong plugin.json cho cấu trúc này. Tên gọi của skill theo cùng quy tắc trên: field name trong frontmatter, hoặc tên thư mục làm fallback.

Ví dụ đường dẫn:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Biến môi trường

Claude Code cung cấp ba biến để tham chiếu đường dẫn:

Biến	Trỏ tới	Dùng cho
`${CLAUDE_PLUGIN_ROOT}`	Đường dẫn tuyệt đối tới thư mục cài đặt của plugin	Script, binary, và file config đóng gói cùng plugin
`${CLAUDE_PLUGIN_DATA}`	Thư mục thường trực tồn tại qua các lần plugin update, được tạo lúc tham chiếu lần đầu	Dependency đã cài như `node_modules` hay Python virtual environment, code sinh ra, và cache
`${CLAUDE_PROJECT_DIR}`	Gốc project	Script và file config cục bộ của project

Cả ba đều được export thành biến môi trường cho tiến trình hook và tiến trình con MCP/LSP server. Field nào thay thế inline phụ thuộc vào component plugin:

Component plugin	Field nơi placeholder được thay thế
Nội dung skill và agent	Bất kỳ đâu placeholder xuất hiện
Lệnh hook và monitor	Bất kỳ đâu placeholder xuất hiện
MCP server `stdio`	`command`, `args`, `env`
MCP server `http`, `sse`, `ws`	`url`, `headers`, `headersHelper`
LSP server	`command`, `args`, `env`, `workspaceFolder`

Trong lệnh hook, dùng exec form với args để mỗi đường dẫn được truyền như một tham số riêng, không cần escape. Trong hook shell-form và lệnh monitor, bọc biến trong dấu ngoặc kép, như "${CLAUDE_PROJECT_DIR}/scripts/server.sh". Hook shell-form sau chạy một script đóng gói cùng plugin:

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

${CLAUDE_PLUGIN_ROOT} đổi khi plugin update. Thư mục của version trước vẫn còn trên đĩa khoảng hai tuần sau khi update trước khi bị dọn dẹp, nhưng hãy coi nó là tạm thời và đừng ghi state vào đó.

Khi một plugin update giữa phiên, lệnh hook, monitor, MCP server, và LSP server vẫn dùng đường dẫn của version trước. Chạy /reload-plugins để chuyển hook, MCP server, và LSP server sang đường dẫn mới; monitor cần khởi động lại phiên.

MCP server cũng có thể gọi request roots/list để đọc thư mục làm việc của phiên lúc runtime. Xem roots/list trả về gì và khi nào Claude Code báo server về thay đổi.

Thư mục dữ liệu thường trực

Thư mục ${CLAUDE_PLUGIN_DATA} trỏ tới ~/.claude/plugins/data/{id}/, với {id} là định danh plugin, các ký tự ngoài a-z, A-Z, 0-9, _, - được thay bằng -. Với một plugin cài dưới tên formatter@my-marketplace, thư mục là ~/.claude/plugins/data/formatter-my-marketplace/.

Một cách dùng phổ biến là cài dependency ngôn ngữ một lần và tái sử dụng qua các phiên và các lần plugin update. Vì thư mục dữ liệu tồn tại lâu hơn bất kỳ version plugin nào, chỉ kiểm tra thư mục có tồn tại hay không thì không đủ để phát hiện lúc một update đổi dependency manifest. Cách khuyến nghị là so sánh manifest đóng gói với bản sao trong thư mục dữ liệu và cài lại khi chúng khác nhau.

Hook SessionStart sau cài node_modules ở lần chạy đầu và cài lại mỗi khi một plugin update kèm package.json thay đổi:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

Lệnh diff thoát khác 0 khi bản lưu bị thiếu hoặc khác bản đóng gói, bao phủ cả lần chạy đầu và các update đổi dependency. Nếu npm install thất bại, lệnh rm cuối xóa manifest đã sao chép để phiên tiếp theo thử lại.

Script đóng gói trong ${CLAUDE_PLUGIN_ROOT} sau đó có thể chạy dựa vào node_modules đã lưu thường trực:

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

Thư mục dữ liệu bị tự động xóa khi bạn gỡ plugin khỏi scope cuối cùng còn cài nó. Giao diện /plugin hiện dung lượng thư mục và hỏi trước khi xóa. CLI xóa mặc định; truyền --keep-data để giữ lại.

Cache và phân giải file của plugin

Plugin được chỉ định theo một trong hai cách:

Qua claude --plugin-dir hoặc claude --plugin-url, chỉ trong thời gian phiên.
Qua một marketplace, cài cho các phiên sau.

Vì lý do bảo mật và xác minh, Claude Code sao chép plugin từ marketplace vào plugin cache cục bộ của người dùng (~/.claude/plugins/cache) thay vì dùng tại chỗ. Hiểu hành vi này quan trọng khi phát triển plugin tham chiếu file bên ngoài.

Mỗi version cài đặt là một thư mục riêng trong cache. Khi bạn update hoặc gỡ một plugin, thư mục version trước bị đánh dấu mồ côi (orphaned) và tự động xóa sau 14 ngày. Thời gian ân hạn này cho phép các phiên Claude Code đang chạy song song đã nạp version cũ tiếp tục chạy không lỗi.

Tool Glob và Grep của Claude bỏ qua thư mục version mồ côi khi tìm kiếm, nên kết quả file không chứa code plugin đã lỗi thời.

Giới hạn path traversal

Plugin đã cài không thể tham chiếu file ngoài thư mục của nó. Đường dẫn đi ra ngoài gốc plugin (như ../shared-utils) sẽ không hoạt động sau khi cài vì các file bên ngoài đó không được sao chép vào cache.

Chia sẻ file trong một marketplace bằng symlink

Nếu plugin của bạn cần chia sẻ file với phần khác của cùng marketplace, bạn có thể tạo symbolic link bên trong thư mục plugin. Cách một symlink được xử lý khi plugin được sao chép vào cache phụ thuộc vào nơi target của nó trỏ tới:

Trong chính thư mục của plugin: symlink được giữ nguyên dạng symlink tương đối trong cache, nên nó vẫn trỏ đúng tới target đã sao chép lúc runtime.
Nơi khác trong cùng marketplace: symlink bị dereference. Nội dung của target được sao chép vào cache thay cho nó. Điều này cho phép thư mục skills/ của một meta-plugin link tới skill do plugin khác trong marketplace định nghĩa.
Ngoài marketplace: symlink bị bỏ qua vì lý do bảo mật. Điều này ngăn plugin kéo các file host tùy ý, như đường dẫn hệ thống, vào cache.

Với plugin cài bằng --plugin-dir hoặc từ đường dẫn cục bộ, chỉ symlink trỏ tới nơi nằm trong chính thư mục plugin được giữ lại. Các symlink khác bị bỏ qua.

Lệnh sau tạo một link từ bên trong một plugin marketplace tới một skill chia sẻ do plugin anh em định nghĩa. Trên Windows, dùng mklink /D từ Command Prompt chạy quyền admin hoặc bật Developer Mode:

ln -s ../../shared-plugin/skills/foo ./skills/foo

Cách này vừa linh hoạt vừa giữ được lợi ích bảo mật của hệ thống cache.

Cấu trúc thư mục plugin

Bố cục plugin chuẩn

Một plugin đầy đủ có cấu trúc:

enterprise-plugin/
├── .claude-plugin/           # Metadata directory (optional)
│   └── plugin.json             # plugin manifest
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills as flat .md files
│   ├── status.md
│   └── logs.md
├── agents/                   # Subagent definitions
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── workflows/                # Workflow scripts
│   └── release-audit.js
├── output-styles/            # Output style definitions
│   └── terse.md
├── themes/                   # Color theme definitions
│   └── dracula.json
├── monitors/                 # Background monitor configurations
│   └── monitors.json
├── hooks/                    # Hook configurations
│   ├── hooks.json           # Main hook config
│   └── security-hooks.json  # Additional hooks
├── bin/                      # Plugin executables added to PATH
│   └── my-tool               # Invokable as bare command in Bash tool
├── settings.json            # Default settings for the plugin
├── .mcp.json                # MCP server definitions
├── .lsp.json                # LSP server configurations
├── scripts/                 # Hook and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # License file
└── CHANGELOG.md             # Version history

File CLAUDE.md ở gốc plugin không được nạp làm project context. Plugin đóng góp context qua skill, agent, và hook chứ không phải CLAUDE.md. Để đưa hướng dẫn vào context của Claude, đặt nó trong một skill.

Tham chiếu vị trí file

Component	Vị trí mặc định	Mục đích
Manifest	`.claude-plugin/plugin.json`	Metadata và cấu hình plugin (tùy chọn)
Skills	`skills/`	Skill với cấu trúc `<name>/SKILL.md`
Commands	`commands/`	Skill dạng file Markdown phẳng. Dùng `skills/` cho plugin mới
Agents	`agents/`	File Markdown subagent
Workflows	`workflows/`	File script workflow
Output styles	`output-styles/`	Định nghĩa output style
Themes	`themes/`	Định nghĩa theme màu
Hooks	`hooks/hooks.json`	Cấu hình hook
MCP servers	`.mcp.json`	Định nghĩa MCP server
LSP servers	`.lsp.json`	Cấu hình language server
Monitors	`monitors/monitors.json`	Cấu hình monitor nền
Executables	`bin/`	File thực thi được thêm vào `PATH` của tool Bash. File ở đây gọi được như lệnh trần trong bất kỳ lệnh gọi tool Bash nào khi plugin đang bật
Settings	`settings.json`	Cấu hình mặc định áp dụng khi plugin được bật. Hiện chỉ hỗ trợ key `agent` và `subagentStatusLine`

Tham chiếu lệnh CLI

Claude Code cung cấp lệnh CLI để quản lý plugin không tương tác, hữu ích cho scripting và tự động hóa.

plugin init

Scaffold một plugin mới tại ~/.claude/skills/<name>/. Ở phiên Claude Code kế tiếp, nó tự nạp thành <name>@skills-dir và xuất hiện trong /plugin và claude plugin list mà không cần bước cài đặt.

Xem Plugin từ skills-directory về yêu cầu scope và trust.

claude plugin init <name> [options]

Tham số:

<name>: Tên plugin. Trở thành namespace skill và tên thư mục dưới ~/.claude/skills/, nên không được chứa dấu cách hoặc ký tự phân tách đường dẫn.

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`--description <text>`	Mô tả trong manifest
`--author <name>`	Tên tác giả	`git config user.name`
`--author-email <email>`	Email tác giả	`git config user.email`
`--with <components...>`	Scaffold thêm thư mục component. Giá trị hợp lệ: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel`
`-f, --force`	Ghi đè `.claude-plugin/` đã có tại đích
`-h, --help`	Hiện trợ giúp lệnh

Alias: new

Mỗi giá trị --with thêm một file khởi đầu cho component đó, sẵn sàng để sửa:

Component	Scaffold gì
`skills`	Một skill có namespace `<name>:example` thêm bên cạnh skill mặc định
`agents`	Một định nghĩa subagent trong `agents/`
`hooks`	Một `hooks/hooks.json` với event handler mẫu
`mcp`	Một `.mcp.json` với ví dụ server HTTP và stdio
`lsp`	Một ví dụ language server `.lsp.json`
`output-style`	Một `output-styles/<name>.md` tự áp dụng khi plugin đang bật
`channel`	Một channel dựa trên MCP: server stdio (`server.ts`), `.mcp.json`, và `package.json`

Plugin scaffold dùng source @skills-dir thay vì marketplace. Admin có thể chặn source này bằng strictKnownMarketplaces hoặc thêm {"source": "skills-dir"} vào blockedMarketplaces trong managed settings. Khi bị chặn, plugin init lỗi trước khi ghi file.

Ví dụ:

# Scaffold một plugin tối giản
claude plugin init my-helper

# Scaffold với thư mục skill và hook
claude plugin init my-helper --with skills hooks

# Ghi đè một scaffold đã có
claude plugin init my-helper --force

plugin install

Cài một plugin từ các marketplace có sẵn.

claude plugin install <plugin> [options]

Tham số:

<plugin>: Tên plugin hoặc plugin-name@marketplace-name cho một marketplace cụ thể

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`-s, --scope <scope>`	Scope cài đặt: `user`, `project`, hoặc `local`	`user`
`--config <key=value>`	Đặt một option `userConfig` khai báo trong manifest của plugin. Lặp lại flag để đặt nhiều option
`-h, --help`	Hiện trợ giúp lệnh

Scope quyết định plugin cài được ghi vào file settings nào. Ví dụ, --scope project ghi vào enabledPlugins trong .claude/settings.json, khiến plugin có sẵn cho mọi người clone repository project.

Ví dụ:

# Cài vào scope user (mặc định)
claude plugin install formatter@my-marketplace

# Cài vào scope project (chia sẻ với nhóm)
claude plugin install formatter@my-marketplace --scope project

# Cài vào scope local (không chia sẻ với nhóm)
claude plugin install formatter@my-marketplace --scope local

plugin uninstall

Gỡ một plugin đã cài.

claude plugin uninstall <plugin> [options]

Tham số:

<plugin>: Tên plugin hoặc plugin-name@marketplace-name

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`-s, --scope <scope>`	Gỡ khỏi scope: `user`, `project`, hoặc `local`	`user`
`--keep-data`	Giữ lại thư mục dữ liệu thường trực của plugin
`--prune`	Gỡ luôn dependency tự cài mà không plugin nào khác còn cần. Xem plugin prune
`-y, --yes`	Bỏ qua xác nhận `--prune`. Bắt buộc khi stdin hoặc stdout không phải TTY
`-h, --help`	Hiện trợ giúp lệnh

Alias: remove, rm

Mặc định, gỡ khỏi scope cuối cùng còn lại cũng xóa thư mục ${CLAUDE_PLUGIN_DATA} của plugin. Dùng --keep-data để giữ lại, ví dụ khi cài lại sau khi test một version mới.

plugin prune

Gỡ dependency plugin tự cài không còn plugin nào yêu cầu. Dependency mà Claude Code kéo vào để thỏa mãn dependencies của một plugin khác bị gỡ; plugin bạn tự cài trực tiếp không bao giờ bị đụng tới.

claude plugin prune [options]

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`-s, --scope <scope>`	Prune ở scope: `user`, `project`, hoặc `local`	`user`
`--dry-run`	Liệt kê thứ sẽ bị gỡ mà không gỡ thật
`-y, --yes`	Bỏ qua xác nhận. Bắt buộc khi stdin hoặc stdout không phải TTY
`-h, --help`	Hiện trợ giúp lệnh

Alias: autoremove

Lệnh này liệt kê dependency mồ côi và hỏi xác nhận trước khi gỡ. Để gỡ một plugin và dọn dependency của nó trong một bước, chạy claude plugin uninstall <plugin> --prune.

plugin enable

Bật một plugin đang tắt. Nếu plugin khai báo dependency, Claude Code bật chúng bắc cầu ở cùng scope, và lệnh thất bại khi một dependency chưa được cài.

claude plugin enable <plugin> [options]

Tham số:

<plugin>: Tên plugin hoặc plugin-name@marketplace-name

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`-s, --scope <scope>`	Scope cần bật: `user`, `project`, hoặc `local`. Nếu bỏ trống, Claude Code tự phát hiện scope plugin đang cài	Tự phát hiện
`-h, --help`	Hiện trợ giúp lệnh

plugin disable

Tắt một plugin mà không gỡ. Thất bại khi một plugin khác đang bật phụ thuộc vào plugin đích. Thông báo lỗi kèm một lệnh nối chuỗi để tắt hết các plugin phụ thuộc trước.

claude plugin disable [plugin] [options]

Tham số:

[plugin]: Tên plugin hoặc plugin-name@marketplace-name. Tùy chọn khi dùng --all

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`-a, --all`	Tắt mọi plugin đang bật. Không kết hợp được với `--scope`
`-s, --scope <scope>`	Scope cần tắt: `user`, `project`, hoặc `local`. Nếu bỏ trống, Claude Code tự phát hiện scope plugin đang cài	Tự phát hiện
`-h, --help`	Hiện trợ giúp lệnh

plugin update

Update một plugin lên version mới nhất.

claude plugin update <plugin> [options]

Tham số:

<plugin>: Tên plugin hoặc plugin-name@marketplace-name

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`-s, --scope <scope>`	Scope cần update: `user`, `project`, `local`, hoặc `managed`	`user`
`-h, --help`	Hiện trợ giúp lệnh

plugin list

Liệt kê plugin đã cài kèm version, marketplace nguồn, và trạng thái bật.

claude plugin list [options]

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`--json`	Xuất dưới dạng JSON
`--available`	Gồm cả plugin có sẵn từ marketplace. Yêu cầu `--json`
`-h, --help`	Hiện trợ giúp lệnh

Trong một phiên tương tác, /plugin list in một danh sách tương tự trực tiếp, nhưng chỉ bao phủ plugin đã cài từ marketplace:

Plugin nạp từ skills directory xuất hiện trong giao diện /plugin và claude plugin list, nhưng không trong output /plugin list inline.
Plugin nạp cho phiên bằng --plugin-dir hoặc --plugin-url xuất hiện trong giao diện /plugin, và trong claude plugin list chỉ khi cùng flag đó đứng trước subcommand, như claude --plugin-dir <dir> plugin list. Chúng không có bản ghi cài đặt, nên claude plugin list trần không hiện chúng.

Dạng tương tác chấp nhận --enabled hoặc --disabled để chỉ hiện plugin ở trạng thái đó, và ls như shorthand cho list.

plugin details

Hiện danh mục component của một plugin và chi phí token dự phóng. Output liệt kê mọi component plugin đóng góp, nhóm theo Skills, Agents, Hooks, MCP servers, và LSP servers, kèm ước tính số token nó thêm vào mỗi phiên. Nhóm Skills gồm cả entry skills/ và commands/.

claude plugin details <name>

Tham số:

<name>: Tên plugin hoặc plugin-name@marketplace-name

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`-h, --help`	Hiện trợ giúp lệnh

Output hiện hai con số chi phí cho mỗi component:

Always-on: token thêm vào mọi phiên bởi văn bản liệt kê của plugin, như mô tả skill, mô tả agent, và tên command, bất kể component có được kích hoạt hay không.
On-invoke: token một component tốn khi nó kích hoạt. Hiện theo từng component, không phải tổng của plugin, vì một phiên điển hình chỉ gọi một tập con component.

Ví dụ output cho một plugin có hai skill:

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  SessionStart  (harness-only - no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

Tổng always-on được tính qua API count_tokens cho model đang active của bạn. Con số theo từng component được scale tỉ lệ từ tổng đó. Nếu API không tới được, lệnh chuyển sang ước tính dựa trên số ký tự.

plugin tag

Tạo một git tag phát hành cho plugin. Mặc định lệnh tag plugin trong thư mục hiện tại; truyền một đường dẫn để tag plugin ở nơi khác. Xem Tag các bản phát hành plugin.

claude plugin tag [path] [options]

Tham số:

[path]: Đường dẫn tới thư mục plugin. Mặc định là thư mục hiện tại.

Tùy chọn:

Tùy chọn	Mô tả	Mặc định
`--push`	Push tag lên remote sau khi tạo
`--dry-run`	In ra thứ sẽ được tag mà không tạo tag thật
`-f, --force`	Tạo tag ngay cả khi working tree bẩn hoặc tag đã tồn tại
`-m, --message <msg>`	Nội dung annotation của tag. Dùng `%s` làm placeholder cho version
`--remote <name>`	Remote để push với `--push`	`origin`
`-h, --help`	Hiện trợ giúp lệnh

Công cụ debug và phát triển

Lệnh debug

Dùng claude --debug để xem chi tiết quá trình nạp plugin:

Output này hiện:

Plugin nào đang được nạp
Lỗi trong manifest plugin, nếu có
Đăng ký skill, agent, và hook
Khởi tạo MCP server

Vấn đề thường gặp

Vấn đề	Nguyên nhân	Cách xử lý
Plugin không nạp	`plugin.json` không hợp lệ	Chạy `claude plugin validate ./my-plugin` hoặc `/plugin validate ./my-plugin`, với `./my-plugin` là thư mục plugin của bạn, để kiểm tra `plugin.json`, frontmatter skill/agent/command, và `hooks/hooks.json` xem có lỗi cú pháp/schema không
Skill không xuất hiện	Sai cấu trúc thư mục	Đảm bảo `skills/` hoặc `commands/` nằm ở gốc plugin, không nằm trong `.claude-plugin/`
Hook không kích hoạt	Script không có quyền thực thi	Chạy `chmod +x script.sh`
MCP server lỗi	Thiếu `${CLAUDE_PLUGIN_ROOT}`	Dùng biến này cho mọi đường dẫn của plugin
Lỗi đường dẫn	Dùng đường dẫn tuyệt đối	Mọi đường dẫn phải tương đối và bắt đầu bằng `./`
LSP `Executable not found in $PATH`	Chưa cài language server	Cài binary (ví dụ `npm install -g typescript-language-server typescript`)

Ví dụ thông báo lỗi

Lỗi validate manifest:

Invalid JSON syntax: Unexpected token } in JSON at position 142: kiểm tra dấu phẩy thiếu, dấu phẩy thừa, hoặc chuỗi không có ngoặc kép
Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined: thiếu một field bắt buộc
Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: lỗi cú pháp JSON

Lỗi nạp plugin:

Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: đường dẫn command tồn tại nhưng không chứa file command hợp lệ
Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: đường dẫn source trong marketplace.json trỏ tới thư mục không tồn tại
Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: xóa định nghĩa component trùng lặp hoặc bỏ strict: false trong entry marketplace

Xử lý sự cố hook

Script hook không chạy:

Kiểm tra script có quyền thực thi: chmod +x ./scripts/your-script.sh
Kiểm tra dòng shebang: dòng đầu phải là #!/bin/bash hoặc #!/usr/bin/env bash
Kiểm tra đường dẫn dùng ${CLAUDE_PLUGIN_ROOT}: "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"
Chạy thử script thủ công: ./scripts/your-script.sh

Hook không kích hoạt đúng sự kiện mong đợi:

Kiểm tra tên sự kiện đúng (phân biệt hoa/thường): PostToolUse, không phải postToolUse
Kiểm tra pattern matcher khớp với tool của bạn: "matcher": "Write|Edit" cho thao tác file
Xác nhận loại hook hợp lệ: command, http, mcp_tool, prompt, hoặc agent

Xử lý sự cố MCP server

Server không khởi động:

Kiểm tra lệnh tồn tại và có quyền thực thi
Kiểm tra mọi đường dẫn dùng biến ${CLAUDE_PLUGIN_ROOT}
Kiểm tra log MCP server: claude --debug hiện lỗi khởi tạo
Chạy thử server thủ công bên ngoài Claude Code

Tool của server không xuất hiện:

Đảm bảo server được cấu hình đúng trong .mcp.json hoặc plugin.json
Xác nhận server triển khai đúng giao thức MCP
Kiểm tra timeout kết nối trong output debug

Lỗi cấu trúc thư mục

Triệu chứng: Plugin nạp được nhưng thiếu component (skill, agent, hook).

Cấu trúc đúng: Component phải ở gốc plugin, không nằm trong .claude-plugin/. Chỉ plugin.json thuộc về .claude-plugin/.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Only manifest here
├── commands/            ← At root level
├── agents/              ← At root level
└── hooks/               ← At root level

Nếu component của bạn nằm trong .claude-plugin/, hãy chuyển ra gốc plugin.

Checklist debug:

Chạy claude --debug và tìm thông báo “loading plugin”
Kiểm tra mỗi thư mục component có xuất hiện trong output debug
Xác nhận quyền file cho phép đọc file plugin

Tham chiếu phân phối và quản lý version

Quản lý version

Claude Code dùng version của plugin làm cache key để quyết định có update hay không. Khi bạn chạy /plugin update hoặc auto-update kích hoạt, Claude Code tính version hiện tại và bỏ qua update nếu nó khớp với version đã cài.

Version được phân giải theo thứ tự ưu tiên đầu tiên còn được đặt trong các mục sau:

Field version trong plugin.json của plugin
Field version trong entry marketplace của plugin trong marketplace.json
Git commit SHA của source plugin, cho các source github, url, git-subdir, và đường dẫn tương đối trong một marketplace lưu trên git
unknown, cho source npm hoặc thư mục cục bộ không nằm trong git repository

Điều này cho bạn hai cách để version một plugin:

Cách tiếp cận	Làm sao	Hành vi update	Phù hợp cho
Version tường minh	Đặt `"version": "2.1.0"` trong `plugin.json`	Người dùng chỉ nhận update khi bạn tăng field này. Push commit mới mà không tăng version thì không có tác dụng, và `/plugin update` báo “already at the latest version”	Plugin phát hành công khai với chu kỳ release ổn định
Version theo commit SHA	Bỏ trống `version` ở cả `plugin.json` lẫn entry marketplace	Người dùng nhận update ở mỗi commit mới tới source git của plugin	Plugin nội bộ hoặc plugin nhóm đang phát triển tích cực

Nếu dùng version tường minh, theo semantic versioning (MAJOR.MINOR.PATCH): tăng MAJOR cho thay đổi phá vỡ tương thích, MINOR cho tính năng mới, PATCH cho sửa lỗi. Ghi lại thay đổi trong CHANGELOG.md.

Xem thêm

Plugins - Hướng dẫn và cách dùng thực tế
Plugin marketplaces - Tạo và quản lý marketplace
Skills - Chi tiết phát triển skill
Subagents - Cấu hình và năng lực agent
Hooks - Xử lý sự kiện và tự động hóa
MCP - Tích hợp công cụ ngoài

Phuc Tran

Software Engineer | Learning Claude