Plugin Settings Pattern

👤 Anthropics

•

📅 January 19, 2026

•

⭐ 62.2K

Introduction

The Plugin Settings Pattern is a standardized architectural approach for managing user-configurable settings and state within the Claude Code ecosystem. Instead of hardcoding logic or relying on global environment variables, this skill enables developers to create flexible, per-project configurations using a specialized .claude/plugin-name.local.md file format.

By leveraging YAML frontmatter for structured data and Markdown for rich context, this pattern solves several critical developer workflows:

Dynamic Configuration: Enable or disable specific plugin features without modifying the core source code.
State Persistence: Maintain agent state, task numbers, or session coordinators across different terminal sessions.
Environment Safety: Local configuration files are designed to be git-ignored, ensuring secrets and local paths stay on your machine.
Cross-Interface Compatibility: Access your settings seamlessly from Bash hooks, natural language commands, and autonomous agents.

Installation

To implement this pattern in your Claude Code environment, ensure your project structure is prepared to handle local configuration files.

Create the configuration directory: Ensure a .claude folder exists in your project root.
Terminal window
```
mkdir -p .claude
```
Update your .gitignore: To prevent local settings from being committed to version control, add the following pattern to your .gitignore file:
```
.claude/*.local.md
.claude/*.local.json
```
Initialize a settings file: Create a file named .claude/your-plugin-name.local.md following the template below.

Usage

The Basic Template

Every settings file should follow the dual-structure of YAML frontmatter (for data) and Markdown (for human-readable context or prompts).

---
enabled: true
mode: "strict"
max_retries: 3
---

# Optional Context

This section can include specific instructions that Claude should read
when processing this project.

Accessing Settings in Hooks (Bash)

When building automation hooks, you can parse these settings using standard Unix utilities like sed and grep. This allows your scripts to exit early if a plugin is disabled or change behavior based on user preferences.

# Define state file path
STATE_FILE=".claude/my-plugin.local.md"

# Quick exit pattern: check if file exists
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0
fi

# Extract YAML frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# Parse a specific field
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

if [[ "$ENABLED" != "true" ]]; then
  exit 0
fi

Integration with Agents and Commands

Claude Code agents can be instructed to look for these files to ground their behavior.

Commands: Use the Read tool to check for the existence of .claude/plugin-name.local.md before executing logic.
Agents: Include instructions in your agent’s system prompt to “Check for plugin settings at .claude/plugin-name.local.md and adapt behavior based on the mode field.”

Warning: Settings changes typically require a Claude Code restart. Hooks and plugin configurations are loaded at the start of a session; if you modify a .local.md file, exit and restart claude to apply the changes.

Best Practices

Naming Convention: Always use the .claude/plugin-name.local.md format. The .local suffix is a visual cue that the file is machine-specific.
Provide Defaults: Your code should always have “fallback” values in case the settings file is missing or a specific key is undefined.
Validation: When reading numeric or boolean values in Bash, include a small validation check to prevent script errors from malformed YAML.
Sanitization: If your plugin writes to these files based on user input, ensure you escape quotes to maintain valid YAML structure.