zhongwei/gh-joel611-claude-plugins-plugins-claude-plugin-builder
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 08:28:20 +08:00
commit 9e41b7cc0d
8 changed files with 745 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,11 @@
{
"name": "plugin-builder",
"description": "Helps create well-structured Claude Code plugins with skills, commands, and proper metadata following best practices",
"version": "1.0.0",
"author": {
"name": "Claude Code Marketplace"
},
"skills": [
"./skills"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# plugin-builder
Helps create well-structured Claude Code plugins with skills, commands, and proper metadata following best practices

61
plugin.lock.json Normal file
View File

@@ -0,0 +1,61 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:joel611/claude-plugins:plugins/claude/plugin-builder",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "42654ab92290c48c1201fea52e91c5df29037834",
"treeHash": "6db020c2be0e8fef2246353f4db6e1e439bf187e203861b4f95f5617aa6c5310",
"generatedAt": "2025-11-28T10:19:17.220216Z",
"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": "plugin-builder",
"description": "Helps create well-structured Claude Code plugins with skills, commands, and proper metadata following best practices",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "5aa01f4fc2cc3db5a6c60e292f8ce9f9f71d162db411c5b951f4bccff3f63bce"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "10fd847676ba1693273f5d474d4f20f43e040d846ba61432551a6585d5e6dd3e"
},
{
"path": "skills/plugin-builder/SKILL.md",
"sha256": "685b32ad42afff51ed583a1fc2e0ad2faaee4b0d7ec869975e732bd4d207276d"
},
{
"path": "skills/plugin-builder/resources/plugin-template.json",
"sha256": "ef6376d98c2b2e6bb5ec287df279b031515fa2e860b1b49ea1fee3170a5bbc7b"
},
{
"path": "skills/plugin-builder/resources/marketplace-entry.json",
"sha256": "d6f8cc6f7485a3bcb5fff61028a820a3d1e10d61ccc470ef629ae80c41fc63db"
},
{
"path": "skills/plugin-builder/resources/command-template.md",
"sha256": "58e6640b71e8e50c3ebef66057ec8647e4bb4215b0c3fc8118896cf5ce2116d3"
},
{
"path": "skills/plugin-builder/resources/skill-template.md",
"sha256": "ad25bbf021ac857bf8b724000e6ff2d1f73bb18a9388dd71a4471848010e064b"
}
],
"dirSha256": "6db020c2be0e8fef2246353f4db6e1e439bf187e203861b4f95f5617aa6c5310"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

513
skills/plugin-builder/SKILL.md Normal file
View File

