Plugin Settings Pattern

Plugins store user-configurable settings in .claude/plugin-name.local.md files within the project directory. YAML frontmatter provides structured configuration; the markdown body carries prompts or additional context.

When to Use This Pattern

flowchart TD
    Start(["Plugin needs user-configurable behavior"]) --> Q1{What kind of state?}
    Q1 -->|"Per-project configuration<br>(validation level, enabled/disabled, limits)"| Settings["Use .claude/plugin-name.local.md<br>YAML frontmatter for config values"]
    Q1 -->|"Agent coordination state<br>(task assignment, session tracking)"| AgentState["Use .claude/plugin-name.local.md<br>Frontmatter for metadata<br>Body for task description"]
    Q1 -->|"Hook activation control<br>(enable/disable without editing hooks.json)"| HookControl["Use .claude/plugin-name.local.md<br>enabled: true/false field"]
    Q1 -->|"Loop iteration state<br>(iteration counter, completion promise)"| LoopState["Use .claude/plugin-name.local.md<br>Frontmatter tracks loop state<br>Body is the prompt to loop"]
    Settings --> Location
    AgentState --> Location
    HookControl --> Location
    LoopState --> Location
    Location["File location — .claude/plugin-name.local.md<br>Lifecycle — user-managed, gitignored<br>Structure — YAML frontmatter + markdown body<br>Consumers — hooks, skills, agents"]

File Structure

---
enabled: true
setting1: value1
numeric_setting: 42
list_setting: ["item1", "item2"]
---

# Additional Context

Markdown body for prompts, task descriptions,
additional instructions, or documentation.

Reading Settings

From Hooks (Bash)

The standard pattern for reading settings in hooks follows three steps — check existence, parse frontmatter, extract fields.

#!/bin/bash
set -euo pipefail

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

# Quick exit if not configured
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0
fi

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

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

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

From Skills and Agents

Skills and agents read settings with the Read tool, then parse YAML frontmatter inline.

Check for plugin settings at `.claude/my-plugin.local.md`.
If present, parse YAML frontmatter and adapt behavior according to:
- enabled field controls whether the plugin is active
- mode field selects processing behavior (strict, standard, lenient)

Extracting the Markdown Body

Content after the closing --- marker is the body.

BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Common Implementation Patterns

Pattern 1 — Temporarily Active Hooks

Control hook activation via settings file instead of editing hooks.json (which requires restart).

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

# Run hook logic only when enabled

Pattern 2 — Agent State Management

Store agent-specific state and task assignments.

---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
---

# Task Assignment

Implement JWT authentication for the API.

Hooks read this to coordinate agents.

AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')
COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')

tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

Pattern 3 — Configuration-Driven Behavior

Settings drive validation strictness, file size limits, and allowed extensions.

LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')

case "$LEVEL" in
  strict)   ;; # Maximum validation
  standard) ;; # Balanced validation
  lenient)  ;; # Minimal validation
esac

Creating Settings Files

flowchart TD
    Start(["Add settings to a plugin"]) --> S1["Design settings schema<br>— which fields, types, defaults"]
    S1 --> S2["Create template in plugin README<br>— document the .local.md format"]
    S2 --> S3["Add .gitignore entry<br>— .claude/*.local.md"]
    S3 --> S4["Implement parsing in hooks/skills<br>— use quick-exit pattern"]
    S4 --> S5["Provide sensible defaults<br>— when settings file is absent"]
    S5 --> S6["Document restart requirement<br>— changes need session restart"]

Best Practices

File naming — use .claude/plugin-name.local.md format. The .local suffix signals user-local, gitignored files.

Gitignore — add to project .gitignore:

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

Defaults — provide sensible defaults when the settings file does not exist.

if [[ ! -f "$STATE_FILE" ]]; then
  ENABLED=true
  MODE=standard
else
  # Parse from file
fi

Validation — validate field values before use.

if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
  echo "Invalid max_value in settings (must be 1-100)" >&2
  MAX=10
fi

Atomic updates — use temp file + atomic move to prevent corruption.

TEMP_FILE="${FILE}.tmp.$$"
sed "s/^field: .*/field: $NEW_VALUE/" "$FILE" > "$TEMP_FILE"
mv "$TEMP_FILE" "$FILE"

Restart requirement — settings changes require Claude Code session restart. Document this in the plugin README.

Security Considerations

Sanitize user input when writing settings files.

SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')

Validate file paths stored in settings to prevent path traversal.

if [[ "$FILE_PATH" == *".."* ]]; then
  echo "Invalid path in settings (path traversal)" >&2
  exit 2
fi

Permissions — settings files should be readable by user only (chmod 600), not committed to git, not shared between users.

Deep Reference

For detailed parsing techniques (field extraction, body parsing, atomic updates, edge cases, yq integration), read Parsing Techniques Reference.

For production examples showing complete settings file lifecycles in real plugins, read Real-World Examples.

Related Skills

• For hook authoring patterns that consume settings files, use /plugin-creator:hooks-guide
• For component selection guidance (when to use hooks vs skills vs agents), use /plugin-creator:component-patterns
• For the legacy commands format that can create settings files, use /plugin-creator:command-development

SOURCE: Adapted from Anthropic plugin-dev plugin skills/plugin-settings/ (8 files, ~545 lines). Accessed 2026-03-24.