plugin-settings_skill

Overview

This skill documents the .claude/plugin-name.local.md pattern for per-project plugin settings and state. It explains file location, YAML frontmatter structure, markdown body usage, and how hooks, commands, and agents should read and apply settings. The pattern is user-managed, kept out of git, and intended for simple configuration and small state values.

How this skill works

Plugins place a file at .claude/<plugin>.local.md containing YAML frontmatter for structured fields and a markdown body for prompts or notes. Hooks and commands detect the file, extract frontmatter (between --- markers), parse fields (strings, booleans, numbers, lists), and read the body after the second --- for additional instructions. Typical code examples use sed and awk in bash to extract frontmatter and individual values, then apply quick-exit and enabled checks before executing logic.

When to use it

• Store per-project plugin configuration that must not be committed to git
• Enable or disable plugin hooks without changing global config
• Save lightweight agent or plugin state (task numbers, coordinator session)
• Provide project-specific prompts or documentation to feed back to agents
• Let commands create or update local plugin preferences interactively

Best practices

• Name files exactly .claude/plugin-name.local.md and add .claude/*.local.md to .gitignore
• Use YAML frontmatter for structured fields and the markdown body for prompts or context
• Provide sensible defaults when the file is absent and use quick-exit patterns
• Validate numeric ranges, booleans, and paths; sanitize user input before writing
• Set file permissions to user-only (chmod 600) and document restart requirement

Example use cases

• A hook that skips or runs security scans based on enabled: true/false in .claude/security-scan.local.md
• An agent swarm storing coordinator_session and task info in .claude/multi-agent-swarm.local.md
• A command that prompts the user for preferences and writes .claude/my-plugin.local.md with sanitized values
• Validation configuration (validation_level, allowed_extensions) controlling behavior for file checks
• A stop-hook that reads a body prompt from the file to feed back into agent loops