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 ```markdown --- 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`: ```gitignore .claude/*.local.md ``` ## Reading Settings ### From Shell Scripts (Hooks) Use the standard frontmatter extraction pattern from `.claude/rules/shell-scripting.md`: ```bash #!/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" ...