plugin-settings
Installation
SKILL.md
Plugin Settings
Design plugin configuration without confusing Claude Code settings, plugin-bundled defaults, application-owned data, and Agent Master discovery metadata.
Classify the Setting First
Place each value in the narrowest mechanism that actually owns it:
| Need | Mechanism | Scope |
|---|---|---|
| Configure Claude Code behavior, permissions, environment, or plugin enablement | Official settings.json hierarchy |
User, project, local, or managed |
| Ship a supported Claude Code default with a plugin | <plugin-root>/settings.json |
Plugin default |
| Describe or distribute the plugin | .claude-plugin/plugin.json |
Plugin metadata |
| Collect per-user plugin options | .claude-plugin/plugin.json userConfig |
User, CLI-supplied, or managed |
| Store project-owned settings or state interpreted by custom code | Project-owned file with an explicit schema and reader | Whatever the plugin defines |
| Advertise a skill-owned UI in the bOpen desktop configurator | <plugin-root>/setup/manifest.json skillInterfaces |
Agent Master discovery |
Do not present a project-owned file as an official Claude Code settings source. Claude Code does not automatically discover, merge, validate, or reload arbitrary files merely because they live under .claude/.