Plugins生态

1 Plugins的定位：能力的封装与分发

• Plugins本身并不引入新的功能，而是提供了一套统一的打包格式和安装机制。一个Plugin能够同时囊括Skills、Hooks、Commands、Agents以及MCP配置，只需要一行命令即可让所有组件就位。

点击查看代码

/plugin install team-toolkit@our-company

2 Plugin的物理结构

• 以下是一个典型的Plugin目录结构示例（以react-workflow为例）。

点击查看代码

react-workflow/ ← Plugin根目录
├── .claude-plugin/
│ └── plugin.json ← [必需]Plugin清单文件
├── commands/ ← 斜杠命令定义
│ ├── review.md │ └── deploy.md ├── agents/ ← 子智能体定义
│ ├── security-scanner.md │ └── quick-fix.md ├── skills/ ← Skills领域知识包
│ └── react-patterns/
│ ├── SKILL.md │ └── chapters/
│ ├── hooks.md │ └── performance.md ├── hooks/ ← Hooks配置与脚本
│ ├── hooks.json │ ├── check-bash.sh │ └── auto-format.sh ├── .mcp.json ←
MCP服务器配置引用
└── README.md ← 文档说明

点击查看代码

react-workflow/                ← Plugin 根目录
├── .claude-plugin/
│   └── plugin.json            ← [必需] Plugin 清单文件
├── commands/                  ← 斜杠命令定义
│   ├── review.md
│   └── deploy.md
├── agents/                    ← 子智能体定义
│   ├── security-scanner.md
│   └── quick-fix.md
├── skills/                    ← Skills 领域知识包
│   └── react-patterns/
│       ├── SKILL.md
│       └── chapters/
│           ├── hooks.md
│           └── performance.md
├── hooks/                     ← Hooks 配置与脚本
│   ├── hooks.json
│   ├── check-bash.sh
│   └── auto-format.sh
├── .mcp.json                  ← MCP 服务器配置引用
└── README.md                  ← 文档说明

2.1 plugin.json：Plugin的“身份证”

点击查看代码

{
  "name": "react-workflow",
  "version": "1.2.0",
  "description": "Complete React/TypeScript development workflow for Claude Code",
  "author": "YourName",
  "repository": "https://github.com/yourname/react-workflow",
  "license": "MIT",
  "keywords": [
    "react",
    "typescript",
    "workflow",
    "code-review"
  ]
}

2.2 组件的具体格式

1.命令文件

• 命令文件位于commands/目录下，采用Markdown格式。

点击查看代码

---
name: review
description: 对当前文件或目录进行代码审查
---

当用户运行 `/review [target]` 时，请执行以下代码审查流程。

## 审查要点

1. **代码质量**：检查命名规范、是否遵循 DRY 原则
2. **安全问题**：排查输入验证缺失、潜在的注入风险（如 SQL 注入、XSS）
3. **性能问题**：识别不必要的循环、潜在的内存泄漏或低效算法

## 输出格式

请严格按照以下分类输出审查结果：

- **严重**：必须立即修复的问题
- **警告**：建议修复的潜在隐患
- **建议**：可选的代码优化或改进点

2.子智能体文件

• 子智能体文件位于agents/目录下，用于定义具备特定角色、权限和模型配置的专用Agent。

点击查看代码

---
name: security-scanner
description: 扫描代码中的安全漏洞
tools: Read, Grep, Glob
model: sonnet
---

你是一名资深的安全专家，专门负责识别代码库中的潜在安全漏洞。

## 核心职责

请重点检查以下风险点：

- **注入攻击**：检测 SQL 注入、命令注入等风险
- **跨站脚本（XSS）**：排查未转义的用户输入输出
- **凭证泄露**：查找硬编码的 API 密钥、密码或私钥
- **权限控制**：验证访问控制逻辑是否严密

3. Hooks配置文件

• Hooks配置文件位于hooks/目录下，用于定义Plugin在特定生命周期事件中的自动化行为。

点击查看代码

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Bash",
      "command": ["bash", "./hooks/check-bash.sh"]
    },
    {
      "event": "PostToolUse",
      "matcher": "Write",
      "command": ["bash", "./hooks/auto-format.sh"]
    }
  ]
}

