AI创业内参
Agent工坊

【Agent工坊】Claude Code 插件系统完整教程：从 .claude/ 混乱到一键分发的工业化工作流

AI创业内参

Claude Code 插件生态已突破 32,019 个活跃插件。Week 19 新增 --plugin-url 远程加载和 .zip 打包支持——你的定制技能、Agent 和 Hook 终于可以像 npm 包一样分发了。

痛点：你的 .claude/ 已经失控了

如果你用过 Claude Code 超过一周，大概率经历过以下场景：

.claude/
├── CLAUDE.md          # 1800行的系统提示词
├── commands/
│   ├── review.md       # 代码审查命令
│   ├── deploy.md       # 部署命令（已过时，但不敢删）
│   ├── test.md         # 测试命令（跟review.md 80%重复）
│   └── ...
├── skills/
│   ├── pdf-processor/  # 上个月的项目需要
│   ├── code-reviewer/  # 这个月的项目也要
│   └── api-doc-gen/    # 不知道哪个项目留下的
└── agents/
    ├── architect.md    # 架构师Agent
    └── debugger.md     # 调试Agent（写了一半）

问题清单：
1. 碎片化：每个项目复制粘贴同一套 skills，版本从未同步
2. 难分享：队友需要的不是一个 .claude/ 文件夹，是能用 /plugin-name:skill 调用的命名空间版本
3. 无版本控制：你改了 review.md，队友的 review.md 还是旧版——直到踩了坑才知道
4. 无生态感知：32,019 个插件已经存在，但你还在从零写一切

Claude Code 的插件系统就是为这些问题而生的。

插件 vs 独立配置：什么时候该用插件

独立配置（.claude/） 插件（.claude-plugin/plugin.json）
调用方式 /review /my-plugin:review
共享难度 复制粘贴文件夹 claude --plugin-url https://...
版本管理 手动 plugin.json 含 version 字段
命名空间 无，全局冲突 插件名自动前缀
适用场景 个人实验、项目特化 团队共享、社区分发、可复用资产

一句话决策： 如果一个 skill/agent 你用过两次以上，就值得封装成插件。

第一步：创建你的第一个插件（5分钟）

1. 初始化插件目录

mkdir claude-code-reviewer
mkdir claude-code-reviewer/.claude-plugin

2. 编写 plugin.json 清单

cat > claude-code-reviewer/.claude-plugin/plugin.json << 'EOF'
{
  "name": "code-reviewer",
  "description": "Multi-lens code review: security, performance, readability, testing",
  "version": "1.0.0",
  "author": {
    "name": "Your Team"
  },
  "repository": "https://github.com/your-org/claude-code-reviewer"
}
EOF
字段 说明
name 唯一标识符，也是 skill 的命名空间前缀
description 在 /plugin 管理器里显示的描述
version 版本号，用户只在版本号变化时收到更新
repository 可选，指向源码仓库

3. 添加第一个 Skill：代码审查

mkdir -p claude-code-reviewer/skills/review

skills/review/SKILL.md：

---
description: Multi-lens code review covering security, performance, readability, and test coverage. Use when reviewing PRs, analyzing code changes, or auditing code quality.
---

# Code Review Skill

When reviewing code, systematically check these four dimensions:

## 1. Security（安全）
- SQL injection, XSS, CSRF 漏洞
- 敏感信息硬编码（API key、token、密码）
- 权限校验缺失
- 依赖版本是否有已知 CVE

## 2. Performance（性能）
- N+1 查询问题
- 不必要的循环嵌套
- 大对象内存泄漏风险
- 缓存策略是否合理

## 3. Readability（可读性）
- 函数是否超过 30 行
- 变量命名是否自解释
- 是否有必要的注释（解释"为什么"而非"做什么"）
- 是否符合项目代码风格

## 4. Testing（测试覆盖）
- 核心逻辑是否有单元测试
- 边界条件是否覆盖
- 错误路径是否有测试
- Mock/Stub 是否合理

Output format:
- 每个维度给出通过/警告/失败标记
- 每条问题附带具体行号和修改建议
- 最后给出总体评分（1-10）

4. 本地测试插件

# 从本地目录加载（原有方式）
claude --plugin-dir ./claude-code-reviewer

# 进入交互模式后使用
/code-reviewer:review   # 审查当前代码

5. 🆕 Week 19 新增：打包为 ZIP 并测试

# 打包插件为 ZIP
cd claude-code-reviewer
zip -r ../claude-code-reviewer-1.0.0.zip .
cd ..

# 从 ZIP 文件加载（Week 19 新功能）
claude --plugin-dir ./claude-code-reviewer-1.0.0.zip

第二步：深入插件组件（进阶）

一个完整的插件可以包含以下所有组件：

my-production-plugin/
├── .claude-plugin/
│   └── plugin.json          # 清单文件
├── skills/                  # 技能（57.2% 的插件组件是 skill）
│   └── review/SKILL.md
├── commands/                # 命令（平铺 Markdown，无需子目录）
│   ├── deploy.md
│   └── rollback.md
├── agents/                  # 自定义子Agent
│   └── security-auditor.md
├── hooks/
│   └── hooks.json           # 事件钩子（24种生命周期事件）
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 代码智能
├── monitors/
│   └── monitors.json        # 后台监控
├── settings.json            # 默认设置
└── bin/                     # 可执行脚本（自动加入 PATH）

子Agent 示例（agents/security-auditor.md）

---
name: security-auditor
description: Specialized security auditor that checks for OWASP Top 10 vulnerabilities
model: sonnet
effort: high
maxTurns: 15
disallowedTools: Write, Edit
---

