真背单词
68.16M · 2026-02-23
在前面的文章中,我们已经学习了:
但在实际使用中,你可能会遇到这些场景:
场景 1: 功能分散,难以管理
你的 .claude/ 目录下有:
├── commands/
│ ├── deploy.md
│ ├── test.md
│ └── format.md
├── agents/
│ └── reviewer.md
├── hooks/
│ └── hooks.json
└── .mcp.json
问题:这些功能是一套完整的工作流,但分散在各处
- 团队成员需要手动复制多个文件
- 更新时需要逐个文件同步
- 难以版本管理
场景 2: 团队共享困难
你: "我写了一套很好用的代码审查流程,包含 Agent、Skill 和 Hook"
同事: "能分享给我吗?"
你: "好的,你需要复制这3个文件到这里,那2个文件到那里..."
同事: "这么复杂?算了我自己写吧..."
场景 3: 无法跨项目复用
项目 A 中精心配置的开发工具:
- Git 提交规范 Skill
- 代码格式化 Hook
- 测试运行 Agent
- CI/CD 集成 MCP
问题:切换到项目 B 时,又要重新配置一遍
Plugin 就是解决这些问题的终极方案——它是一个打包和分发机制:
/plugin install 命令,一次性获得完整功能本文核心内容:
Plugin(插件)是 Claude Code 的轻量级打包机制,用于组合多种扩展点:
Plugin = Skills + Agents + Hooks + MCP Servers + LSP Servers
核心特点:
plugin.json 管理元数据和依赖让我们先用一张图来理解它们之间的关系:
图示内容:
| 层级 | 名称 | 作用 | 示例 |
|---|---|---|---|
| 基础层 | Tools | Claude Code 内置的基础能力 | Read、Write、Grep、Bash |
| 连接层 | MCP Servers | 连接外部服务和工具 | 数据库查询、API 调用、文件系统访问 |
| 能力层 | Skills | 领域知识和工作流程 | PDF 处理、BigQuery 分析、代码审查 |
| 能力层 | Agents(Subagents) | 专业化的子智能体 | 后端架构师、技术博客作者、测试工程师 |
| 能力层 | Hooks | 事件驱动的自动化 | 代码提交前检查、文件保存后格式化 |
| 打包层 | Plugin | 组合上述能力成完整工具包 | 完整的部署工具、代码审查系统 |
| 分发层 | Marketplace | Plugin 的发现和安装平台 | 官方市场、团队市场、社区市场 |
Claude Code 支持两种方式添加自定义功能:
| 方式 | 位置 | Skill 名称 | 适用场景 |
|---|---|---|---|
| 独立配置 | .claude/ 目录 | /hello | 个人工作流、项目特定定制、快速实验 |
| Plugin | 带 .claude-plugin/plugin.json 的目录 | /plugin-name:hello | 团队共享、社区分发、版本管理、跨项目复用 |
何时使用独立配置?
/hello 而非 /my-plugin:hello)何时使用 Plugin?
/my-plugin:hello,避免冲突)一个完整的 Plugin 目录结构如下:
enterprise-plugin/
├── .claude-plugin/ # 元数据目录
│ └── plugin.json # Plugin 清单文件(使用默认位置时可选)
├── commands/ # 简单 Skills(单个 .md 文件)
│ ├── deploy.md
│ └── status.md
├── skills/ # Agent Skills(推荐,目录+SKILL.md)
│ ├── code-reviewer/
│ │ ├── SKILL.md
│ │ └── scripts/
│ └── pdf-processor/
│ ├── SKILL.md
│ └── reference.md
├── agents/ # 子智能体
│ ├── security-reviewer.md
│ ├── performance-tester.md
│ └── compliance-checker.md
├── hooks/ # 事件钩子
│ ├── hooks.json
│ └── security-hooks.json
├── .mcp.json # MCP 服务器配置
├── .lsp.json # LSP 服务器配置
├── scripts/ # 辅助脚本
│ ├── security-scan.sh
│ ├── format-code.py
│ └── deploy.js
├── README.md # 使用文档
├── LICENSE # 许可证
└── CHANGELOG.md # 版本历史
️ 重要说明:目录位置
commands/、skills/、agents/、hooks/)必须在 Plugin 根目录.claude-plugin/ 目录内.claude-plugin/ 内只放 plugin.json| 特性 | commands/ | skills/ |
|---|---|---|
| 文件格式 | 单个 Markdown 文件(如 deploy.md) | 目录包含 SKILL.md(如 deploy/SKILL.md) |
| 适用场景 | 简单的斜杠命令,不需要额外资源 | 复杂的 Agent Skills,可包含脚本、参考文档 |
| 调用方式 | /plugin-name:command-name | /plugin-name:skill-name |
| 推荐使用 | 简单命令 | 推荐用于新 Skills(支持渐进式披露) |
| 支持资源 | 不支持 | 支持(scripts、reference 文件等) |
推荐做法:
skills/ 目录格式commands/skills/plugin.json 是 Plugin 的配置文件,位于 .claude-plugin/ 目录下。
重要: 如果你的 Plugin 使用默认目录位置(commands/、skills/、agents/等)且不需要自定义配置,plugin.json 是可选的。Claude Code 会自动识别这些默认目录并从目录名推导 Plugin 名称。
当你需要以下功能时,plugin.json 是必需的:
完整的 plugin.json 示例:
{
"name": "enterprise-tools",
"version": "2.1.0",
"description": "企业级开发工具集,包含部署、审查、测试完整流程",
"author": {
"name": "Development Team",
"email": "dev@company.com",
"url": "https://github.com/company"
},
"homepage": "https://docs.company.com/plugin",
"repository": "https://github.com/company/enterprise-plugin",
"license": "MIT",
"keywords": ["deployment", "code-review", "testing", "ci-cd"],
"commands": ["./specialized/deploy.md"],
"agents": "./custom-agents/",
"skills": "./custom-skills/",
"hooks": "./config/hooks.json",
"mcpServers": "./mcp-config.json",
"lspServers": "./.lsp.json"
}
如果你选择创建 plugin.json,只有一个字段是必填的:
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
name | string | 唯一标识符(kebab-case,无空格) | "deployment-tools" |
| 字段 | 类型 | 说明 |
|---|---|---|
version | string | 语义化版本号(如 "2.1.0") |
description | string | Plugin 用途的简短说明 |
author | object | 作者信息(name、email、url) |
homepage | string | 文档 URL |
repository | string | 源代码 URL |
license | string | 许可证标识符(如 "MIT") |
keywords | array | 用于发现的标签 |
| 字段 | 类型 | 说明 |
|---|---|---|
commands | string|array | 额外的 Skill 文件/目录 |
agents | string|array | 额外的 Agent 文件 |
skills | string|array | 额外的 Skills 目录 |
hooks | string|array|object | Hook 配置路径或内联配置 |
mcpServers | string|array|object | MCP 配置路径或内联配置 |
lspServers | string|array|object | LSP 配置 |
outputStyles | string|array | 输出样式文件/目录 |
重要规则:
commands/ 存在,会在自定义路径外额外加载./ 开头${CLAUDE_PLUGIN_ROOT}${CLAUDE_PLUGIN_ROOT} 包含 Plugin 目录的绝对路径。在 Hooks、MCP Servers 和脚本中使用,确保路径正确:
{
"hooks": {
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
}
]
}
]
}
}
Claude Code 提供了一系列官方 Plugin,覆盖不同的开发场景。让我们深入了解几个典型的 Plugin:
用途: 7 阶段的功能开发工作流,从需求分析到部署
核心能力:
适用场景:
使用方式:
# 安装
/plugin install feature-dev
# 使用
/feature-dev:start "添加用户登录功能"
用途: 多角度、全方位的代码审查系统
核心能力:
并行机制: 4个 Agent 同时工作,最后汇总报告
适用场景:
使用方式:
# 安装
/plugin install code-review
# 审查当前分支
/code-review:review
# 审查指定文件
/code-review:review src/auth/login.ts
用途: 用自然语言描述 Hook 行为,无需编写脚本
核心能力:
适用场景:
使用方式:
# 安装
/plugin install hookify
# 创建 Hook
/hookify:create "当保存 Python 文件时,自动运行 black 格式化"
LSP(Language Server Protocol) Plugins 为 Claude 提供实时代码智能:
| Plugin | 语言服务器 | 安装命令 |
|---|---|---|
pyright-lsp | Pyright (Python) | pip install pyright |
typescript-lsp | TypeScript Language Server | npm install -g typescript-language-server typescript |
rust-lsp | rust-analyzer | 见官方文档 |
核心能力:
使用方式:
# 1. 先安装语言服务器
npm install -g typescript-language-server typescript
# 2. 安装 LSP Plugin
/plugin install typescript-lsp
访问官方 Marketplace 浏览完整列表:
/plugin discover
让我们通过一个实战案例,创建一个简单的问候 Plugin:
Step 1: 创建 Plugin 目录
mkdir my-first-plugin
Step 2: 创建清单文件
mkdir my-first-plugin/.claude-plugin
创建 my-first-plugin/.claude-plugin/plugin.json:
{
"name": "my-first-plugin",
"description": "学习基础的问候 Plugin",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
Step 3: 添加 Skill
mkdir -p my-first-plugin/skills/hello
创建 my-first-plugin/skills/hello/SKILL.md:
---
description: 用友好的消息问候用户
disable-model-invocation: true
---
热情地问候用户,并询问今天有什么可以帮助的。
Step 4: 测试 Plugin
claude --plugin-dir ./my-first-plugin
在 Claude Code 中:
/my-first-plugin:hello
Step 5: 添加 Skill 参数
更新 hello/SKILL.md:
---
description: 用个性化消息问候用户
---
# Hello Command
热情地问候名为 "$ARGUMENTS" 的用户,并询问今天有什么可以帮助的。让问候语个性化且鼓舞人心。
测试:
/my-first-plugin:hello Alex
创建一个用于数据库 schema 迁移的完整工具:
db-migration-tools/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ ├── migration-generator/
│ │ ├── SKILL.md
│ │ └── templates/
│ │ ├── up.sql.tmpl
│ │ └── down.sql.tmpl
│ └── migration-validator/
│ └── SKILL.md
├── agents/
│ └── db-architect.md
├── .mcp.json
└── scripts/
├── generate-migration.sh
└── validate-migration.sh
---
name: migration-generator
description: 生成数据库迁移脚本。当需要创建 schema 变更、添加表、修改列时使用。
---
# 数据库迁移生成器
根据用户描述生成标准的数据库迁移脚本。
## 生成步骤
1. **理解变更需求**:
- 询问变更类型(创建表、修改列、添加索引等)
- 确认数据库类型(PostgreSQL、MySQL、SQLite)
- 了解业务背景和约束
2. **生成迁移脚本**:
- `up.sql`:应用变更的脚本
- `down.sql`:回滚变更的脚本
- 命名格式:`YYYYMMDDHHMMSS_description.sql`
3. **包含最佳实践**:
- 使用事务包裹变更
- 添加回滚点
- 包含数据迁移逻辑(如果需要)
- 添加详细注释
## 示例
用户: "添加 users 表的 email_verified 布尔字段,默认 false"
生成的迁移:
**202602120900_add_email_verified_to_users.up.sql**:
```sql
BEGIN;
-- 添加 email_verified 字段
ALTER TABLE users
ADD COLUMN email_verified BOOLEAN NOT NULL DEFAULT false;
-- 为已存在用户设置默认值
UPDATE users
SET email_verified = false
WHERE email_verified IS NULL;
-- 添加注释
COMMENT ON COLUMN users.email_verified IS '邮箱是否已验证';
COMMIT;
202602120900_add_email_verified_to_users.down.sql:
BEGIN;
-- 删除 email_verified 字段
ALTER TABLE users
DROP COLUMN IF EXISTS email_verified;
COMMIT;
使用模板文件 templates/up.sql.tmpl 和 templates/down.sql.tmpl 生成脚本。
#### Agent:db-architect.md
```markdown
---
name: db-architect
description: 数据库架构师。设计 schema、评估性能影响、制定迁移策略。当需要复杂的数据库设计时调用。
---
# Database Architect Agent
你是一位资深的数据库架构师,专注于 schema 设计、性能优化和数据迁移。
## 你的职责
1. **Schema 设计**:
- 设计合理的表结构和关系
- 选择合适的数据类型
- 设计索引策略
2. **性能评估**:
- 评估变更对查询性能的影响
- 识别潜在的性能瓶颈
- 提出优化建议
3. **迁移策略**:
- 制定零停机迁移方案
- 处理数据转换和回填
- 评估回滚风险
## 工作流程
1. 理解业务需求和数据模型
2. 设计 schema 变更方案
3. 评估性能和风险
4. 生成迁移脚本
5. 制定测试和回滚计划
## 输出格式
**Schema 设计文档**:
- 表结构说明
- 字段类型和约束
- 索引设计
- 关系图示
**迁移计划**:
- 变更步骤
- 预估影响范围
- 回滚步骤
- 测试清单
{
"mcpServers": {
"database-query": {
"command": "npx",
"args": ["@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://localhost/mydb"
}
}
}
}
如果你已经在 .claude/ 中有配置,可以轻松转换为 Plugin:
Step 1: 创建 Plugin 结构
mkdir -p my-plugin/.claude-plugin
创建 my-plugin/.claude-plugin/plugin.json:
{
"name": "my-plugin",
"description": "从独立配置迁移",
"version": "1.0.0"
}
Step 2: 复制现有文件
# 复制 Skills
cp -r .claude/commands my-plugin/
cp -r .claude/skills my-plugin/
# 复制 Agents
cp -r .claude/agents my-plugin/
# 复制 Hooks
mkdir my-plugin/hooks
# 从 settings.json 中提取 hooks 对象
# 粘贴到 my-plugin/hooks/hooks.json
Step 3: 迁移 Hooks
从 .claude/settings.json 复制 hooks 配置到 my-plugin/hooks/hooks.json。
注意:Hook 命令需要更新路径,使用 ${CLAUDE_PLUGIN_ROOT}:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh"
}]
}
]
}
}
Step 4: 测试迁移后的 Plugin
claude --plugin-dir ./my-plugin
迁移前后对比:
独立配置(.claude/) | Plugin |
|---|---|
| 仅在一个项目中可用 | 可通过 Marketplace 共享 |
Skill 在 .claude/commands/ | Skill 在 plugin-name/skills/ |
Hooks 在 settings.json | Hooks 在 hooks/hooks.json |
| 手动复制共享 | /plugin install 安装 |
Plugin Marketplace(插件市场)是 Plugin 的发现和安装平台:
一个 Marketplace 本质上是一个包含 marketplace.json 的 Git 仓库:
my-marketplace/
├── marketplace.json # 市场配置
└── plugins/ # Plugin 源代码目录
├── plugin-a/
├── plugin-b/
└── plugin-c/
{
"name": "company-tools",
"displayName": "Company Internal Tools",
"description": "企业内部开发工具集",
"version": "1.0.0",
"homepage": "https://docs.company.com/plugins",
"plugins": [
{
"name": "android-review",
"displayName": "Android 代码审查",
"description": "Android 代码审查工具集",
"version": "1.0.0",
"source": "./plugins/android-review",
"author": {
"name": "Android Team"
},
"tags": ["android", "code-review"]
},
{
"name": "db-migration",
"displayName": "数据库迁移工具",
"description": "数据库 schema 迁移工具",
"version": "1.2.0",
"source": "./plugins/db-migration",
"author": {
"name": "Backend Team"
},
"tags": ["database", "migration"]
}
]
}
Step 1: 初始化 Git 仓库
mkdir company-plugins
cd company-plugins
git init
Step 2: 创建市场配置
创建 marketplace.json:
{
"name": "company-tools",
"displayName": "Company Tools",
"description": "公司内部工具集",
"version": "1.0.0",
"plugins": []
}
Step 3: 添加 Plugin
mkdir -p plugins/my-tool
cp -r /path/to/my-plugin/* plugins/my-tool/
更新 marketplace.json:
{
"plugins": [
{
"name": "my-tool",
"displayName": "My Tool",
"description": "我的工具描述",
"version": "1.0.0",
"source": "./plugins/my-tool",
"author": { "name": "Your Name" }
}
]
}
Step 4: 推送到 Git
git add .
git commit -m "Add my-tool plugin"
git push origin main
Step 5: 配置 Marketplace
编辑 .claude/settings.json:
{
"pluginMarketplaces": [
{
"name": "company-tools",
"url": "https://github.com/company/plugins.git",
"autoUpdate": true
}
]
}
Step 6: 使用 Marketplace
# 刷新市场
/plugin refresh
# 浏览可用 Plugin
/plugin discover
# 安装
/plugin install my-tool@company-tools
安装 Plugin 时,可以选择不同的作用域:
| 作用域 | 配置文件 | 适用场景 |
|---|---|---|
user | ~/.claude/settings.json | 个人 Plugin,跨所有项目(默认) |
project | .claude/settings.json | 团队共享,通过版本控制 |
local | .claude/settings.local.json | 项目特定,gitignored |
managed | managed-settings.json | 托管 Plugin(只读,仅更新) |
安装示例:
# 安装到 user 作用域(默认)
/plugin install formatter
# 安装到 project 作用域(团队共享)
/plugin install formatter --scope project
# 安装到 local 作用域(不提交)
/plugin install formatter --scope local
出于安全和验证目的,Claude Code 会将 Plugin 复制到缓存目录:
工作流程:
source 字段source 类型(相对路径、npm、pip、url、github)复制到缓存路径遍历限制:
../shared-utils)解决方案:
1. 单一职责原则
2. 组合优于继承
3. 约定优于配置
skills/、agents/、hooks/)4. 文档先行
README.mdCHANGELOG.md 记录版本变更遵循语义化版本(Semantic Versioning):
MAJOR.MINOR.PATCH
示例:
1.0.0: 第一个稳定版本1.1.0: 添加新 Skill(向后兼容)1.1.1: 修复 Hook 脚本 bug2.0.0: Agent 接口改动(破坏性变更)2.0.0-beta.1: 测试预发布版本最佳实践:
plugin.json 中的版本号CHANGELOG.md 记录变更2.0.0-beta.1)本地测试:
# 使用 --plugin-dir 加载 Plugin
claude --plugin-dir ./my-plugin
# 测试 Skills
/my-plugin:skill-name
# 测试 Agents
"请 my-plugin:agent-name Agent 执行任务"
# 测试 Hooks(触发相应事件)
多 Plugin 测试:
# 同时加载多个 Plugin
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b
调试技巧:
# 启用调试模式
claude --debug
# 或在 TUI 中
/debug
调试模式显示:
plugin.json 错误| 问题 | 原因 | 解决方案 |
|---|---|---|
| Plugin 未加载 | plugin.json 无效 | 使用 /plugin validate 验证 JSON |
| Skill 未出现 | 目录结构错误 | 确保 skills/ 在根目录,不在 .claude-plugin/ 内 |
| Hook 未触发 | 脚本不可执行 | 运行 chmod +x script.sh |
| MCP Server 失败 | 缺少 ${CLAUDE_PLUGIN_ROOT} | 所有路径使用该变量 |
| 路径错误 | 使用绝对路径 | 所有路径必须相对,以 ./ 开头 |
LSP 错误: Executable not found | 语言服务器未安装 | 安装二进制文件(如 npm install -g typescript-language-server) |
示例错误信息:
清单验证错误:
Invalid JSON syntax: Unexpected token } in JSON at position 142
→ 检查缺少逗号、多余逗号或未引用的字符串
Plugin 加载错误:
Plugin directory not found at path: ./plugins/my-plugin
→ marketplace.json 中的 source 路径指向不存在的目录
Hook 故障排查:
chmod +x ./scripts/script.sh#!/bin/bash 或 #!/usr/bin/env bash${CLAUDE_PLUGIN_ROOT}./scripts/script.sh1. 脚本执行权限
sudo2. 环境变量
plugin.json 中包含密钥3. 第三方依赖
4. 输入验证
1. 按需加载
2. 减少 Token 占用
description 字段简洁明确3. 脚本执行效率
官方 Marketplace:
/plugin discover
浏览分类:
社区资源:
方式 1: 提交到官方市场
方式 2: 创建团队市场
settings.json方式 3: 开源到 GitHub
claude-code-plugin topic方式 4: 发布到 npm/pip
使用独立配置(.claude/):
创建 Plugin:
初学者:
SKILL.md)进阶开发者:
专家级:
/plugin-name:skill 格式${CLAUDE_PLUGIN_ROOT} 确保路径正确--plugin-dir 本地测试再分发相关文章:
如果这篇文章对你有帮助,欢迎点赞、收藏、分享!有任何问题或建议,欢迎在评论区留言讨论。让我们一起学习,一起成长!
也欢迎访问我的个人主页发现更多宝藏资源
