Plugin Settings

This is a documentation pattern for managing plugin configuration in Claude Code projects. It shows you how to structure settings files in `.claude/plugin-name.local.md` using YAML frontmatter for config values and markdown for prompts or context. The pattern keeps settings local to each project and out of version control. It's straightforward if you're building Claude Code plugins and need a clean way to let users configure behavior per project. The example comes from Anthropic's original claude-code repo, so it follows their intended approach. Not much code here, just the structural pattern and some basic examples of what goes in the frontmatter versus the markdown body.

GitHub stars: 30.2K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add davila7/claude-code-templates --skill 'Plugin Settings' --agent claude-code

Installs into .claude/skills of the current project.

Files

Plugin Settings Pattern for Claude Code Plugins

Overview

Plugins can store user-configurable settings and state in .claude/plugin-name.local.md files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.

Key characteristics:

File location: .claude/plugin-name.local.md in project root
Structure: YAML frontmatter + markdown body
Purpose: Per-project plugin configuration and state
Usage: Read from hooks, commands, and agents
Lifecycle: User-managed (not in git, should be in .gitignore)

File Structure

Basic Template

---
enabled: true
setting1: value1
setting2: value2
numeric_setting: 42
list_setting: ["item1", "item2"]
---

# Additional Context

This markdown body can contain:
- Task descriptions
- Additional instructions
- Prompts to feed back to Claude
- Documentation or notes

Example: Plugin State File

.claude/my-plugin.local.md:

---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

# Plugin Configuration

SKILL.md on GitHub

Details

Repository: github.com/davila7/claude-code-templates
First seen: Jun 3, 2026