Set up and review Claude Code plugin settings

This guide turns Anthropic's official documentation for the plugin-settings pattern into a controlled workflow. The goal is local configuration that remains understandable, portable, and outside the team repository.

Define the configuration schema

Begin with the few values the plugin actually needs. Document types, allowed values, and defaults. A missing document must lead to a safe and useful default path. Avoid sensitive content and never store credentials in a project settings file.

Create the local file

Create the .claude directory in the project and use the plugin name with the .local.md suffix. Put structured values between the two frontmatter delimiters and reserve the Markdown body for additional context. Add suitable .gitignore rules so local files are not accidentally committed.

Read and validate

Check that the file exists before reading it. Restrict the accepted schema, validate booleans and numeric values, and handle invalid input with a documented default or a clear stop. Paths require dedicated traversal and write-target checks. Hooks, commands, and agents must not infer additional permissions from settings values.

Activate changes

Document that a settings change requires a Claude Code restart. After restarting, verify that the plugin reads the expected configuration and still behaves safely when the file is absent. Test each optional feature separately from the configuration reader, so a successful read is not mistaken for a functional or security approval.

Review before sharing

Read every hook and script before sharing a plugin with a team. Review network access, file writes, environment variables, runtime dependencies, and possible prompt-injection paths. Keep the local file out of Git and use purpose-built mechanisms for sensitive values. The provider describes this pattern for plugin settings and state; it is not a replacement for centralized secret management.