Plugin Settings Pattern

Per-project plugin configuration using .claude/plugin-name.local.md files with YAML frontmatter for structured settings and markdown body for additional context.

When to Use This Skill

Use plugin settings when...	Use alternatives when...
Plugin needs per-project configuration	Settings are global (use ~/.claude/settings.json)
Hooks need runtime enable/disable control	Hook behavior is always-on
Agent state persists between sessions	State is ephemeral within a session
Users customize plugin behavior per-project	Plugin has no configurable behavior
Configuration includes prose/prompts alongside structured data	All config is purely structured (use .json)

File Structure

Location

project-root/
└── .claude/
    └── plugin-name.local.md    # Per-project, user-local settings

Format

---
enabled: true
mode: standard
max_retries: 3
allowed_extensions: [".js", ".ts", ".tsx"]
---

# Additional Context

Markdown body for prompts, instructions, or documentation
that hooks and agents can read and use.

Naming Convention

• Use .claude/plugin-name.local.md format
• Match the plugin name exactly from plugin.json
• The .local.md suffix signals user-local (not committed to git)

Gitignore

Add to project .gitignore:

.claude/*.local.md

Reading Settings

From Shell Scripts (Hooks)

Use the standard frontmatter extraction pattern from .claude/rules/shell-scripting.md:

#!/bin/bash
set -euo pipefail

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

# Quick exit if not configured
[[ -f "$STATE_FILE" ]] || exit 0

# Extract field using standard pattern
extract_field() {
  local file="$1" field="$2"
  head -50 "$file" | grep -m1 "^${field}:" | sed 's/^[^:]*:[[:space:]]*//' | tr -d '\r'
}

plugin_enabled=$(extract_field "$STATE_FILE" "enabled")
[[ "$plugin_enabled" == "true" ]] || exit 0

plugin_mode=$(extract_field "$STATE_FILE" "mode")

Extract Markdown Body

# Get content after the closing --- frontmatter delimiter
BODY=$(awk '/^---$/{i++; next} i>=2' "$STATE_FILE")

From Skills and Agents

Skills and agents read settings with the Read tool:

1. Check if `.claude/my-plugin.local.md` exists
2. Read the file and parse YAML frontmatter
3. Apply settings to current behavior
4. Use markdown body as additional context/prompt

Common Patterns

Pattern 1: Toggle-Based Hook Activation

Control hook activation without editing hooks.json:

#!/bin/bash
set -euo pipefail
STATE_FILE=".claude/security-scan.local.md"
[[ -f "$STATE_FILE" ]] || exit 0

extract_field() {
  local file="$1" field="$2"
  head -50 "$file" | grep -m1 "^${field}:" | sed 's/^[^:]*:[[:space:]]*//' | tr -d '\r'
}

scan_enabled=$(extract_field "$STATE_FILE" "enabled")
[[ "$scan_enabled" == "true" ]] || exit 0

# Hook logic runs only when enabled

Pattern 2: Agent State Between Sessions

Store agent task state for multi-session work:

---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
enabled: true
---

# Current Task

Implement JWT authentication for the REST API.
Coordinate with auth-agent on shared types.

Pattern 3: Configuration-Driven Validation

---
validation_level: strict
max_file_size: 1000000
allowed_extensions: [".js", ".ts", ".tsx"]
---

validation_level=$(extract_field "$STATE_FILE" "validation_level")
case "$validation_level" in
  strict)  run_strict_checks ;;
  standard) run_standard_checks ;;
  *)       run_standard_checks ;;  # Default
esac

Implementation Checklist

When adding settings to a plugin:

1. Design settings schema (fields, types, defaults)
2. Create template in plugin README
3. Add .claude/*.local.md to .gitignore
4. Implement parsing using extract_field pattern
5. Use quick-exit pattern ([[ -f "$STATE_FILE" ]] || exit 0)
6. Provide sensible defaults when file is missing
7. Document that changes require Claude Code restart (hooks only)

Best Practices

Practice	Details
Quick exit	Check file existence first, exit 0 if absent
Sensible defaults	Provide fallback values when settings file is missing
Use extract_field	Standard frontmatter extraction from shell-scripting.md
Validate values	Check numeric ranges, enum membership
File permissions	Settings files should be user-readable only (chmod 600)
Restart notice	Document that hook-related changes need a Claude Code restart

Agentic Optimizations

Context	Command
Check settings exist	[[ -f ".claude/plugin.local.md" ]]
Extract single field	head -50 file | grep -m1 "^field:" | sed 's/^[^:]*:[[:space:]]*//'
Extract body	awk '/^---$/{i++; next} i>=2' file
Quick enable check	[[ "$(extract_field file enabled)" == "true" ]]