Plugin Settings

Shows you how to store per-project configuration for Claude Code plugins using .claude/plugin-name.local.md files with YAML frontmatter. You'd use this when building plugins that need user-configurable settings, like toggling strict mode or storing agent coordination state. The pattern keeps settings out of git while letting hooks, commands, and agents read configuration at runtime. Includes bash parsing examples for extracting frontmatter fields and markdown bodies. The restart requirement for hooks to pick up changes is a bit clunky, but the .local.md convention is clean and the YAML plus markdown combo works well for mixing structured config with human-readable context.

GitHub stars: 340
last updated: May 19, 2026

View on GitHub

Install

$ npx -y skills add tzachbon/smart-ralph --skill 'Plugin Settings' --agent claude-code

Installs into .claude/skills of the current project.

Files

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

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

# Additional Context

This markdown body can contain:
- Task descriptions
- Additional instructions
- Prompts to feed back to Claude
- Documentation or notes

Example: Plugin State File

.claude/my-plugin.local.md:

---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

# Plugin Configuration

SKILL.md on GitHub

Details

Repository: github.com/tzachbon/smart-ralph
License: MIT
First seen: Jun 11, 2026