Skip to content
Patterson Academy

Plugin settings and state

Plugins often need per-project configuration. The plugin-dev toolkit's pattern: a .claude/<plugin-name>.local.md file with YAML frontmatter for machine-readable settings and a markdown body for human notes — gitignored, validated by scripts, updated atomically.

.claude/my-plugin.local.md
---
enabled: true
strict_mode: false
max_retries: 3
notify_channel: "#eng-alerts"
---


# My Plugin — local settings


Strict mode is off while we migrate the legacy API routes.
Flip it on after PROJ-142 lands.

Hooks read these settings by parsing the frontmatter with sed/awk/grep and can exit early when disabled — the temporarily-active-hook pattern: a flag file or config check at the top of the script makes a hook a no-op until enabled.

hook with quick-exit
#!/bin/bash
FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-strict-validation"


if [ ! -f "$FLAG_FILE" ]; then
  exit 0   # not enabled — skip silently
fi


input=$(cat)
# ... validation logic ...

Check your understanding

Section titled “Check your understanding”

Question 1What is the "temporarily active hook" pattern?