@@ -0,0 +1,513 @@
# Plugin Builder Skill
## Purpose
This skill guides you through creating well-structured Claude Code plugins with all necessary components, following best practices for discoverability, maintainability, and user experience.
## When to Use
Use this skill when:
- Creating a new Claude Code plugin from scratch
- Adding components (skills, commands, agents, hooks) to existing plugins
- Generating properly structured SKILL.md files
- Setting up marketplace plugin registration
- Validating plugin metadata and structure
## Prerequisites
- Access to a Claude Code marketplace repository
- Understanding of the plugin's intended functionality
- Basic knowledge of JSON and Markdown formats
- Location of the marketplace root directory
## Plugin Architecture Overview
A Claude Code plugin follows this structure:
```
plugin-name/
├── .claude-plugin/
│ └── plugin.json # Required: Plugin metadata
├── skills/ # Optional: Agent Skills
│ └── skill-name/
│ ├── SKILL.md # Skill instructions
│ ├── scripts/ # Optional: Executable code
│ └── resources/ # Optional: Templates, data
├── commands/ # Optional: Custom slash commands
│ └── command-name.md
├── agents/ # Optional: Custom agent definitions
├── hooks/ # Optional: Event handlers
│ └── hooks.json
└── .mcp.json # Optional: MCP server configuration
```
## Instructions
### Step 1: Plan the Plugin
Before creating files, clarify:
1. **Plugin name** (use kebab-case: `my-plugin-name`)
2. **Purpose** (what problem does it solve?)
3. **Components needed** (skills, commands, agents, hooks?)
4. **Target users** (who will use this plugin?)
### Step 2: Create Plugin Directory Structure
1. Navigate to the marketplace `plugins/` directory
2. Create the plugin directory: `plugins/category/plugin-name/`
3. Create required subdirectories:
```bash
mkdir -p plugins/category/plugin-name/.claude-plugin
mkdir -p plugins/category/plugin-name/skills
mkdir -p plugins/category/plugin-name/commands # if needed
```
### Step 3: Generate plugin.json
Create `.claude-plugin/plugin.json` with this structure:
```json
{
"name": "plugin-name",
"description": "Clear, concise description of plugin functionality (1-2 sentences)",
"version": "1.0.0",
"author": {
"name": "Author Name",
"email": "author@example.com"
}
}
```
**Required fields:**
- `name`: Plugin identifier (kebab-case, no spaces)
- `description`: User-facing description (be specific about what it does)
- `version`: Semantic version (major.minor.patch)
- `author.name`: Author's name
**Version Guidelines:**
- Start with `1.0.0` for initial release
- Increment patch (1.0.1) for bug fixes
- Increment minor (1.1.0) for new features (backward compatible)
- Increment major (2.0.0) for breaking changes
### Step 4: Create Skills (if applicable)
For each skill in the plugin:
1. **Create skill directory:**
```bash
mkdir -p plugins/category/plugin-name/skills/skill-name
```
2. **Create SKILL.md** using progressive disclosure format:
```markdown
# Skill Name
## Purpose
[1-2 sentences: What this skill does and its main value]
## When to Use
[Bullet list of specific scenarios where this skill applies]
- Creating X
- Automating Y
- Solving Z problem
## Prerequisites
[What's needed before using this skill]
- Required tools or libraries
- Necessary permissions or access
- Context or information needed
## Instructions
### Task 1: [First Major Step]
[Detailed step-by-step instructions]
1. Do this first
2. Then do this
3. Finally do this
### Task 2: [Second Major Step]
[More detailed instructions]
[Continue with all major tasks...]
## Examples
### Example 1: [Concrete Use Case]
[Show complete example with actual code/commands]
\`\`\`language
[actual code]
\`\`\`
### Example 2: [Another Use Case]
[Another complete example]
## Best Practices
- [Specific practice 1]
- [Specific practice 2]
- [Specific practice 3]
## Common Issues
- **Problem:** [Description]
**Solution:** [How to fix]
- **Problem:** [Description]
**Solution:** [How to fix]
```
3. **Add optional resources:**
```bash
mkdir -p plugins/category/plugin-name/skills/skill-name/resources
mkdir -p plugins/category/plugin-name/skills/skill-name/scripts
```
**Skill Best Practices:**
- **Focus:** Each skill should do ONE thing well
- **Discoverability:** Use clear, searchable names and descriptions
- **Progressive disclosure:** Start with overview, then details, then examples
- **Actionable:** Provide concrete steps, not generic advice
- **Examples:** Include real, working examples users can adapt
- **Error handling:** Document common issues and solutions
### Step 5: Create Commands (if applicable)
For custom slash commands:
1. **Create command file:**
```bash
touch plugins/category/plugin-name/commands/command-name.md
```
2. **Write command markdown:**
```markdown
# Command Name
[Description of what this command does]
## Usage
/command-name [arguments]
## Examples
/command-name example-arg
## Parameters
- `arg1`: Description of first argument
- `arg2`: Description of second argument (optional)
## Instructions for Claude
[Detailed instructions for what Claude should do when this command is invoked]
1. Step 1
2. Step 2
3. Step 3
```
### Step 6: Update Marketplace Registry
1. **Open marketplace.json:**
Located at `.claude-plugin/marketplace.json` in the repository root
2. **Add plugin entry:**
```json
{
"name": "marketplace-name",
"plugins": [
{
"name": "plugin-name",
"source": "./plugins/category/plugin-name",
"description": "Plugin description"
}
]
}
```
**Important:** For local plugins, the `source` field must start with `./` to specify a relative path from the marketplace root.
### Step 7: Validate Plugin
**Checklist:**
- [ ] plugin.json exists and has all required fields
- [ ] Plugin name uses kebab-case (no spaces, lowercase with hyphens)
- [ ] Description is clear and specific
- [ ] Version follows semantic versioning (major.minor.patch)
- [ ] All SKILL.md files follow progressive disclosure format
- [ ] Examples are included in all SKILL.md files
- [ ] Commands have clear usage instructions
- [ ] Plugin is registered in marketplace.json
- [ ] File paths are correct and accessible
### Step 8: Test Locally
1. **Install the plugin locally:**
- User runs: `/plugin install plugin-name@marketplace-name`
2. **Test skill invocation:**
- Verify skills are discoverable
- Test with relevant prompts
- Check that instructions are clear
3. **Test commands:**
- Run each slash command
- Verify behavior matches documentation
4. **Iterate:**
- Fix any issues found
- Update documentation as needed
- Increment version number for changes
## Complete Examples
### Example 1: Creating a Data Validation Plugin
**Scenario:** Create a plugin that validates JSON schemas
**Step-by-step:**
1. **Create structure:**
```bash
mkdir -p plugins/data/json-validator/.claude-plugin
mkdir -p plugins/data/json-validator/skills/json-validator
```
2. **Create plugin.json:**
```json
{
"name": "json-validator",
"description": "Validates JSON data against schemas with detailed error reporting",
"version": "1.0.0",
"author": {
"name": "Data Team"
}
}
```
3. **Create SKILL.md:**
```markdown
# JSON Validator Skill
## Purpose
Validates JSON data against JSON Schema specifications and provides detailed error reports.
## When to Use
- Validating API request/response payloads
- Checking configuration files
- Ensuring data structure compliance
## Prerequisites
- JSON data to validate
- JSON Schema definition
- Understanding of JSON Schema syntax
## Instructions
### Validate JSON Data
1. Receive or locate the JSON data to validate
2. Receive or locate the JSON Schema
3. Parse both JSON data and schema
4. Validate data against schema
5. Report validation results with specific errors
6. Suggest fixes for validation errors
## Examples
### Example 1: Validate User Object
Schema:
\`\`\`json
{
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "number"}
},
"required": ["name"]
}
\`\`\`
Valid data:
\`\`\`json
{"name": "Alice", "age": 30}
\`\`\`
Invalid data:
\`\`\`json
{"age": 30}
\`\`\`
Error: Missing required property 'name'
## Best Practices
- Always show the full error path for nested objects
- Suggest corrected JSON when possible
- Validate schema itself before using it
- Handle common schema mistakes gracefully
## Common Issues
- **Problem:** Schema reference ($ref) not resolved
**Solution:** Ensure all referenced schemas are accessible
- **Problem:** Type coercion confusion
**Solution:** Be explicit about type expectations
```
4. **Update marketplace.json:**
```json
{
"plugins": [
{
"name": "json-validator",
"source": "./plugins/data/json-validator",
"description": "Validates JSON data against schemas"
}
]
}
```
### Example 2: Adding a Skill to Existing Plugin
**Scenario:** Add a new skill to the json-validator plugin
1. **Create new skill directory:**
```bash
mkdir -p plugins/data/json-validator/skills/schema-generator
```
2. **Create SKILL.md:**
```markdown
# Schema Generator Skill
## Purpose
Generates JSON Schema definitions from example JSON data.
## When to Use
- Creating schemas from existing data
- Documenting API data structures
- Reverse engineering schemas
[... rest of SKILL.md ...]
```
3. **Update plugin version:**
Edit `plugin.json`:
```json
{
"version": "1.1.0"
}
```
(Minor version increment for new feature)
## Naming Conventions
**Plugins:**
- Use kebab-case: `my-plugin-name`
- Be descriptive but concise
- Avoid generic names like "helper" or "utility"
- Good: `json-validator`, `code-formatter`, `api-tester`
- Bad: `helper`, `utils`, `my_plugin`
**Skills:**
- Use clear, action-oriented names
- Match the skill's primary function
- Good: `json-validator`, `schema-generator`, `data-transformer`
- Bad: `skill1`, `helper`, `misc`
**Commands:**
- Start with verb when possible
- Be specific about action
- Good: `validate-json`, `generate-schema`, `format-code`
- Bad: `do-thing`, `run`, `help`
## Best Practices Summary
### Plugin Design
- **Single responsibility:** Each plugin should have a clear, focused purpose
- **Composability:** Plugins should work well together
- **Discoverability:** Names and descriptions should make purpose obvious
- **Documentation:** Include examples for all features
- **Versioning:** Follow semantic versioning strictly
### Skill Design
- **Progressive disclosure:** Overview → Instructions → Examples
- **Concrete examples:** Show real code, not pseudocode
- **Error handling:** Document common issues and solutions
- **Prerequisites:** List what's needed upfront
- **Modularity:** Keep skills focused on specific tasks
### Testing
- **Local testing:** Always test before committing
- **User perspective:** Test as if you've never seen it before
- **Documentation:** Verify all examples work
- **Edge cases:** Test with unusual inputs
- **Integration:** Test with other plugins
### Maintenance
- **Version bump:** Update version for any changes
- **Changelog:** Document what changed and why
- **Backward compatibility:** Don't break existing users
- **Deprecation:** Warn before removing features
- **Updates:** Keep dependencies and references current
## Common Issues and Solutions
### Issue 1: Skill Not Being Discovered
**Problem:** Claude doesn't load the skill when relevant
**Solutions:**
- Check SKILL.md filename is exactly `SKILL.md` (case-sensitive)
- Verify skill directory path: `plugins/category/plugin/skills/skill-name/SKILL.md`
- Ensure plugin is registered in marketplace.json
- Check that skill name and description are descriptive
- Verify plugin is installed: `/plugin list`
### Issue 2: Invalid Plugin Metadata
**Problem:** Plugin fails to install or load
**Solutions:**
- Validate JSON syntax in plugin.json (no trailing commas, proper quotes)
- Ensure all required fields present: name, description, version, author.name
- Check name uses kebab-case with no spaces
- Verify version follows semantic versioning (X.Y.Z)
- Ensure file is named exactly `plugin.json`
### Issue 3: Command Not Working
**Problem:** Slash command doesn't execute
**Solutions:**
- Verify command file is in `commands/` directory
- Check filename matches command name
- Ensure markdown formatting is correct
- Verify plugin is installed and loaded
- Check command syntax matches documentation
### Issue 4: Marketplace Registration Failed
**Problem:** Plugin not showing in marketplace
**Solutions:**
- Verify marketplace.json syntax is valid
- Check plugin source path is correct relative to marketplace root
- Ensure plugin name in marketplace.json matches plugin.json
- Verify marketplace.json is in `.claude-plugin/` at repo root
### Issue 5: Version Conflicts
**Problem:** Multiple versions causing issues
**Solutions:**
- Use semantic versioning consistently
- Document breaking changes clearly
- Test compatibility with existing plugins
- Update marketplace.json with correct version
- Consider version deprecation strategy
## Resources
The plugin-builder includes templates in `skills/plugin-builder/resources/`:
- `plugin-template.json`: Starter plugin.json
- `skill-template.md`: SKILL.md boilerplate
- `command-template.md`: Command file structure
- `marketplace-entry.json`: Marketplace registration example
## Support
For plugin system documentation, see:
- Claude Code Plugins: https://docs.claude.com/en/docs/claude-code/plugins
- Agent Skills: https://docs.claude.com/en/docs/claude-code/skills
- Skills Best Practices: https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/best-practices

