plugin-forge

CC Plugin Forge

用途

以正確的結構、清單與市集整合來建置與管理 Claude Code 外掛。包含工作流程、自動化腳本與參考文件。

使用時機

• 為市集建立新外掛
• 新增或修改外掛元件（指令、技能、代理、鉤子）
• 更新外掛版本
• 處理外掛或市集清單
• 設定本機外掛測試
• 發布外掛

快速入門

建立新外掛

使用 create_plugin.py 產生外掛結構：

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

此指令會自動：

• 建立外掛目錄結構
• 產生 plugin.json 清單
• 建立 README 範本
• 更新 marketplace.json

更新版本

使用 bump_version.py 同時更新兩個清單中的版本：

python scripts/bump_version.py plugin-name major|minor|patch \
  --marketplace-root /path/to/marketplace

語意化版本：

• major：重大變更（1.0.0 → 2.0.0）
• minor：新功能、重構（1.0.0 → 1.1.0）
• patch：錯誤修正、文件（1.0.0 → 1.0.1）

開發工作流程

1. 建立結構

手動方式（若不使用腳本）：

mkdir -p plugins/plugin-name/.claude-plugin
mkdir -p plugins/plugin-name/commands
mkdir -p plugins/plugin-name/skills

2. 外掛清單

檔案：plugins/plugin-name/.claude-plugin/plugin.json

{
  "name": "plugin-name",
  "version": "0.1.0",
  "description": "Plugin description",
  "author": {
    "name": "Your Name",
    "email": "your.email@example.com"
  },
  "keywords": ["keyword1", "keyword2"]
}

3. 註冊至市集

更新 .claude-plugin/marketplace.json：

{
  "name": "plugin-name",
  "source": "./plugins/plugin-name",
  "description": "Plugin description",
  "version": "0.1.0",
  "keywords": ["keyword1", "keyword2"],
  "category": "productivity"
}

4. 新增元件

在對應目錄中建立：

元件	位置	格式
指令	commands/	含 frontmatter 的 Markdown
技能	skills/<name>/	目錄內含 SKILL.md
代理	agents/	Markdown 定義
鉤子	hooks/hooks.json	事件處理器
MCP 伺服器	.mcp.json	外部整合

5. 本機測試

# 新增市集
/plugin marketplace add /path/to/marketplace-root

# 安裝外掛
/plugin install plugin-name@marketplace-name

# 變更後重新安裝
/plugin uninstall plugin-name@marketplace-name
/plugin install plugin-name@marketplace-name

外掛模式

框架外掛

針對特定框架（React、Vue 等）的指引：

plugins/framework-name/
├── .claude-plugin/plugin.json
├── skills/
│   └── framework-name/
│       ├── SKILL.md
│       └── references/
├── commands/
│   └── prime/
│       ├── components.md
│       └── framework.md
└── README.md

工具外掛

用於工具與指令：

plugins/utility-name/
├── .claude-plugin/plugin.json
├── commands/
│   ├── action1.md
│   └── action2.md
└── README.md

領域外掛

用於特定領域知識：

plugins/domain-name/
├── .claude-plugin/plugin.json
├── skills/
│   └── domain-name/
│       ├── SKILL.md
│       ├── references/
│       └── scripts/
└── README.md

指令命名

以子目錄為基礎的命名空間，使用 : 分隔：

• commands/namespace/command.md → /namespace:command
• commands/simple.md → /simple

範例：

• commands/prime/vue.md → /prime:vue
• commands/docs/generate.md → /docs:generate

版本管理

重要： 必須同時更新兩個位置的版本：

1. plugins/<name>/.claude-plugin/plugin.json
2. .claude-plugin/marketplace.json

使用 bump_version.py 自動化處理。

Git 提交

使用 Conventional Commits：

git commit -m "feat: add new plugin"
git commit -m "fix: correct plugin manifest"
git commit -m "docs: update plugin README"
git commit -m "feat!: breaking change"

參考文件

內含詳細文件：

參考文件	內容
references/plugin-structure.md	目錄結構、清單結構、元件
references/marketplace-schema.md	市集格式、外掛條目、發布
references/workflows.md	逐步工作流程、模式、發布

腳本

腳本	用途
scripts/create_plugin.py	建立新外掛骨架
scripts/bump_version.py	更新版本