plugin-development

Han Plugin Development

This skill provides comprehensive guidance for developing Han plugins.

Plugin Types

Han supports several plugin categories:

1. Language/​Validation - Skills and validation hooks for languages/​tools
2. Discipline - Specialized agents for specific domains
3. Service/​Tool - MCP servers for external integrations

Directory Structure

Every plugin must follow this structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # Plugin metadata (required)
├── han-plugin.yml       # Hook configuration (optional)
├── skills/              # Skills directory (optional)
│   └── my-skill/
│       └── SKILL.md     # Skill definition
├── commands/            # Commands directory (optional)
│   └── my-command.md    # Slash command
├── hooks/               # Hook scripts (optional)
│   └── my-hook.sh       # Hook implementation
└── README.md            # Documentation

plugin.json (Required)

The plugin.json file defines metadata:

{
  "name": "my-plugin-name",
  "version": "1.0.0",
  "description": "What the plugin does",
  "author": {
    "name": "Author Name",
    "url": "https://author-website.com"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

Required fields:

• name - Must match directory name
• version - Semantic versioning

han-plugin.yml (Hooks)

Define validation hooks that run at lifecycle events:

hooks:
  my-validation:
    event: Stop                    # When to run
    command: bash "hooks/​my-hook.sh"
    description: What this hook does

    # Optional filters:
    if_changed:                    # Only run if these files changed
      - "**/​*.ts"
    dirs_with:                     # Only run in dirs containing
      - "package.json"

Hook Events

• Setup - Plugin installation
• SessionStart - Session begins
• UserPromptSubmit - User sends message
• PreToolUse - Before tool execution
• PostToolUse - After tool execution
• Stop - Work completion (validation)
• SubagentStop - Subagent completion

Hook Environment Variables

Scripts receive:

• CLAUDE_PLUGIN_ROOT - Plugin directory path
• HAN_SESSION_ID - Current session ID
• HAN_PROJECT_DIR - Project directory
• HAN_FILES - Changed files (space-separated)

Skills (SKILL.md)

Skills provide domain expertise:

---
name: skill-name
description: When to use this skill
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
---

# Skill Title

Skill content with guidance, examples, and best practices.

Required frontmatter:

• name - Skill identifier
• description - When Claude should use this skill

Commands (Slash Commands)

Commands provide slash command functionality:

---
description: What the command does
---

Command implementation content...

Invoke with: /​plugin-name:command-name

Validation

Before publishing, validate your plugin:

cd my-plugin
han plugin validate

This checks:

• Required files exist
• JSON/​YAML syntax is valid
• Frontmatter is correct
• No misplaced files

Best Practices

Hook Scripts

1. Use set -e - Exit on first error
2. Quote variables - "${HAN_FILES}" not $HAN_FILES
3. Clear error messages - Write to stderr on failure
4. Exit codes - 0 for success, non-zero for failure

Skills

1. Specific descriptions - Help Claude know when to use
2. Practical examples - Show real usage patterns
3. Progressive detail - Start simple, add complexity
4. Troubleshooting - Include common issues

General

1. Follow naming conventions - short names matching directory
2. Include README - Installation and usage docs
3. Version properly - Use semantic versioning
4. Test locally - Install via path before publishing

Local Installation

Test your plugin locally:

# Install from local path
han plugin install /​path/​to/​my-plugin --scope project

# Or add to .claude/​settings.json manually

Publishing

Share your plugin:

1. Push to a git repository
2. Add to the Han marketplace (optional)
3. Users install via: han plugin install github:user/​repo

Troubleshooting

Hook Not Running

• Check event matches lifecycle point
• Verify command path is correct
• Check if_changed/dirs_with filters

Validation Fails

• Run han plugin validate for specific errors
• Check plugin.json syntax
• Verify skill frontmatter

Skill Not Found

• Check SKILL.md path and naming
• Verify frontmatter has required fields
• Skill name should match directory name