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"]