← Explore all 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.

“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.

Upstream setup instructions ↗
  1. 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.
  2. The README's other form, for local development, is `cc --plugin-dir /path/to/plugin-dev`.
  3. 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.

  1. 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]

  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]

  3. 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]

  4. 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]

  5. 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

  6. plugin-dev LICENSE ↗Checked

    https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE

    Supports: license, limitations[5], access.cost

  7. https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json

    Supports: limitations[6], install.steps[0]

Evidence & Ask