Claude Code Plugin Settings Pattern
Store and read project-specific plugin configuration in local Markdown state files.
The documentation describes project-local files, gitignore handling, input validation, traversal checks, and permission recommendations, with no evidence of malware, credential theft, or covert exfiltration. However, most safeguards are advisory; heredoc examples, brittle parsing, and user-controlled body content can still create injection, disclosure, or unsafe-write risks, so points are deducted.
Scripts, defaults, partial validation, atomic updates, and error messages make the happy path plausible. However, sed/grep is not full YAML parsing, missing fields can fail under set -e, the validator can overstate validity, and no tests or execution evidence are provided; the static ceiling therefore applies and points are deducted.
The trigger description clearly covers plugin settings, state files, YAML frontmatter, and per-project configuration. Boundaries are incomplete for complex YAML, concurrent updates, varying working directories, and non-Bash environments, and semantic non-trigger conditions are not explicit, so points are deducted.
The material is organized into overview, templates, parsing guidance, examples, scripts, best practices, and workflow, with a version and official organizational attribution. License terms, changelog, named maintenance responsibility, update path, and dependency-installation notes are incomplete, so points are deducted.
The templates, examples, and two utility scripts can directly support creation and reading of simple settings files and offer clear value over manual repetition. However, users must integrate the pattern themselves, parsing is limited, some examples are unsafe, and representative outputs are not verified, so points are deducted.
The selected path contains auditable source, scripts, and concrete examples supporting the main design claims. It provides no committed test suite, CI coverage, or third-party execution evidence, so static review can award only limited verifiability.
- Do not treat the sed/grep parser as a general YAML parser; complex values, colons, multiline content, lists, and quoting may be misparsed.
- When using user-controlled settings bodies in prompts or JSON, use parameterized construction and strictly constrain writable paths and sensitive fields.
- The restart requirement is asserted but not demonstrated for every relevant runtime; the consuming plugin should verify the lifecycle behavior.
- No tests or execution records cover the key scripts; add tests for malformed input, missing fields, hostile paths, and concurrent updates before deployment.
What it does & when to use it
This skill documents a pattern for storing plugin configuration and state in `.claude/plugin-name.local.md`. Each file combines YAML frontmatter for structured values with a Markdown body for prompts, notes, or additional context. It explains how hooks, commands, and agents can read the files, including field parsing, defaults, validation, Git exclusion, permissions, and restart behavior. It fits plugin authors who need per-project configuration without committing user-local settings.
Documents how to create .claude/plugin-name.local.md files, store booleans, strings, numbers, and lists in YAML frontmatter, and keep prompts or context in the Markdown body. It provides Bash examples using sed, grep, and awk to extract frontmatter fields and body content, plus patterns for hooks, commands, and agents to consume the settings. It also covers enabled-state checks, defaults, numeric validation, path-traversal checks, file permissions, .gitignore entries, and restarting Claude Code after changes.
- A plugin author needs per-project enablement for hooks and uses an `enabled` field in a local state file.
- A team coordinates multiple agents and stores task numbers, coordinator sessions, dependencies, and status locally.
- A project changes validation behavior between strict, standard, and lenient modes based on frontmatter settings.
- A plugin needs local prompts, notes, or configuration that should not be committed to Git.
Pros & cons
- Defines a clear project-local configuration convention.
- Combines structured YAML values with Markdown prompts and context.
- Includes examples for Bash parsing, defaults, validation, permissions, and Git exclusion.
- Covers use by hooks, commands, and agents.
- Provides no standalone installation or enablement command for the skill.
- Examples depend on Bash, sed, grep, and awk, so other environments may require adaptation.
- Settings changes require restarting Claude Code and are not hot-swapped in-session.
- The source provides no test results or cross-platform verification.
How to install
The source does not document a separate installation command for this skill; it is located at plugins/plugin-dev/skills/plugin-settings/SKILL.md in the repository. The README says to install Claude Code first, for example on macOS/Linux with curl -fsSL https://claude.ai/install.sh | bash, then enter a project directory and run claude. The source does not specify a separate procedure for enabling or copying this individual skill.
How to use
Create .claude/plugin-name.local.md in the project root with YAML frontmatter such as enabled: true and mode: standard, followed by any Markdown context. Have the plugin's hooks, commands, or agents read the file. After saving or editing it, exit and restart Claude Code because the documented pattern does not hot-reload settings during a session. No specific trigger command is defined in the source.