You are a security auditor specializing in web application security.
Your job is to:
1. Scan the provided code for OWASP Top 10 vulnerabilities
2. For each finding, provide CWE ID, severity, and fix recommendation
3. Output results in SARIF format when possible
Do NOT modify any files — only report findings.

Hook 示例（hooks/hooks.json）— 每次代码写入后自动格式化

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

🆕 第三步：Week 19 核心新功能 —— 远程加载

这是 2026 年 5 月 4-8 日（v2.1.128-v2.1.136）最重要的更新：

--plugin-url：一键从 URL 加载插件

# 从 URL 加载单个插件（仅当前会话）
claude --plugin-url https://example.com/my-plugin.zip

# 同时加载多个 URL 插件
claude --plugin-url "https://example.com/plugin-a.zip https://example.com/plugin-b.zip"

# 混合本地和远程
claude --plugin-dir ./my-local-plugin --plugin-url https://example.com/remote-plugin.zip

实际应用场景：

# 场景1：团队内部插件从制品库加载
claude --plugin-url https://artifacts.company.com/claude-plugins/team-toolkit-2.1.0.zip

# 场景2：试用社区插件再决定是否安装
claude --plugin-url https://github.com/user/experimental-plugin/releases/latest/download/plugin.zip

# 场景3：CI/CD 中注入审查插件
claude --plugin-url https://plugins.internal/ci-review.zip -p "review PR #42"

--plugin-dir 现在接受 .zip

旧版只能传目录路径，现在直接传 ZIP 文件：

# 旧版（仅目录）
claude --plugin-dir ./my-plugin/

# 新版（支持 ZIP）
claude --plugin-dir ./my-plugin.zip

# 也支持混合
claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b.zip

生态全景：32,019 个插件在等你

截至 2026 年 4 月，Claude Code 插件生态（数据来源：ClaudePluginHub）：

指标 数值
活跃插件 32,019
组件总数 282,325
作者数 13,151
近 30 天安装 18,472
上周新增 2,069

组件分布

类型 数量 占比
Skills 161,540 57.2%
Commands 58,121 20.6%
Agents 48,012 17.0%
MCP Servers 7,159 2.5%
Hooks 6,723 2.4%

关键洞察： MCP Server 和 Hook 的占比分别只有 2.5% 和 2.4%——这两个集成点严重未被开发。对于插件开发者，这里意味着蓝海机会。

值得关注的 5 个顶级插件

🥇 superpowers（1,730 周安装 / 169K Stars）

强制 TDD 工作流，并行 Agent + Git Worktree + 批量验证。适合追求代码质量的团队。

🥈 caveman（787 周安装 / 47K Stars）

75% Token 节省——通过压缩通信模式降低 API 成本。适合高频使用 Claude Code 的创业团队。

🥉 everything-claude-code（295 周安装 / 169K Stars）

Maximalist 路线：48 个 Agent + 183 个 Skill + 79 个 Command，覆盖 20+ 技术栈。

andrej-karpathy-skills（102 周安装 / 90K Stars）

Karpathy 风格的编码规则，强制简洁性。证明聚焦单一理念的插件也能获得大量采用。

claude-hud（96 周安装 / 21K Stars）

实时 HUD 面板：上下文健康度、工具活动、Agent 状态、TODO 进度一目了然。

实战：发布你的第一个插件到团队

完整工作流

# 1. 开发并本地测试
claude --plugin-dir ./my-plugin

# 2. 打包
cd my-plugin && zip -r ../my-plugin-1.0.0.zip . && cd ..

# 3. 上传到制品库/对象存储
aws s3 cp my-plugin-1.0.0.zip s3://plugins.company.com/claude/my-plugin-1.0.0.zip

# 4. 队友一键加载
claude --plugin-url https://plugins.company.com/claude/my-plugin-1.0.0.zip

版本管理策略

my-plugin-1.0.0.zip   # 初始版本
my-plugin-1.0.1.zip   # Bug 修复 → 自动推送更新
my-plugin-1.1.0.zip   # 新增 Skill → 用户手动升级
my-plugin-2.0.0.zip   # 破坏性变更 → 需要迁移指南

插件系统只在 plugin.json 的 version 字段变化时才会通知用户更新。版本号就是你控制升级节奏的唯一杠杆。

AI 创业者的机会

1. 插件即产品

Claude Code 已有 13,151 名插件作者，但付费插件市场尚未形成。如果你能做出一个解决真实痛点的插件（比如 caveman 的 75% Token 节省），在免费阶段积累用户 → 企业版收费是完全可行的路径。

2. MCP + Hook 蓝海

7,159 个 MCP Server 和 6,723 个 Hook——在 32,019 插件总量中，这两个能连接外部系统的集成点只占 5%。做一个连接 Jira/Linear/飞书的 MCP Server 插件，就是找到了差异化定位。

3. 企业内部插件市场

大团队（50+ 开发者）共享一套 .claude/ 配置是天方夜谭。为企业构建内部 Claude Code 插件市场——统一管理、版本控制、权限审计——这是一个可以收年费的服务。

总结

Claude Code 插件系统从 Week 19 开始正式进入「可分发」时代。.zip 支持意味着你可以像发布 npm 包一样发布 Claude Code 能力，--plugin-url 则让"试用再安装"变得和 npx 一样简单。

今天就可以做的事：
1. 把你最常用的 .claude/commands/ 里的一个命令升级为插件
2. 打包成 ZIP，放到团队共享目录
3. 让队友用 claude --plugin-url 一行命令加载

从技能孤岛到生态共享，只需要一个 plugin.json 的距离。

数据来源：Claude Code Docs (code.claude.com)、ClaudePluginHub (claudepluginhub.com)

AI创业 #ClaudeCode #插件开发 #Agent工坊 #一人公司