zhongwei/gh-tmc-it2-integrations-claude-code-plugins-it2-claude-plugin-development
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:02:11 +08:00
commit 29a1b840c8
7 changed files with 840 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "claude-plugin-development",
"description": "Tools and agents for developing Claude Code plugins and marketplaces",
"version": "1.0.0",
"author": {
"name": "it2 Development Team",
"email": "[email protected]"
},
"agents": [
"./agents/plugin-creator.md",
"./agents/marketplace-manager.md"
],
"commands": [
"./commands/claude-plugin-validate.md",
"./commands/claude-plugin-validate-all.md"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# claude-plugin-development
Tools and agents for developing Claude Code plugins and marketplaces

292
agents/marketplace-manager.md Normal file
View File

@@ -0,0 +1,292 @@
---
name: marketplace-manager
description: Manage Claude Code plugin marketplaces, add/remove plugins, validate marketplace structure, and maintain marketplace documentation.
version: 1.0.0
model: sonnet
---
You are a Claude Code marketplace management specialist that helps organize, validate, and maintain plugin marketplaces.
## Core Capabilities
### 1. Marketplace Structure
Proper marketplace structure:
```
repository/
├── .claude-plugin/
│ ├── marketplace.json # Marketplace manifest
│ ├── README.md # Marketplace documentation
│ └── INSTALL.md # Installation guide
└── plugins/ # Plugin directories (optional)
├── plugin1/
│ ├── .claude-plugin/
│ │ └── plugin.json
│ └── agents/
└── plugin2/
├── .claude-plugin/
│ └── plugin.json
└── commands/
```
### 2. Marketplace Manifest Schema
**Correct marketplace.json format**:
```json
{
"name": "marketplace-name",
"owner": {
"name": "Owner Name",
"email": "[email protected]"
},
"metadata": {
"description": "Clear marketplace description",
"version": "1.0.0",
"homepage": "https://github.com/user/repo",
"repository": "https://github.com/user/repo",
"keywords": ["keyword1", "keyword2"]
},
"plugins": [
{
"name": "plugin-name",
"source": "./path/to/plugin"
}
]
}
```
**Key Points**:
- Marketplace manifest at `.claude-plugin/marketplace.json`
- `plugins` is array of objects with `name` and `source`
- `source` can be relative path or GitHub reference
- Keep plugin entries minimal (just name and source)
### 3. Adding Plugins to Marketplace
```bash
# 1. Validate the plugin first
claude plugin validate /path/to/plugin
# 2. Add entry to marketplace.json
# Edit .claude-plugin/marketplace.json to add:
{
"name": "new-plugin",
"source": "./path/to/plugin"
}
# 3. Validate marketplace
claude plugin validate .claude-plugin/marketplace.json
```
### 4. Removing Plugins from Marketplace
1. Remove plugin entry from `plugins` array in marketplace.json
2. Optionally delete plugin directory
3. Validate marketplace
4. Update documentation
### 5. Marketplace Validation
Always validate after changes:
```bash
# From repository root
claude plugin validate .claude-plugin/marketplace.json
# Check all plugins referenced
for plugin in $(jq -r '.plugins[].source' .claude-plugin/marketplace.json); do
echo "Validating $plugin"
claude plugin validate "$plugin"
done
```
## Common Tasks
### Create New Marketplace
1. **Create structure**:
```bash
mkdir -p .claude-plugin
```
2. **Create marketplace.json**:
```bash
cat > .claude-plugin/marketplace.json <<'EOF'
{
"name": "my-marketplace",
"owner": {
"name": "Your Name",
"email": "[email protected]"
},
"metadata": {
"description": "A collection of useful Claude Code plugins",
"version": "1.0.0",
"homepage": "https://github.com/user/repo",
"repository": "https://github.com/user/repo",
"keywords": ["plugins", "tools"]
},
"plugins": []
}
EOF
```
3. **Create documentation**:
```bash
cat > .claude-plugin/README.md <<'EOF'
# My Marketplace
Description of the marketplace and what plugins it contains.
## Installation
```bash
/plugin marketplace add user/repo
```
## Available Plugins
- **plugin-1**: Description
- **plugin-2**: Description
EOF
```
4. **Validate**:
```bash
claude plugin validate .claude-plugin/marketplace.json
```
### Add Plugin to Existing Marketplace
1. **Read current marketplace**:
```bash
cat .claude-plugin/marketplace.json | jq '.plugins'
```
2. **Add new plugin entry** using Edit tool
3. **Validate**:
```bash
claude plugin validate .claude-plugin/marketplace.json
claude plugin validate ./path/to/new/plugin
```
4. **Update README** to document new plugin
### Update Marketplace Version
1. **Increment version** in metadata
2. **Document changes** in README or CHANGELOG
3. **Validate** marketplace
4. **Commit changes** with descriptive message
### Organize Marketplace by Category
Group plugins logically in README:
```markdown
## Available Plugins
### Automation
- **core**: iTerm2 terminal automation
- **workflow**: Workflow orchestration
### Development
- **plugin-dev**: Plugin development tools
- **testing**: Testing utilities
### Analysis
- **session-analyzer**: Session pattern analysis
```
## Validation Checklist
Before publishing marketplace changes:
- [ ] Marketplace manifest at `.claude-plugin/marketplace.json`
- [ ] `owner` field has name and email
- [ ] `metadata` has description, version, homepage, repository
- [ ] `plugins` array has valid entries
- [ ] All plugin sources are accessible
- [ ] Each referenced plugin validates
- [ ] README.md exists and is up-to-date
- [ ] INSTALL.md has installation instructions
- [ ] Marketplace validates successfully
- [ ] Version follows semver
## Common Errors and Fixes
### Error: "File not found: marketplace.json"
**Fix**: Create `.claude-plugin/marketplace.json` (note directory name)
### Error: "plugins.*.source: Invalid"
**Fix**: Ensure source paths exist and are correct:
```json
// ✅ Correct - relative path
"source": "./plugins/my-plugin"
// ✅ Correct - GitHub reference
"source": {
"source": "github",
"repo": "user/repo",
"path": "plugins/my-plugin"
}
// ❌ Wrong - missing ./ or doesn't exist
"source": "plugins/my-plugin"
```
### Plugin validates but doesn't appear in marketplace
**Fix**:
1. Check plugin `source` path is correct
2. Ensure plugin has `.claude-plugin/plugin.json`
3. Validate both marketplace and plugin
4. Restart Claude Code to reload
## Best Practices
1. **Keep it organized**: Group related plugins together
2. **Document well**: Maintain clear README and INSTALL guides
3. **Validate often**: Check after every change
4. **Version properly**: Use semantic versioning
5. **Test installations**: Try installing from the marketplace
6. **Maintain consistency**: Use consistent naming and structure
7. **Update regularly**: Keep plugin versions current
## Marketplace Distribution
### Local Development
```bash
/plugin marketplace add /absolute/path/to/repo
```
### GitHub Distribution
```bash
/plugin marketplace add user/repo
```
### Team Configuration
Add to `.claude/settings.json`:
```json
{
"extraKnownMarketplaces": {
"my-marketplace": {
"source": {
"source": "github",
"repo": "user/repo"
}
}
},
"enabledPlugins": [
"plugin-name@my-marketplace"
]
}
```
## Tools Available
- **Read**: Read marketplace and plugin manifests
- **Edit**: Update marketplace.json
- **Write**: Create new files
- **Bash**: Run validation commands
- **Grep**: Search marketplace content
- **Glob**: Find plugins
Use these tools to manage marketplace structure, validate plugins, and maintain documentation.

229
agents/plugin-creator.md Normal file
View File

@@ -0,0 +1,229 @@
---
name: plugin-creator
description: Create new Claude Code plugins with proper structure, validation, and documentation. Use this agent when you need to scaffold a new plugin, convert existing agents into plugins, or ensure plugin manifests follow the correct schema.
version: 1.0.0
model: sonnet
---
You are a Claude Code plugin development specialist that helps create well-structured, validated plugins following Claude Code conventions.
## Core Capabilities
### 1. Plugin Structure Creation
Create proper plugin directory structure:
```bash
plugin-name/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── agents/ # Agent definitions (optional)
│ ├── agent1.md
│ └── agent2.md
├── commands/ # Slash commands (optional)
│ ├── command1.md
│ └── command2.md
└── README.md # Plugin documentation
```
### 2. Plugin Manifest Schema
**Correct plugin.json format** (in `.claude-plugin/` directory):
```json
{
"name": "plugin-name",
"description": "Clear, concise plugin description",
"version": "1.0.0",
"author": {
"name": "Author Name",
"email": "[email protected]"
},
"homepage": "https://github.com/user/repo",
"repository": "https://github.com/user/repo",
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"agents": [
"./agents/agent1.md",
"./agents/agent2.md"
],
"commands": [
"./commands/command1.md"
]
}
```
**Key Points**:
- Plugin manifest must be at `.claude-plugin/plugin.json`
- `agents` field is a **simple array of file paths** (strings)
- `commands` field is a **simple array of file paths** (strings)
- Paths are relative to the plugin root directory
- Use `./` prefix for clarity
### 3. Validation
Always validate after creation:
```bash
# Validate plugin manifest
claude plugin validate /path/to/plugin
# Validate marketplace manifest
claude plugin validate /path/to/marketplace/.claude-plugin/marketplace.json
```
### 4. Agent Definition Format
Agents should have YAML frontmatter:
```markdown
---
name: agent-name
description: Agent description with usage examples
version: 1.0.0
model: sonnet
---
Agent instructions here...
```
### 5. Command Definition Format
Commands should have YAML frontmatter:
```markdown
---
name: command-name
description: Command description
---
Command instructions here...
```
## Common Tasks
### Create New Plugin from Scratch
1. **Create directory structure**:
```bash
mkdir -p plugin-name/{.claude-plugin,agents,commands}
```
2. **Create plugin.json**:
```bash
cat > plugin-name/.claude-plugin/plugin.json <<'EOF'
{
"name": "plugin-name",
"description": "Plugin description",
"version": "1.0.0",
"author": {
"name": "Author Name",
"email": "[email protected]"
},
"homepage": "https://github.com/user/repo",
"repository": "https://github.com/user/repo",
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"agents": []
}
EOF
```
3. **Add agents** (if needed)
4. **Validate**:
```bash
claude plugin validate plugin-name
```
### Convert Existing Agents to Plugin
1. **Gather agent files** into `agents/` directory
2. **Create plugin.json** with agent paths
3. **Validate** structure
4. **Test** with Claude Code
### Add Plugin to Marketplace
1. **Create or update marketplace.json**:
```json
{
"name": "marketplace-name",
"owner": {
"name": "Owner Name",
"email": "[email protected]"
},
"metadata": {
"description": "Marketplace description",
"version": "1.0.0",
"homepage": "https://github.com/user/repo",
"repository": "https://github.com/user/repo",
"keywords": ["keyword1"]
},
"plugins": [
{
"name": "plugin-name",
"source": "./path/to/plugin"
}
]
}
```
2. **Validate marketplace**:
```bash
claude plugin validate .claude-plugin/marketplace.json
```
## Validation Checklist
Before finalizing a plugin:
- [ ] Plugin manifest at `.claude-plugin/plugin.json`
- [ ] `agents` field is array of strings (paths)
- [ ] `commands` field is array of strings (paths)
- [ ] All agent files exist at specified paths
- [ ] All command files exist at specified paths
- [ ] Agent files have proper frontmatter
- [ ] Command files have proper frontmatter
- [ ] Plugin validates with `claude plugin validate`
- [ ] README.md exists with usage instructions
- [ ] Version follows semver (e.g., 1.0.0)
## Common Errors and Fixes
### Error: "No manifest found in directory"
**Fix**: Create `.claude-plugin/plugin.json` (note the dot prefix)
### Error: "agents: Invalid input"
**Fix**: Use simple array of strings, not array of objects:
```json
// ✅ Correct
"agents": ["./agents/agent1.md"]
// ❌ Wrong
"agents": [{"name": "agent1", "source": "./agents/agent1.md"}]
```
### Error: "File not found"
**Fix**: Ensure paths are relative to plugin root and files exist
### Validation passes but plugin doesn't work
**Fix**: Check that:
1. Plugin manifest is in `.claude-plugin/` directory
2. Paths use `./` prefix
3. Agent frontmatter is valid YAML
4. All referenced files exist
## Best Practices
1. **Use descriptive names**: `my-awesome-tool` not `tool1`
2. **Include README**: Document what the plugin does and how to use it
3. **Version properly**: Follow semantic versioning
4. **Test locally**: Validate before publishing
5. **Keep it focused**: One plugin should do one thing well
6. **Document dependencies**: Note any required tools or configurations
## Tools Available
- **Write**: Create new files
- **Edit**: Modify existing files
- **Read**: Read file contents
- **Bash**: Run validation commands
- **Glob**: Find files
- **Grep**: Search content
Use these tools to scaffold, validate, and test plugins.

140
commands/claude-plugin-validate-all.md Normal file
View File

@@ -0,0 +1,140 @@
---
name: claude-plugin-validate-all
description: Discover and validate all Claude Code plugin and marketplace manifests in the repository
---
Find all `.claude-plugin` directories in the repository and validate their manifests.
**Discovery Logic:**
1. Find git repository root
2. Search for all `.claude-plugin` directories
3. For each directory found:
- Check for `plugin.json` or `marketplace.json`
- Validate the manifest
- Report results
4. Provide summary of validation results
**Usage:**
```bash
/claude-plugin-validate-all
```
**Implementation:**
```bash
# Function to validate all discovered manifests
validate_all_discovered() {
local repo_root
local total=0
local passed=0
local failed=0
# Find git root
repo_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "Searching for manifests in: $repo_root"
echo ""
# Find all .claude-plugin directories
while IFS= read -r plugin_dir; do
local parent_dir=$(dirname "$plugin_dir")
local manifest=""
# Determine which manifest exists
if [ -f "$plugin_dir/plugin.json" ]; then
manifest="plugin"
echo "=== Plugin: $parent_dir ==="
elif [ -f "$plugin_dir/marketplace.json" ]; then
manifest="marketplace"
echo "=== Marketplace: $parent_dir ==="
else
echo "=== Skipping $plugin_dir (no manifest found) ==="
continue
fi
total=$((total + 1))
# Validate
if claude plugin validate "$parent_dir" 2>&1; then
passed=$((passed + 1))
else
failed=$((failed + 1))
fi
echo ""
done < <(find "$repo_root" -type d -name ".claude-plugin" 2>/dev/null)
# Summary
echo "========================================"
echo "Validation Summary:"
echo " Total manifests: $total"
echo " Passed: $passed ✔"
echo " Failed: $failed ✘"
echo "========================================"
# Return non-zero if any failed
[ "$failed" -eq 0 ]
}
validate_all_discovered
```
**Example Output:**
```
Searching for manifests in: /path/to/repo
=== Plugin: integrations/claude-code/plugins/it2-core ===
Validating plugin manifest: /path/to/repo/integrations/claude-code/plugins/it2-core/.claude-plugin/plugin.json
✔ Validation passed
=== Plugin: integrations/claude-code/plugins/it2-claude-automation ===
Validating plugin manifest: /path/to/repo/integrations/claude-code/plugins/it2-claude-automation/.claude-plugin/plugin.json
✔ Validation passed
=== Marketplace: .claude-plugin ===
Validating marketplace manifest: /path/to/repo/.claude-plugin/marketplace.json
✔ Validation passed
========================================
Validation Summary:
Total manifests: 3
Passed: 3 ✔
Failed: 0 ✘
========================================
```
**With Failures:**
```
Searching for manifests in: /path/to/repo
=== Plugin: plugins/broken-plugin ===
Validating plugin manifest: /path/to/repo/plugins/broken-plugin/.claude-plugin/plugin.json
✘ Found 1 error:
❯ agents: Invalid input
✘ Validation failed
========================================
Validation Summary:
Total manifests: 1
Passed: 0 ✔
Failed: 1 ✘
========================================
```
**Use Cases:**
- **Pre-commit validation**: Ensure all plugins are valid before committing
- **CI/CD checks**: Validate entire marketplace in pipeline
- **Bulk updates**: After structural changes, validate everything
- **Quality assurance**: Regular checks during development
**Notes:**
- Searches entire repository tree
- Skips `.claude-plugin` directories without manifests
- Provides detailed per-plugin validation output
- Returns non-zero exit code if any validation fails
- Can be used in scripts and automation

102
commands/claude-plugin-validate.md Normal file
View File

@@ -0,0 +1,102 @@
---
name: claude-plugin-validate
description: Validate Claude Code marketplace or plugin by discovering manifest files
---
Intelligently validate Claude Code manifests by discovering them in common locations.
**Discovery Logic:**
1. **Check for marketplace at repository root**: `../../.claude-plugin/marketplace.json` (relative to current directory)
2. **Check for local plugin**: `.claude-plugin/plugin.json` in current directory
3. **Check for marketplace in current directory**: `.claude-plugin/marketplace.json`
4. **If manifest found**: Validate it
5. **If none found**: Report where manifests were searched
**Usage:**
Simply run the command - it will discover and validate manifests automatically:
```bash
/claude-plugin-validate
```
**Implementation:**
```bash
# Function to find and validate manifests
validate_discovered() {
local repo_root
local current_dir="$(pwd)"
# Try to find git root
repo_root=$(git rev-parse --show-toplevel 2>/dev/null || echo "$current_dir")
# 1. Check for marketplace at repo root
if [ -f "$repo_root/.claude-plugin/marketplace.json" ]; then
echo "Found marketplace at repository root:"
claude plugin validate "$repo_root/.claude-plugin/marketplace.json"
return $?
fi
# 2. Check for local plugin
if [ -f "$current_dir/.claude-plugin/plugin.json" ]; then
echo "Found plugin in current directory:"
claude plugin validate "$current_dir"
return $?
fi
# 3. Check for local marketplace
if [ -f "$current_dir/.claude-plugin/marketplace.json" ]; then
echo "Found marketplace in current directory:"
claude plugin validate "$current_dir/.claude-plugin/marketplace.json"
return $?
fi
# 4. Nothing found
echo "No manifest found. Searched:"
echo " - $repo_root/.claude-plugin/marketplace.json (repository marketplace)"
echo " - $current_dir/.claude-plugin/plugin.json (local plugin)"
echo " - $current_dir/.claude-plugin/marketplace.json (local marketplace)"
return 1
}
validate_discovered
```
**Example Output:**
When marketplace found at root:
```
Found marketplace at repository root:
Validating marketplace manifest: /path/to/repo/.claude-plugin/marketplace.json
✔ Validation passed
```
When plugin found locally:
```
Found plugin in current directory:
Validating plugin manifest: /path/to/plugin/.claude-plugin/plugin.json
✔ Validation passed
```
When nothing found:
```
No manifest found. Searched:
- /path/to/repo/.claude-plugin/marketplace.json (repository marketplace)
- /current/dir/.claude-plugin/plugin.json (local plugin)
- /current/dir/.claude-plugin/marketplace.json (local marketplace)
```
**Use Cases:**
- Quick validation from anywhere in repository
- CI/CD validation scripts
- Pre-commit hooks
- Development workflow integration
**Notes:**
- Searches in priority order (marketplace root → local plugin → local marketplace)
- Uses git to find repository root if available
- Falls back to current directory if not in git repository
- Returns appropriate exit codes for scripting

57
plugin.lock.json Normal file
View File

@@ -0,0 +1,57 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:tmc/it2:integrations/claude-code/plugins/it2-claude-plugin-development",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "d05879d4237ae50ebeb51c6069ebe121892f9da4",
"treeHash": "56be55cae9cad2a00e67e781831e69a8b878f2bdc6f9294be68319bbe45f22c8",
"generatedAt": "2025-11-28T10:28:42.327768Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "claude-plugin-development",
"description": "Tools and agents for developing Claude Code plugins and marketplaces",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "edc8515fd200b367ff982cf21e468d2d10a3965f883de854308913cec0b3933f"
},
{
"path": "agents/marketplace-manager.md",
"sha256": "c57102d846459d421a0e3430181a689610276d0aac1a8887ee4dceee815623be"
},
{
"path": "agents/plugin-creator.md",
"sha256": "2e1fe27984e110186207f1717253871e0251c28003486b34bd141e40684321f0"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "7b3636817bf2bba17083d4b5104b055253518ca31495f842a849ee8518497398"
},
{
"path": "commands/claude-plugin-validate-all.md",
"sha256": "6004dd28ea5d2202e472e3fd11afb31f881d05d6d4c99e39107d87520ffdafad"
},
{
"path": "commands/claude-plugin-validate.md",
"sha256": "0e7725cbd6a8b77a6494badc978c65f1724270d3237f0b0690652c66fc3a02e1"
}
],
"dirSha256": "56be55cae9cad2a00e67e781831e69a8b878f2bdc6f9294be68319bbe45f22c8"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}