claude-plugin-creator

Claude Plugin Creator

Claude Code 插件创建指南。完整参考请参阅 references/plugins-reference.md。

第 1 步：确定要构建什么

向用户提出以下问题，以确定合适的方案：

问题 1：这是用于单个项目，还是要在多个项目／团队间共享？

• 单个项目 → 独立组件（.claude/ 目录）或技能
• 共享 → 插件

问题 2：Claude 应自动使用它，还是由用户显式调用？

• 自动使用（基于上下文）→ 技能（SKILL.md）
• 显式调用（/command）→ 命令（Markdown 文件）

问题 3：是否需要连接外部服务／API？

• 是 → MCP 服务（独立运行或置于插件内）
• 否 → 技能或命令

问题 4：是否应在事件发生时（文件保存、使用工具等）自动运行代码？

• 是 → hook
• 否 → 技能或命令

问题 5：是否需要使用自身系统提示词的专用 AI Agent？

• 是 → Agent
• 否 → 技能或命令

决策摘要

需求	方案	位置
个人使用、单个项目、自动触发	独立技能	.claude/skills/<name>/SKILL.md
个人使用、单个项目、由用户调用	独立命令	.claude/commands/<name>.md
共享、自动触发	含技能的插件	plugin/skills/<name>/SKILL.md
共享、由用户调用	含命令的插件	plugin/commands/<name>.md
外部 API 访问	MCP 服务	.mcp.json（独立运行或置于插件内）
事件自动化	Hook	hooks/hooks.json（独立运行或置于插件内）
专用 AI 角色	Agent	agents/<name>.md
以上多项	组合多个组件的插件	请参阅下方的插件结构

范围：谁可以访问？

范围	文件	可见性
user	~/.claude/settings.json	仅你可用，适用于所有项目
project	.claude/settings.json	团队成员通过 git 使用，适用于此项目
local	.claude/settings.local.json	仅你可用，适用于此项目（被 git 忽略）
managed	管理员控制	组织范围内，只读

第 2 步：创建插件

目录结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # Only this file goes here
├── skills/                   # Auto-triggered by context
│   └── skill-name/
│       └── SKILL.md
├── commands/                 # User-invoked via /plugin:command
│   └── command-name.md
├── agents/                   # Specialized subagents
│   └── agent-name.md
├── hooks/
│   └── hooks.json            # Event handlers
├── bin/                      # Executables added to PATH
├── settings.json             # Default settings
├── .mcp.json                 # MCP server configs
└── .lsp.json                 # LSP server configs

重要规则：

• 组件放在插件根目录，而不是 .claude-plugin/ 内
• 插件名称必须使用 kebab-case
• 技能文件必须命名为 SKILL.md（大小写必须完全一致）

plugin.json（最简）

{
  "name": "my-plugin",
  "description": "What the plugin does",
  "version": "1.0.0"
}

plugin.json（完整）

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What the plugin does",
  "author": { "name": "Name", "email": "[email protected]" },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/user/plugin",
  "license": "MIT",
  "keywords": ["keyword1"],
  "userConfig": {
    "api_key": { "description": "API key", "sensitive": true }
  }
}

用户配置值可在配置中通过 ${user_config.KEY} 使用，也可作为 CLAUDE_PLUGIN_OPTION_<KEY> 环境变量使用。

技能（SKILL.md）

---
name: skill-name
description: What it does. Use when [trigger phrases].
---

Instructions for Claude.

命令（commands/name.md）

---
description: What it does
disable-model-invocation: true
---

Instructions. User input: $ARGUMENTS

Agent（agents/name.md）

---
name: agent-name
description: What it specializes in
model: sonnet
maxTurns: 20
---

System prompt here.

Hook（hooks/hooks.json）

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

MCP 服务（.mcp.json）

{
  "mcpServers": {
    "server-name": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

第 3 步：测试

claude --plugin-dir ./my-plugin

在会话中，完成更改后运行 /reload-plugins。验证：claude plugin validate .

第 4 步：分发

方案 A：Marketplace（适用于团队／社区）

在 Marketplace 仓库中创建 .claude-plugin/marketplace.json：

{
  "name": "marketplace-name",
  "owner": { "name": "Team Name" },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "What it does",
      "version": "1.0.0"
    }
  ]
}

插件源可以是：相对路径（"./plugins/x"）、GitHub（{ "source": "github", "repo": "owner/repo" }）、git URL、git 子目录或 npm 包。

托管在 GitHub 上，然后运行以下命令添加：/plugin marketplace add owner/repo

方案 B：直接共享

在 GitHub 上托管插件目录。用户可以通过 --plugin-dir 安装，或将其添加到自己的 .claude/ 配置中。

方案 C：团队自动安装

添加到项目的 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "team-tools": { "source": { "source": "github", "repo": "org/plugins" } }
  },
  "enabledPlugins": { "my-plugin@team-tools": true }
}

方案 D：官方 Marketplace

通过 claude.ai/settings/plugins/submit 或 platform.claude.com/plugins/submit 提交。

将独立组件转换为插件

1. mkdir -p my-plugin/.claude-plugin
2. 创建包含名称的 plugin.json
3. 复制 .claude/commands/ → my-plugin/commands/
4. 复制 .claude/skills/ → my-plugin/skills/
5. 复制 .claude/agents/ → my-plugin/agents/
6. 将 hooks 从 settings.json 移至 my-plugin/hooks/hooks.json
7. 测试：claude --plugin-dir ./my-plugin

插件中的环境变量

• ${CLAUDE_PLUGIN_ROOT} — 插件安装路径（更新时会变化）
• ${CLAUDE_PLUGIN_DATA} — 持久数据路径（更新后仍会保留）