plugin-settings

Plugin Settings Pattern

Per-project plugin configuration using .claude/plugin-name.local.md files with YAML frontmatter for structured settings and markdown body for additional context.

Reach for a different mechanism when the settings are global (~/.claude/settings.json) or purely structured with no prose/prompt content (a plain .json file). The .local.md form earns its keep when config must carry prompts or instructions alongside structured fields.

File Structure

Location

project-root/
└── .claude/
    └── plugin-name.local.md    # Per-project, user-local settings

Format

---
enabled: true
mode: standard
max_retries: 3
allowed_extensions: [".js", ".ts", ".tsx"]
---

# Additional Context

Markdown body for prompts, instructions, or documentation
that hooks and agents can read and use.

Naming Convention

• Use .claude/plugin-name.local.md format
• Match the plugin name exactly from plugin.json
• The .local.md suffix signals user-local (not committed to git)

Gitignore

Add to project .gitignore:

.claude/*.local.md

Reading Settings

From Shell Scripts (Hooks)

Use the standard frontmatter extraction pattern from .claude/rules/shell-scripting.md:

#!/bin/bash
set -euo pipefail

STATE_FILE=".claude/my-plugin.local.md"

# Quick exit if not configured
[[ -f "$STATE_FILE" ]] || exit 0

# Extract field using standard pattern
extract_field() {
  local file="$1" field="$2"
  head -50 "$file" | grep -m1 "^${field}:" | sed 's/^[^:]*:[[:space:]]*//' | tr -d '\r'
}

plugin_enabled=$(extract_field "$STATE_FILE" "enabled")
[[ "$plugin_enabled" == "true" ]] || exit 0

plugin_mode=$(extract_field "$STATE_FILE" "mode")

Extract Markdown Body

# Get content after the closing --- frontmatter delimiter
BODY=$(awk '/^---$/{i++; next} i>=2' "$STATE_FILE")

From Skills and Agents

Skills and agents read settings with the Read tool:

1. Check if `.claude/my-plugin.local.md` exists
2. Read the file and parse YAML frontmatter
3. Apply settings to current behavior
4. Use markdown body as additional context/prompt