plugin-settings

Per-project plugin configuration is managed through a local settings file named `.claude/plugin-name.local.md` with YAML frontmatter. This file stores structured fields like an `enabled` flag and instructions, letting you adapt plugin execution without modifying source code.

YAML frontmatter provides structured key-value pairs at the top of a markdown file, such as `enabled`, modes, and limits. Hooks and commands parse these fields to apply deterministic plugin behavior and manage state safely.

Create a `.claude/plugin-name.local.md` file with YAML frontmatter containing at least `enabled: true`. Configure your hook to read and respect these fields, defaulting safely when the file is missing.

Yes, the settings pattern uses YAML frontmatter for structured configuration and the markdown body for additional instructions or prompts. This allows agents and commands to apply both deterministic fields and contextual guidance.

When the local settings file is missing, the parsing logic defaults safely. This ensures hooks and commands continue executing predictably by applying default behaviors instead of failing.

You need this pattern when you want user-configurable behavior for hooks, commands, or agents on a per-project basis. It separates plugin state and configuration from plugin code, allowing localized customization.