plugin-creator

Plugin Creator

This skill provides guidance for creating high-quality plugins for the fx/cc Claude Code marketplace.

About fx/cc Plugins

Plugins are structured packages that extend Claude Code's capabilities by bundling related components:

• Skills - Auto-invoked specialized knowledge and workflows (can also be used as sub-agent types for autonomous multi-step operations)
• Commands - Slash commands for specific operations
• Hooks - Event-driven workflow automation

Default Working Directory

All plugin development work defaults to: ~/.claude/plugins/marketplaces/fx-cc/

This is the local clone of the fx/cc marketplace repository where all plugins reside.

Plugin Creation Process

Step 1: Understanding the Plugin with Concrete Examples

To create an effective plugin, gather concrete examples of how it will be used:

Example questions to ask:

• "What functionality should this plugin provide?"
• "Can you give examples of tasks users would perform with this plugin?"
• "What would trigger each component (skills, commands)?"
• "Are these components typically used together or separately?"

Example for fx-git plugin:

• User: "Help me write better commit messages following our conventions"
• User: "Review this PR for code quality issues"
• User: "Resolve these merge conflicts"

Conclude when there's a clear understanding of:

1. Plugin's domain and purpose
2. Required components (skills, commands)
3. Typical usage patterns

Step 2: Planning Plugin Structure

Analyze examples to determine:

1. Plugin Name

Follow fx/cc naming conventions (see references/fx-cc-guidelines.md):

• Use fx- prefix
• Kebab-case format
• Concise and descriptive
• Examples: fx-git, fx-aws, fx-docs

2. Component Grouping

Decide whether to:

• Combine related components in one plugin (typically used together)
• Separate into multiple plugins (different domains or install preferences)

3. Required Components

Skills - When to include:

• Auto-invoked specialized knowledge needed
• Procedural workflows for specific tasks
• Domain expertise that should trigger automatically
• Complex multi-step autonomous operations (skills can serve as sub-agent types)

Commands - When to include:

• Explicit user-triggered operations
• Shortcuts for common workflows
• Integration with external tools/APIs

Hooks - When to include:

• Event-driven automation needs
• Pre/post-processing requirements
• Workflow customization

Step 3: Initialize Plugin Structure

Navigate to the fx/cc marketplace and create plugin directory:

cd ~/.claude/plugins/marketplaces/fx-cc/plugins

# Create plugin directory structure
mkdir -p fx-plugin-name/.claude-plugin

# Create plugin.json manifest
cat > fx-plugin-name/.claude-plugin/plugin.json <<'EOF'
{
  "name": "fx-plugin-name",
  "version": "0.1.0",
  "description": "Clear description of what this plugin does"
}
EOF

# Create component directories as needed
cd fx-plugin-name
mkdir -p skills commands hooks

Directory structure:

~/.claude/plugins/marketplaces/fx-cc/plugins/fx-plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── skills/          (if needed)
├── commands/        (if needed)
├── hooks/           (if needed)
└── README.md

Step 4: Implement Components

Skills

Create skill directories with SKILL.md:

mkdir -p skills/skill-name
cat > skills/skill-name/SKILL.md <<'EOF'
---
name: skill-name
description: When this skill should be used (third-person, specific)
---

# Skill Name

Instructions using imperative/infinitive form.

## Usage

How to use this skill and reference bundled resources.
EOF

See skill-creator skill for detailed skill development guidance.

Commands

Create command files (markdown or shell):

# Markdown command
cat > commands/command-name.md <<'EOF'
---
name: command-name
description: What this command does
---

Command implementation and documentation.
EOF

# Or shell script
cat > commands/command-name.sh <<'EOF'
#!/bin/bash
# Command implementation
EOF
chmod +x commands/command-name.sh

Hooks

Create hooks configuration:

cat > hooks/hooks.json <<'EOF'
{
  "PreToolUse": {
    "command": "bash -c 'echo \"Pre-tool hook\"'",
    "timeout": 5000
  }
}
EOF

Step 5: Documentation

Create comprehensive README.md:

# Plugin Name

Brief description of plugin purpose.

## Installation