57
skills/plugin-builder/resources/command-template.md Normal file
View File

@@ -0,0 +1,57 @@
# Command Name
[Brief description of what this command does - 1-2 sentences]
## Usage
```
/command-name [required-arg] [optional-arg]
```
## Parameters
- `required-arg`: Description of the required argument and what it should be
- `optional-arg`: Description of optional argument (if any)
## Examples
### Example 1: Basic Usage
```
/command-name example-value
```
[Description of what happens]
### Example 2: Advanced Usage
```
/command-name example-value optional-value
```
[Description of what happens with optional argument]
## Instructions for Claude
When this command is invoked, you should:
1. [First action to take]
2. [Second action]
3. [Third action]
4. [Final action]
### Validation
Before executing:
- [Check this condition]
- [Verify that requirement]
### Error Handling
If [error condition]:
- [How to handle it]
If [another error]:
- [Resolution steps]
## Notes
- [Important note about usage]
- [Limitation or constraint]
- [Related commands or skills]

5
skills/plugin-builder/resources/marketplace-entry.json Normal file
View File

@@ -0,0 +1,5 @@
{
"name": "plugin-name",
"source": "./plugins/category/plugin-name",
"description": "Brief description of what the plugin does for marketplace listing"
}

9
skills/plugin-builder/resources/plugin-template.json Normal file
View File

