Claude Code Plugin Forge Skill

A Claude Code skill for building, testing, and publishing Claude Code plugins — covering plugin structure, manifest configuration, skills development, marketplace integration, and automation workflows.

When to Use This Skill

Choose this skill when:

• Creating a new Claude Code plugin from scratch
• Structuring plugin skills, commands, and hooks
• Writing plugin manifests for marketplace publishing
• Building automation scripts for plugin development
• Testing plugins locally before distribution
• Managing plugin versioning and releases

Consider alternatives when:

• You need to build an MCP server (use the MCP builder skill)
• You need single slash commands without a plugin (use command creator)
• You need IDE extension development (use VS Code Extension API)

Quick Start

Copy
# Create a new plugin structure
mkdir my-plugin && cd my-plugin
mkdir -p skills commands hooks

# Create the plugin manifest
cat > plugin.json << 'EOF'
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A custom Claude Code plugin",
  "author": "Your Name",
  "skills": ["skills/*.md"],
  "commands": ["commands/*.md"],
  "hooks": ["hooks/*.json"]
}
EOF

Copy
# skills/code-optimizer.md
---
description: Optimize code for performance and readability
---

Analyze the provided code and suggest optimizations:
1. Identify performance bottlenecks
2. Suggest cleaner patterns
3. Apply the optimizations after user approval

Core Concepts

Plugin Directory Structure

Path	Purpose	Format
plugin.json	Plugin manifest with metadata	JSON
skills/*.md	Skill definitions with triggers	Markdown
commands/*.md	Slash command definitions	Markdown with frontmatter
hooks/*.json	Event hook configurations	JSON
README.md	Plugin documentation	Markdown
CHANGELOG.md	Version history	Markdown

Manifest Configuration

Copy
{
  "name": "code-quality",
  "version": "2.1.0",
  "description": "Automated code quality tools for Claude Code",
  "author": "Developer",
  "homepage": "https://github.com/user/code-quality-plugin",
  "license": "MIT",
  "skills": [
    "skills/lint-fix.md",
    "skills/refactor.md",
    "skills/test-generator.md"
  ],
  "commands": [
    "commands/review.md",
    "commands/optimize.md"
  ],
  "hooks": [
    "hooks/post-write.json"
  ],
  "settings": {
    "strictness": { "type": "string", "default": "standard", "description": "Lint strictness level" }
  }
}

Skill with Triggers

Copy
# skills/test-generator.md
---
description: Generate comprehensive test suites for code
triggers:
  - "generate tests"
  - "write tests"
  - "add test coverage"
---

Analyze the target code and generate a comprehensive test suite:

1. Read the source file and understand the public API
2. Generate unit tests covering:
   - Happy path for each exported function
   - Edge cases (null, empty, boundary values)
   - Error scenarios
3. Use the project's existing test framework and patterns
4. Place tests in the appropriate test directory

Configuration

Parameter	Type	Default	Description
name	string	—	Plugin identifier (required, kebab-case)
version	string	—	Semantic version (required)
description	string	—	Short plugin description
author	string	—	Plugin author name
license	string	"MIT"	License identifier
skills	array	[]	Glob patterns for skill files
commands	array	[]	Glob patterns for command files
hooks	array	[]	Glob patterns for hook config files
settings	object	{}	User-configurable settings schema

Best Practices

1. Keep each skill focused on one capability — a skill that does "lint, test, and deploy" should be three separate skills; focused skills are easier to trigger and compose.

2. Write descriptive trigger patterns — triggers determine when the skill activates; include common phrasings like "generate tests", "write tests", "add test coverage" for the same skill.

3. Include default settings with clear descriptions — every configurable option should have a sensible default and a description that explains what it controls and valid values.

4. Version your plugin with semantic versioning — bump the major version for breaking changes, minor for new features, and patch for bug fixes; users depend on version stability.

5. Test plugins locally before publishing — install the plugin locally with claude plugin add ./path-to-plugin and verify all skills, commands, and hooks work correctly.

Common Issues

Skill triggers don't activate — Triggers are matched against user messages; if triggers are too specific, they won't match natural language variations. Add multiple trigger phrases covering different ways users might request the skill.

Plugin settings not persisting — Settings are stored in .claude/plugin-name.local.md; verify the file path matches the plugin name and that the file is not in .gitignore.

Hook doesn't fire on expected events — Check the hook event name matches exactly (PreToolUse, PostToolUse, Notification, Stop) and the matcher regex matches the tool name you're targeting.