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.
“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.”
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.
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.
- 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
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 ↗Checked
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]
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]
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]
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 ↗Checked
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 ↗Checked
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE
Supports: license, limitations[5], access.cost
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json
Supports: limitations[6], install.steps[0]