Plugin Settings

anthropics/claude-plugins-officialOfficial

This documents the pattern for storing per-project plugin configuration in `.claude/plugin-name.local.md` files with YAML frontmatter. You'd use this when building plugins that need user-configurable settings or state, like enabling strict mode, storing agent assignments, or controlling hook behavior without editing hooks.json. The skill shows concrete bash parsing techniques for extracting frontmatter fields in hooks and how to read settings from commands and agents. One thing to know: changes require restarting Claude Code since hooks load at startup. It's aimed at plugin authors rather than end users, and the `.local.md` suffix convention helps keep these files out of git while making them human-editable.

skills.sh installs: 7.3K
GitHub stars: 46.7K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add anthropics/claude-plugins-official --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/anthropics/claude-plugins-official
First seen: May 16, 2026