Claude Code: Conditionally Loading Plugins with --plugin-dir

claude-code-conditional-plugin-loading.md

Claude Code: Conditionally Loading Plugins with --plugin-dir

Overview

Claude Code supports loading plugins on a per-session basis using the --plugin-dir flag. This is additive — it loads the specified plugin(s) in addition to all normally installed/enabled plugins. It does not replace them.

A plugin directory is identified by having a .claude-plugin/plugin.json manifest inside it.

Basic Usage

# Load a plugin for this session only
claude --plugin-dir /path/to/my-plugin

# Load multiple plugins
claude --plugin-dir /path/to/plugin-a --plugin-dir /path/to/plugin-b

Example: Loading the official skill-creator plugin from a local checkout

claude --plugin-dir /path/to/claude-plugins-official/plugins/skill-creator

Conditional Loading Approaches

1. Shell Alias / Function (simplest for ad-hoc use)

# Add to ~/.bashrc or ~/.zshrc
claude-with-skill-creator() {
  claude --plugin-dir /path/to/claude-plugins-official/plugins/skill-creator "$@"
}

Then just run:

claude-with-skill-creator
claude-with-skill-creator -p "Create a new skill for linting"

2. Environment Variable Toggle

#!/bin/bash
CLAUDE_EXTRA_ARGS=""
if [[ "$ENABLE_SKILL_CREATOR" == "1" ]]; then
  CLAUDE_EXTRA_ARGS="--plugin-dir /path/to/claude-plugins-official/plugins/skill-creator"
fi
claude $CLAUDE_EXTRA_ARGS "$@"

Usage:

ENABLE_SKILL_CREATOR=1 claude

3. Wrapper Script with Flag

#!/bin/bash
# Save as e.g. ~/bin/claude-wrapper
PLUGIN_ARGS=()
if [[ "$1" == "--with-skill-creator" ]]; then
  PLUGIN_ARGS+=(--plugin-dir /path/to/claude-plugins-official/plugins/skill-creator)
  shift
fi
claude "${PLUGIN_ARGS[@]}" "$@"

Usage:

claude-wrapper --with-skill-creator
claude-wrapper  # normal session, no extra plugin

4. Install Permanently, Toggle with enable/disable

# Install from local path (one-time)
claude plugins install /path/to/claude-plugins-official/plugins/skill-creator

# Disable when not needed
claude plugins disable skill-creator

# Re-enable when needed
claude plugins enable skill-creator

# Check status
claude plugins list

This is the cleanest approach for repeated use — install once, then toggle as needed.

Which Approach to Choose?

Approach	Best For
Shell alias/function	Quick, frequent use of a specific plugin
Environment variable	CI/CD or scripted workflows
Wrapper script	Multiple optional plugins, team-shared tooling
Install + enable/disable	Day-to-day use, persistent across sessions

Plugin Directory Structure

A valid plugin directory looks like:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Required manifest
├── skills/
│   └── my-skill/
│       └── SKILL.md       # Skill definition
├── agents/                # Optional custom agents
└── ...

The plugin.json manifest:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "author": {
    "name": "Your Name",
    "email": "[email protected]"
  }
}

References

• Claude Code official plugins
• claude --help for all CLI flags
• claude plugins --help for plugin management commands