plugin-development

Plugin Development Guide

General guide for creating effective plugins with skills, commands, and agents.

Plugin Structure

my-plugin/
├── .metadata/
│   └── manifest.json       # Plugin metadata
├── skills/
│   └── skill-name/
│       ├── SKILL.md        # Required
│       ├── references/     # Detailed docs (Optional)
│       └── scripts/        # Utilities (Optional)
├── commands/
│   └── command-name.md
├── agents/
│   └── agent-name.md
└── hooks/
    └── hooks.json

Skill Development

SKILL.md Structure

---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", or mentions "keyword". Be specific about triggers.
version: 1.0.0
---

# Skill Title

Core content here.

## Additional Resources (Optional)

- **`references/detailed.md`** - Detailed patterns
- **`examples/`** - Working examples (Include only if requested or necessary)

Progressive Disclosure

Level	Content	When Loaded
Metadata	name + description	Always (~100 words)
SKILL.md	Core content	When triggered (<5k words)
References	Detailed docs	As needed (Optional)
Examples	Working code	Optional (Based on user request)

Description Best Practices

Good:

description: This skill should be used when the user asks to "create a hook", "add PreToolUse hook", "validate tool use", or mentions hook events.

Bad:

description: Provides hook guidance.  # Too vague
description: Use this skill for hooks.  # Not third person

Writing Style

Use imperative form, not second person:

# Good
Start by reading the configuration.
Validate the input before processing.

# Bad
You should start by reading...
You need to validate the input...

Command Development

Command Structure

---
name: command-name
description: What the command does
argument-hint: "[optional args]"
---

# Command Title

Instructions for executing the command.