@@ -0,0 +1,9 @@
{
"name": "plugin-name",
"description": "Clear, concise description of plugin functionality (1-2 sentences)",
"version": "1.0.0",
"author": {
"name": "Author Name",
"email": "author@example.com"
}
}

86
skills/plugin-builder/resources/skill-template.md Normal file
View File

@@ -0,0 +1,86 @@
# Skill Name
## Purpose
[1-2 sentences describing what this skill does and its main value proposition]
## When to Use
Use this skill when:
- [Specific scenario 1]
- [Specific scenario 2]
- [Specific scenario 3]
## Prerequisites
- [Required tool, library, or dependency]
- [Necessary permission or access]
- [Context or information needed]
## Instructions
### Step 1: [First Major Task]
[Detailed step-by-step instructions for the first major task]
1. [Specific action]
2. [Next action]
3. [Final action]
### Step 2: [Second Major Task]
[Detailed instructions for the second task]
1. [Action]
2. [Action]
[Continue with additional steps as needed...]
## Examples
### Example 1: [Concrete Use Case Name]
**Scenario:** [Brief description of the scenario]
**Input:**
```
[Example input data/code]
```
**Steps:**
1. [What to do]
2. [Next step]
**Output:**
```
[Expected output]
```
### Example 2: [Another Use Case]
[Another complete example showing different aspect of the skill]
## Best Practices
- [Specific practice related to this skill]
- [Another important practice]
- [Third practice]
- [Fourth practice]
## Common Issues
### Issue 1: [Problem Description]
**Problem:** [Detailed description of the issue]
**Solution:** [How to resolve it]
### Issue 2: [Another Problem]
**Problem:** [Description]
**Solution:** [Resolution steps]
## Additional Resources
- [Link to related documentation]
- [Reference to related skills]
- [External resources if applicable]