4. MCP配置文件

• MCP配置文件通常位于项目根目录，名为.mcp.json。

点击查看代码

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

3 安装与生命周期管理

3.1 安装来源

点击查看代码

# 从社区市场安装（从官方或认证的社区仓库拉取已发布的 Plugin 包）
/plugin install react-workflow@community

# 从 GitHub 仓库安装（注意：旧版 github 前缀格式已废弃，必须使用完整的 github.com/... URL 格式）
/plugin install github.com/username/react-workflow

# 从本地目录安装（适用场景：Plugin 开发调试阶段，修改代码后无需重新发布即可实时测试）
/plugin install ./path/to/my-plugin

3.2 日常管理

点击查看代码

# 列出所有已安装的 Plugin
/plugin list

# 卸载指定 Plugin（如 react-workflow）
/plugin remove react-workflow

# 将指定 Plugin 更新至最新版本
/plugin update react-workflow

3.3 本地开发与测试

• 在开发Plugin时，可以使用--plugin-dir参数直接加载本地目录，从而跳过标准的安装流程。

点击查看代码

claude --plugin-dir ./my-plugin-dev

3.4 存储位置

• Plugin安装后默认存储在~/.claude/plugins/目录下。开发者可通过设置CLAUDE_PLUGIN_ROOT环境变量来自定义存储路径。

4 命名空间：多Plugin共存

• 当多个Plugin同时安装且包含同名的Skill或Command时，会发生什么？Plugins系统通过命名空间机制自动解决冲突。

点击查看代码

• 原review Command变为/react-workflow:review。
• 原code-reviewer Skill变为react-workflow:code-reviewer。
• 原security-scanner Agent变为react-workflow:security-scanner。

5 实战：构建团队能力包

5.1 完整目录结构

点击查看代码

team-toolkit/
├── .claude-plugin/
│ └── plugin.json ├── commands/
│ ├── review.md # 代码审查命令定义
│ └── test.md # 测试运行命令定义
├── agents/
│ ├── security-scanner.md # 安全扫描子智能体配置
│ └── quick-fix.md # 快速修复子智能体配置
├── skills/
│ └── react-patterns/
│ └── SKILL.md # React 最佳实践知识库
├── hooks/
│ ├── hooks.json # Hook触发配置
│ ├── check-bash.sh # Bash命令安全检查脚本
│ └── auto-format.sh # 自动格式化执行脚本
├── .mcp.json # MCP配置（数据库与GitHub链接）
└── README.md # 项目说明文档

5.2 plugin.json

点击查看代码

{
  "name": "team-toolkit",
  "version": "2.0.0",
  "description": "团队标准化开发工具包：集成代码审查、自动化测试与安全扫描功能",
  "author": "Platform Team",
  "repository": "https://github.com/our-company/teamtoolkit",
  "license": "MIT",
  "keywords": [
    "team",
    "devops",
    "code-review",
    "security"
  ]
}

5.3 安全扫描子智能体

• 安全扫描子智能体agents/security-scanner.md的内容如下。

点击查看代码

---
name: security-scanner
description: 扫描代码库中的安全漏洞并生成结构化报告
tools:
  - Read
  - Grep
  - Glob
model: sonnet
---

你是一名资深安全专家，专注于识别代码中的潜在安全漏洞。

## 扫描范围

1. **注入漏洞**：包括 SQL 注入、命令注入及 XSS。
2. **认证问题**：涵盖弱密码策略、硬编码凭证及会话管理缺陷。
3. **数据暴露**：涉及敏感信息日志输出及不安全的数据传输。
4. **访问控制**：包括缺失权限校验及路径遍历漏洞。

## 工作流程

1. **文件发现**：使用 `Glob` 获取所有源代码文件。
2. **模式匹配**：使用 `Grep` 搜索可疑代码模式（如 `eval`、`dangerouslySetInnerHTML`、`exec` 等）。
3. **深度分析**：使用 `Read` 读取可疑代码的上下文，确认漏洞真实性。
4. **报告生成**：输出结构化报告，明确列出每个问题的文件名、行号及风险等级。

## 执行原则

