Plugin Settings Pattern for Claude Code Plugins

Overview

Plugins can store user-configurable settings and state in .claude/plugin-name.local.md files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.

Key characteristics:

• File location: .claude/plugin-name.local.md in project root
• Structure: YAML frontmatter + markdown body
• Purpose: Per-project plugin configuration and state
• Usage: Read from hooks, commands, and agents
• Lifecycle: User-managed (not in git, should be in .gitignore)

File Structure

Basic Template