---
title: "Plugin Settings Pattern for Claude Code Plugins: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/anthropic-plugin-settings/
description: "Documents one pattern for per-project Claude Code plugin settings, a .claude/<plugin-name>.local.md file with YAML frontmatter and a Markdown body, and how hooks, commands and agents read it."
---

# Plugin Settings Pattern for Claude Code Plugins: review, setup & limitations · Undominated.ai

> Documents one pattern for per-project Claude Code plugin settings, a .claude/<plugin-name>.local.md file with YAML frontmatter and a Markdown body, and how hooks, commands and agents read it.

[← Explore all skills](/skills/)

AGENT DEVELOPMENT / Anthropic

# Plugin Settings Pattern for Claude Code Plugins

Documents one pattern for per-project Claude Code plugin settings, a .claude/<plugin-name>.local.md file with YAML frontmatter and a Markdown body, and how hooks, commands and agents read it.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/anthropics/claude-plugins-official/tree/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings)

SOURCE REVIEW

 Reviewed 2026-10-21
 Evidence 7 linked sources
 Publisher Anthropic
 Licence [Apache-2.0 ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE)
 Revision 41f32e407b45
 [Read what was—and wasn’t—checked ↓](#review)

“This skill should be used when the user asks about "plugin settings", "store plugin configuration", "user-configurable plugin", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings", or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.”

 [Anthropic · upstream description ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - It documents a single, concrete convention: settings and state in .claude/<plugin-name>.local.md in the project root, YAML frontmatter plus a Markdown body, kept out of git through a .claude/*.local.md line in .gitignore.
- It ships parse-frontmatter.sh and validate-settings.sh, and an example hook, read-settings-hook.sh, that exits early when the file is missing or enabled is not true.

### A good fit for

 - Store per-project plugin settings in .claude/<plugin-name>.local.md and read them from a hook with sed and grep
- Switch a hook on or off with an enabled: field instead of editing hooks.json
- Print one frontmatter field in a shell script with parse-frontmatter.sh

### Weigh up before choosing

 - Last commit touching plugins/plugin-dev/skills/plugin-settings at revision 41f32e40: 2026-02-05 (2438937b).
- The parsing it teaches and ships is line-based sed, grep and awk over flat key: value lines, not a YAML parser.
- The SKILL.md says settings changes take effect only after Claude Code is restarted, because hooks cannot be hot-swapped within a session.
- One coordination example has a hook send text into another session with tmux send-keys -t "$COORDINATOR".
- Its real-world examples name the multi-agent-swarm and ralph-loop plugins. At this revision plugins/ralph-loop exists in the repository; no multi-agent-swarm directory is under plugins/ or external_plugins/.
- This skill belongs to plugin-dev, and the plugin-dev README's last section reads "MIT License - See repository for details" although plugins/plugin-dev/LICENSE is the Apache License, Version 2.0. This record follows the LICENSE file.
- The README line that installs plugin-settings with the rest of plugin-dev names claude-code-marketplace, not the repository's own marketplace name, claude-plugins-official.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - plugins/plugin-dev/skills/plugin-settings/SKILL.md
- plugins/plugin-dev/skills/plugin-settings/scripts/parse-frontmatter.sh
- plugins/plugin-dev/skills/plugin-settings/scripts/validate-settings.sh (checks 1-5)
- plugins/plugin-dev/skills/plugin-settings/examples/read-settings-hook.sh
- plugins/plugin-dev/README.md
- plugins/plugin-dev/LICENSE
- .claude-plugin/marketplace.json (name and plugin-dev entry)

### Our findings

 - plugin-settings declares no allowed-tools; its frontmatter has only name, description and version.
- parse-frontmatter.sh prints the whole frontmatter, or one field's value with surrounding quotes stripped, and exits 1 when the file, the frontmatter or the field is missing.
- validate-settings.sh checks that the file exists and is readable, has at least two --- markers and has non-empty frontmatter, and prints a warning when the frontmatter has no key: value pair.
- The security section says to escape quotes in user input before writing a settings file, reject paths containing .., keep the file readable by the user only (chmod 600) and not commit or share it.

### Not established by this review

 - Neither script nor the example hook was run.
- references/parsing-techniques.md, references/real-world-examples.md, examples/create-settings-command.md and examples/example-settings.md were not opened.
- Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md)
 - The plugin-dev README prints `/plugin install plugin-dev@claude-code-marketplace`. That suffix names claude-code-marketplace, whereas this repository's marketplace file is named claude-plugins-official, and plugin-settings comes with the whole plugin-dev plugin through that line, so install.command is null.
- The README's other form, for local development, is `cc --plugin-dir /path/to/plugin-dev`.
- Neither form was executed in this review.

### Before you start

 - Claude Code plugin hooks, commands or agents that read the settings file
- Bash, sed, grep and awk for scripts/; jq for examples/read-settings-hook.sh

### Compatibility

Claude Code

### Guidance plus Bash scripts that read local .local.md settings files

 - Tool use follows the host session, since plugin-settings declares no allowed-tools
- parse-frontmatter.sh and validate-settings.sh read the settings file named on their command line and print to the terminal
- Settings files live in the project's .claude/ directory; commands built from the pattern create them from user input

### Cost model

Apache-2.0 per plugins/plugin-dev/LICENSE; local files and shell tools only

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [plugin-settings SKILL.md ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/SKILL.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/SKILL.md Supports: upstreamDescription, summary, whySelected[0], whySelected[1], bestFor[0], bestFor[1], limitations[1], limitations[2], limitations[3], limitations[4], compatibility, review.findings[0], review.findings[3], access.permissions[0], access.permissions[2]
- [plugin-settings scripts/parse-frontmatter.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/scripts/parse-frontmatter.sh) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/scripts/parse-frontmatter.sh Supports: whySelected[1], bestFor[2], review.findings[1], access.permissions[1], install.prerequisites[1]
- [plugin-settings scripts/validate-settings.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/scripts/validate-settings.sh) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/scripts/validate-settings.sh Supports: whySelected[1], review.findings[2], access.permissions[1]
- [plugin-settings examples/read-settings-hook.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/examples/read-settings-hook.sh) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/plugin-settings/examples/read-settings-hook.sh Supports: whySelected[1], install.prerequisites[1]
- [plugin-dev README ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md Supports: install.sourceUrl, install.steps[0], install.steps[1], install.prerequisites[0], limitations[5], limitations[6], compatibility
- [plugin-dev LICENSE ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE Supports: license, limitations[5], access.cost
- [Marketplace file, name and plugin-dev entry ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json Supports: limitations[6], install.steps[0]

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Hook Development for Claude Code Plugins ↗ Explains how to write Claude Code plugin hooks, prompt-based and command-based, with their event list, input and output JSON and exit codes, and ships Bash utilities to validate, lint and test them.](/skills/anthropic-hook-development/)[### MCP Integration for Claude Code Plugins ↗ Explains how a Claude Code plugin bundles MCP servers, through .mcp.json or plugin.json, for stdio, SSE, HTTP and WebSocket servers, and how plugin commands pre-allow the resulting MCP tools.](/skills/anthropic-mcp-integration/)[### Agent Development for Claude Code Plugins ↗ Explains how to write a Claude Code plugin agent file (frontmatter, trigger description, system prompt) and ships a Bash script that checks one agent file.](/skills/anthropic-agent-development/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