- **证据确凿**：仅报告有确切代码证据的问题，严禁主观臆测。
- **修复导向**：不仅指出问题，还必须提供具体可行的修复建议。
- **严谨标注**：对于无法完全确定的潜在风险，明确标注为“疑似”。

5.4 Hooks：安全检查脚本

• 安全检查脚本hooks/check-bash.sh的内容如下。

点击查看代码

#!/bin/bash
# Bash 命令安全拦截脚本
# 用于在 Claude Code 执行危险命令前进行阻断

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

DANGEROUS_PATTERNS=(
  "rm -rf "
  "rm -rf ~"
  "sudo rm"
  "> dev/"
  "chmod 777"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qF "$pattern"; then
    cat <<EOF
{"decision": "deny", "reason": "

5.5 发布流程

• 一个Plugin本质上是一个标准的Git仓库，因此发布新版本的过程，就是将代码提交、打标签并推送到远程仓库的过程。
• 请在Plugin根目录（team-toolkit）下执行以下命令。

点击查看代码

cd team-toolkit
git init
git add .
git commit -m "v2.0.0: 集成安全扫描与自动格式化功能"
git tag v2.0.0
git remote add origin https://github.com/our-company/team-toolkit
git push -u origin main --tags

• 团队成员可通过以下命令直接安装该Plugin。

点击查看代码

plugin install github.comour-company/team-toolkit

6 私有市场与企业管理

• 对大型组织而言，逐个分发GitHub仓库地址缺乏体系化管理。Plugins系统支持私有市场（Private Marketplace）机制，允许企业构建集中式的内部插件索引，实现统一分发与版本管控。

6.1 构建私有市场

点击查看代码

{
  "name": "Our Company Plugins",
  "description": "内部插件市场",
  "plugins": [
    {
      "name": "team-toolkit",
      "description": "团队标准化开发工具包",
      "repository": "https://github.com/our-company/team-toolkit",
      "version": "2.0.0"
    },
    {
      "name": "db-tools",
      "description": "数据库操作工具集",
      "repository": "https://github.com/our-company/db-tools",
      "version": "1.2.0"
    }
  ]
}

6.2 使用私有市场

点击查看代码

plugin marketplace add our-companyclaude-plugins
/plugin install team-toolkit@our-company

6.3 组织级Plugin管理

• 统一分发
• 版本管控
• 审计可见

7 Plugin设计原则

7.1 单一职责

• react-workflow：专用于React开发工作流优化。
• security-scanner：专注于代码安全扫描。
• db-tools：仅提供数据库操作辅助。

7.2 渐进式迭代

• v1.0.0：发布核心功能（如单个高效的代码审查命令）。
• v1.1.0：扩展子能力（如集成安全扫描子智能体）。
• v1.2.0：增强领域技能（如添加React最佳实践指南）。
• v2.0.0：深化自动化（如引入MCP集成与Hooks自动化流程）。

7.3 最小权限

• 子智能体应严格遵循按需申请原则，仅获取完成其核心任务所必需的工具权限。
• 若子智能体仅负责代码审查与分析，其权限应严格限制在只读操作（如Read、Grep、Glob），严禁授予此类智能体写入文件（Write）或执行系统命令（Bash）的权限。

7.4 文档是必需品

• 快速安装：提供一行即可执行的安装命令，降低启动门槛。
• 功能清单：清晰地列出所有可用的Command、子智能体及Skill，并附带简要说明。
• 配置指南：详细说明所需的环境变量（特别是MCP服务器连接配置），避免用户因配置缺失而受阻。
• 更新日志：记录每个版本的变更内容、新增功能及修复的问题，帮助用户评估升级影响。

8 何时将能力打包为Plugin

• 并非所有的Skill或Hook都需要打包为Plugin。选择分发方式的核心依据是目标受众的范围。

分发范围推荐方式核心优势

• 单个项目项目级配置（.claude/目录）代码同源：配置与代码共同版本管理，变更可追溯
• 个人跨项目用户级配置（~/.claude/目录）个性化：适配个人偏好，不影响团队其他成员
• 跨团队/组织公开/私有Plugin标准化：支持一键安装，便于跨项目复用
• 企业统一推行组织级Plugin强制管控：管理员统一部署，不需要员工手动操作

9 LSP支持与未来演进