From 29a1b840c8e7d906d3f69333ad228c34e316aa1d Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 09:02:11 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 17 ++ README.md | 3 + agents/marketplace-manager.md | 292 +++++++++++++++++++++++++ agents/plugin-creator.md | 229 +++++++++++++++++++ commands/claude-plugin-validate-all.md | 140 ++++++++++++ commands/claude-plugin-validate.md | 102 +++++++++ plugin.lock.json | 57 +++++ 7 files changed, 840 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/marketplace-manager.md create mode 100644 agents/plugin-creator.md create mode 100644 commands/claude-plugin-validate-all.md create mode 100644 commands/claude-plugin-validate.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..abd0d1f --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b31afa6 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# claude-plugin-development + +Tools and agents for developing Claude Code plugins and marketplaces diff --git a/agents/marketplace-manager.md b/agents/marketplace-manager.md new file mode 100644 index 0000000..a08982d --- /dev/null +++ b/agents/marketplace-manager.md @@ -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. diff --git a/agents/plugin-creator.md b/agents/plugin-creator.md new file mode 100644 index 0000000..27953db --- /dev/null +++ b/agents/plugin-creator.md @@ -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. diff --git a/commands/claude-plugin-validate-all.md b/commands/claude-plugin-validate-all.md new file mode 100644 index 0000000..3646129 --- /dev/null +++ b/commands/claude-plugin-validate-all.md @@ -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 diff --git a/commands/claude-plugin-validate.md b/commands/claude-plugin-validate.md new file mode 100644 index 0000000..ad7b23f --- /dev/null +++ b/commands/claude-plugin-validate.md @@ -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 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..134c05f --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file