plugin-settingslisted

# 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. ## When to Use This Skill | Use plugin settings when... | Use alternatives when... | |-----------------------------|--------------------------| | Plugin needs per-project configuration | Settings are global (use `~/.claude/settings.json`) | | Hooks need runtime enable/disable control | Hook behavior is always-on | | Agent state persists between sessions | State is ephemeral within a session | | Users customize plugin behavior per-project | Plugin has no configurable behavior | | Configuration includes prose/prompts alongside structured data | All config is purely structured (use `.json`) | ## 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