Plugin Development Lessons

Installation

• Local plugins need a marketplace directory with .claude-plugin/marketplace.json
• Register: claude plugin marketplace add /path/to/marketplace
• Install: claude plugin install name@marketplace-name
• Manual edits to installed_plugins.json don't work — always use CLI

Commands

• Commands MUST have name: field in YAML frontmatter — without it, they silently fail to register
• The skill: frontmatter field is NOT standard — use instructions in the body instead
• Commands need actual executable instructions, not just "use skill X"

Updates

• claude plugin update checks version field — if unchanged, says "already latest"
• To force update: uninstall then install
• After editing plugin source, always reinstall to refresh the cache

File Structure

marketplace-dir/
├── .claude-plugin/marketplace.json    # Required: name, plugins[] with source paths
└── plugin-name/
    ├── .claude-plugin/plugin.json     # Required: name, description
    ├── CLAUDE.md                      # Plugin-level instructions
    ├── skills/{name}/SKILL.md         # Frontmatter: name, description
    ├── commands/{name}.md             # Frontmatter: name, description (name is REQUIRED)
    ├── agents/{name}.md               # Frontmatter: name, description, model
    ├── hooks/hooks.json               # SessionStart, PreToolUse, PostToolUse, Stop
    └── reference/                     # Supporting docs for skills to read

Skill Design

• Skills are instructions, not code — they tell Claude what to generate
• Reference docs are quality guides, not templates — Claude reads patterns and adapts
• Every skill should reference the project's CLAUDE.md for context (not a config file)
• /setup-workflow appends rules to CLAUDE.md — no separate config needed