--plugin-dir flag documentation unclear and behavior inconsistent

Description

The --plugin-dir flag documentation is unclear about its expected usage, and the behavior is inconsistent especially when combined with CLAUDE_CONFIG_DIR.

Current Documentation

--plugin-dir <paths...>    Load plugins from directories for this session only (repeatable)

Unclear Aspects

1. Should it point to a directory CONTAINING plugins, or TO a specific plugin?

• --plugin-dir ~/.claude/plugins (directory containing plugins)
• --plugin-dir ~/.claude/plugins/my-plugin (specific plugin)
• Both seem to partially work but with different behaviors

1. Does it override or supplement the default plugins directory?

• When using CLAUDE_CONFIG_DIR, does --plugin-dir add to or replace $CLAUDE_CONFIG_DIR/plugins/?

1. Does it work with symlinks?

• Behavior seems inconsistent when plugin path is a symlink

Tested Combinations (with CLAUDE_CONFIG_DIR)

| Command | Commands | Skills |
|---------|----------|--------|
| --plugin-dir ~/.config/plugins | ✅ | ❌ |
| --plugin-dir ~/.config/plugins/my-plugin | ✅ | ❌ |
| --plugin-dir /abs/path/to/plugin | ✅ | ❌ |
| --plugin-dir /abs/path/to/plugins-dir | ✅ | ❌ |
| No --plugin-dir flag | ✅ | ❌ |

Note: Skills failing may be related to #20993, but the documentation still needs clarification.

Suggested Improvements

1. Add examples to --help output showing correct usage
2. Clarify if path should be to plugin or to directory containing plugins
3. Document interaction with CLAUDE_CONFIG_DIR
4. Document symlink handling

Example Documentation

--plugin-dir <paths...>    Load plugins from directories for this session only (repeatable)
                           
                           Examples:
                             --plugin-dir ./my-plugin           # Load single plugin
                             --plugin-dir ./plugins             # Load all plugins in directory
                             --plugin-dir ./p1 --plugin-dir ./p2  # Load multiple
                           
                           Note: Supplements default plugin directories, does not replace them.

Environment

• OS: macOS Darwin 25.2.0
• Date: 2026-01-26