Plugin Settings

This documents the `.claude/plugin-name.local.md` pattern for storing per-project plugin configuration using YAML frontmatter plus markdown. You'd use this when building plugins that need user-configurable behavior, like toggleable hooks, validation levels, or agent coordination state. The pattern keeps settings out of git while making them readable from bash hooks, commands, and agents. Includes practical parsing snippets for extracting frontmatter fields in bash scripts. The trade-off is that changing these files requires restarting Claude Code for hooks to pick them up, which makes sense given how the plugin system loads but can feel clunky during active development.

skills.sh installs: 167
GitHub stars: 476
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add aiskillstore/marketplace --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/aiskillstore/marketplace
First seen: Jun 3, 2026