\`/plugin install fx-plugin-name\`

## Components

### Skills (if applicable)
- **skill-name** - Auto-invoked when [trigger condition]

### Commands (if applicable)
- \`/command-name\` - [What it does]

## Usage Examples

[Concrete examples of using each component]

## Configuration

[Any settings or environment variables]

## Contributing

[Development and testing instructions]

Step 6: Register Plugin in Marketplace

Update ~/.claude/plugins/marketplaces/fx-cc/.claude-plugin/marketplace.json:

cd ~/.claude/plugins/marketplaces/fx-cc

# Edit marketplace.json to add new plugin entry
# Add to "plugins" array:
{
  "name": "fx-plugin-name",
  "source": "./plugins/fx-plugin-name"
}

Example using jq:

jq '.plugins += [{"name": "fx-plugin-name", "source": "./plugins/fx-plugin-name"}]' \
  .claude-plugin/marketplace.json > /tmp/marketplace.json && \
  mv /tmp/marketplace.json .claude-plugin/marketplace.json

Step 7: Validate and Test

Validate structure:

cd ~/.claude/plugins/marketplaces/fx-cc/plugins/fx-plugin-name

# Validate JSON
jq empty .claude-plugin/plugin.json

# Check frontmatter in components
grep -r "^---$" skills/ commands/ || echo "No frontmatter found"

Test functionality:

1. Reload Claude Code to pick up changes
2. Skills: Ask questions that should trigger auto-invocation
3. Commands: Execute slash commands
4. Integration: Verify components work together

Git workflow:

cd ~/.claude/plugins/marketplaces/fx-cc

# Create feature branch
git checkout -b feat/fx-plugin-name

# Stage changes
git add plugins/fx-plugin-name .claude-plugin/marketplace.json

# Commit with semantic message
git commit -m "feat(fx-plugin-name): add plugin for [purpose]"

# Push for review
git push -u origin feat/fx-plugin-name

Step 8: Iterate

After testing:

1. Gather feedback on usability and effectiveness
2. Identify improvements to components
3. Update documentation with discovered use cases
4. Refine component interactions
5. Add examples from real usage

Quality Standards

Code Quality

• Valid JSON in all .json files
• Required frontmatter in all markdown components
• Clear, specific descriptions
• No dead file references

Documentation Quality

• README.md with installation and usage examples
• Expected behavior for each component
• Troubleshooting common issues
• Component interaction documentation

Testing Requirements

• Manual test all components
• Verify auto-invocation triggers for skills
• Confirm command execution
• Validate JSON with jq

Component Guidelines

Skills

• Use third-person descriptions ("This skill should be used when...")
• Write using imperative/infinitive form
• Keep SKILL.md under 5k words
• Use progressive disclosure (references/ for details)

Commands

• Clear, action-oriented naming
• Descriptive command descriptions
• Document expected arguments
• Provide usage examples

Hooks

• Document hook events and purposes
• Set appropriate timeouts
• Handle errors gracefully
• Avoid blocking operations

Common Patterns

Domain-Specific Plugins

Pattern: fx-{domain}

• Single domain focus (git, aws, docker)
• Related components bundled together
• Clear scope and boundaries

Utility Plugins

Pattern: fx-{utility-type}

• General-purpose tools
• Cross-domain applicability
• Modular, reusable components

Meta Plugins

Pattern: fx-{meta-purpose}

• Tools for building other tools
• Development workflow helpers
• Marketplace management

Troubleshooting

Plugin Not Appearing

• Verify marketplace.json syntax and entry
• Check plugin.json exists and is valid
• Reload Claude Code
• Verify plugin name matches exactly

Components Not Loading

• Check frontmatter exists and is valid
• Verify file naming and locations
• Ensure proper directory structure
• Reload after changes

Auto-Invocation Not Working

• Review skill description specificity
• Test with explicit trigger phrases
• Check for frontmatter typos
• Verify skill path in plugin

Working Directory

Critical: All operations default to ~/.claude/plugins/marketplaces/fx-cc/

When creating, editing, or managing plugins, always work from this directory unless explicitly specified otherwise.