Plugin settings

Plugin Settings

Manage per-project plugin configuration stored in .claude/<plugin-name>.local.md files with YAML frontmatter. This is for users who need to create, inspect, or update plugin settings without touching any other project files.

When to use

• The user asks to set up or configure a plugin for a project.
• The user wants to read the current settings for a plugin.
• The user wants to change a plugin setting such as mode, enabled state, or max_retries.
• The user asks what defaults a plugin is using when no config file exists.
• The user wants the markdown body of a settings file presented as context or instructions.

Workflows

Read Plugin Settings

Inputs: Plugin name.

1. Check whether .claude/<plugin-name>.local.md exists.
2. If it does not exist, use defaults (enabled=true, mode=standard, max_retries=3) and report that no custom config is set.
3. If it exists, read it with the Read tool.
4. Parse the YAML frontmatter between the first two --- markers using sed.
5. Extract string, boolean, and numeric fields individually with grep and sed.
6. Report each field's value exactly; never estimate or round numbers.

Check: Every field in the frontmatter is reported with its exact value. Output: A list of field names and their values, plus a note if defaults are in use.

Extract Markdown Body

Inputs: The settings file contents.

1. After reading the settings file, locate the closing YAML frontmatter marker.
2. Use awk to capture everything after the second --- line.
3. Present the body as additional context or instructions when the user asks for it.

Check: The extracted body excludes the frontmatter and starts at the first line after the closing marker. Output: The markdown body text.

Create Plugin Settings File

Inputs: Interview the user once for: plugin name, enabled/disabled state, mode (strict, standard, lenient), max_retries (1-100), and any string settings.

1. Gather all interview answers in a single pass.
2. Create .claude/<plugin-name>.local.md with YAML frontmatter containing those fields.
3. Add a markdown body noting the configuration.
4. Escape double quotes in user input using sed.
5. Remind the user to add .claude/*.local.md to .gitignore.
6. Remind the user to restart Claude Code for hooks to recognize the new settings.
7. Save the interview answers so you never ask again for that plugin.

Check: The file exists at the correct path, frontmatter parses cleanly, and quoted values are escaped. Output: Confirmation of the created file, its contents, and the two reminders.

Update Existing Settings

Inputs: Plugin name and the setting(s) to change.

1. Read the current settings file.
2. Validate numeric ranges: max_retries must be 1-100, max_file_size must be 1-1000000.
3. Reject path traversal attempts (values containing ..).
4. Warn about invalid values and suggest using the default.
5. Write the updated file.
6. Remind the user to restart Claude Code for changes to take effect.

Check: Updated values fall within valid ranges and contain no .. sequences. Output: The updated file contents and the restart reminder.

Provide Default Configuration

Inputs: Plugin name.

1. If no settings file exists for the plugin, assume defaults: enabled=true, mode=standard, max_retries=3.
2. Report that the plugin is using defaults.
3. Offer to create a custom configuration file.
4. Never apply plugin behavior or logic yourself; only manage the configuration.

Check: Defaults are stated exactly and no plugin logic is executed. Output: A statement of the default values and an offer to create a config file.

Tools and data

• Use the Read tool when available to read settings files.
• Use the Bash tool when available for sed, grep, and awk parsing.
• If a tool is not available, ask the user to provide the file contents or connect it.

Guardrails

• Never modify files outside the .claude/ directory.
• Only parse and create .local.md files; never touch hooks.json or other project configuration.
• Do not apply plugin logic or execute plugin behavior based on settings.
• Always warn the user to restart Claude Code after creating or editing a settings file, and never claim changes take effect immediately within the session.
• Never estimate or round numeric values when reporting settings.

Getting started

Ask the user which plugin they want to configure (provide the name). Then interview once for enabled/disabled state, mode, max_retries, and any string settings they want to store.

Credits

Adapted from an open-source original (MIT): https://www.aitmpl.com/component/skills/development/plugin-settings