configure-plugins

<quick_start>

1. Create .claude/plugin-name.local.md in the project root
2. Add YAML frontmatter with configuration fields
3. Optionally add markdown body for prompts or context
4. Read settings from hooks, commands, or agents
5. Add .claude/*.local.md to .gitignore </quick_start>

<essential_principles>

• Settings files are per-project (not global) -- each project can have different configuration
• Settings files are user-local (not committed) -- always gitignored
• Changes to settings require Claude Code restart -- hooks load at session start
• Always provide sensible defaults when the settings file doesn't exist </essential_principles>

---
enabled: true
validation_level: standard     # strict | standard | lenient
max_retries: 3
allowed_extensions: [".js", ".ts", ".tsx"]
---

# Additional Context

This markdown body is available as supplementary content.
It can contain task descriptions, prompts, or instructions.

</step_1_design_schema>

<step_2_create_file> Create the settings file at .claude/plugin-name.local.md:

Naming rules:

• Use .claude/ directory
• Match the plugin name exactly
• Use .local.md suffix (signals user-local, non-committed file)

Add to .gitignore:

.claude/*.local.md
.claude/*.local.json

</step_2_create_file>

<step_3_read_settings> From hooks (bash scripts):

#!/bin/bash
set -euo pipefail

STATE_FILE=".claude/my-plugin.local.md"

# Quick exit if not configured
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0  # Use defaults, skip hook logic
fi

# Extract frontmatter (between --- markers)
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# Read individual fields
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')
MODE=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')

# Check if enabled
if [[ "$ENABLED" != "true" ]]; then
  exit 0
fi

# Extract markdown body (after second ---)
BODY=$(awk '/^---$/{i++; next} i>=2' "$STATE_FILE")

From commands:

Steps:
1. Check if settings exist at .claude/my-plugin.local.md
2. Read configuration using Read tool
3. Parse YAML frontmatter to extract settings
4. Apply settings to processing logic

From agents:

Check for plugin settings at .claude/my-plugin.local.md.
If present, parse YAML frontmatter and adapt behavior accordingly.

</step_3_read_settings>

<step_4_validate> Validate settings values in hook scripts:

# Validate boolean
if [[ "$ENABLED" != "true" && "$ENABLED" != "false" ]]; then
  ENABLED=true  # Default
fi

# Validate numeric range
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
  MAX=10  # Default
fi

# Validate enum
case "$MODE" in
  strict|standard|lenient) ;;  # Valid
  *) MODE=standard ;;          # Default
esac

</step_4_validate>

<common_patterns> <temporarily_active_hooks> Use settings to enable/disable hooks without editing hooks.json:

# In hook script
STATE_FILE=".claude/security-scan.local.md"
if [[ ! -f "$STATE_FILE" ]]; then exit 0; fi

FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
if [[ "$ENABLED" != "true" ]]; then exit 0; fi

# Hook logic only runs when enabled