Plugin Settings Pattern Skill

A Claude Code skill for implementing user-configurable settings in Claude Code plugins — covering settings storage, schema definitions, defaults, validation, and runtime access patterns.

When to Use This Skill

Choose this skill when:

• Adding user configuration to a Claude Code plugin
• Defining settings schema with types and defaults
• Storing persistent settings in project-level files
• Reading and validating plugin settings at runtime
• Building settings migration for plugin updates

Consider alternatives when:

• You need environment-specific config (use .env files)
• You need machine-level settings (use the global Claude config)
• You need one-time configuration (use command arguments)

Quick Start

Copy
// plugin.json - Define settings schema
{
  "name": "my-plugin",
  "version": "1.0.0",
  "settings": {
    "language": {
      "type": "string",
      "default": "typescript",
      "description": "Default programming language for code generation",
      "enum": ["typescript", "javascript", "python"]
    },
    "strictMode": {
      "type": "boolean",
      "default": true,
      "description": "Enable strict validation rules"
    },
    "maxFiles": {
      "type": "number",
      "default": 10,
      "description": "Maximum files to process in a single batch"
    }
  }
}

Copy
<!-- .claude/my-plugin.local.md - User's local settings -->
# My Plugin Settings

language: python
strictMode: false
maxFiles: 25

Core Concepts

Settings Architecture

Layer	File	Purpose
Schema	plugin.json → settings	Define available settings with types and defaults
Global	~/.claude/plugins/my-plugin/settings.md	User-level defaults
Project	.claude/my-plugin.local.md	Project-specific overrides
Runtime	Environment variables	Temporary overrides

Settings Types

Type	Format	Example
string	Plain text or enum	language: typescript
boolean	true or false	strictMode: true
number	Integer or float	maxFiles: 10
array	Comma-separated or list	ignorePatterns: *.test.ts, *.spec.ts
object	Key-value pairs	database: { host: localhost, port: 5432 }

Reading Settings in Skills

Copy
# skills/code-generator.md
---
description: Generate code with configured settings
---

Before generating code:
1. Read `.claude/my-plugin.local.md` for user settings
2. Apply defaults from plugin.json for any missing settings
3. Use the configured language and strictMode settings

Generate code in the user's preferred language.
If strictMode is enabled, include type annotations and error handling.

Configuration

Parameter	Type	Default	Description
type	string	—	Setting type: string, boolean, number, array
default	any	—	Default value when not configured
description	string	—	Help text for the setting
enum	array	—	Allowed values (for string type)
min	number	—	Minimum value (for number type)
max	number	—	Maximum value (for number type)
required	boolean	false	Whether the setting must be configured

Best Practices

1. Define sensible defaults for every setting — plugins should work out of the box without any configuration; defaults should cover the most common use case.

2. Use .local.md file extension for project settings — the .local suffix signals the file contains local configuration that may contain preferences; add it to .gitignore if it contains user-specific values.

3. Validate settings at the start of skill execution — check that configured values match the schema (type, enum, range) and fall back to defaults for invalid values rather than crashing.

4. Document each setting in the plugin README — list all settings with their types, defaults, and descriptions so users know what they can configure without reading the source.

5. Support both project-level and global settings — project settings override global settings; this lets users set personal defaults while allowing per-project customization.

Common Issues

Settings file not found — The plugin looks for .claude/plugin-name.local.md in the project root. Ensure the file exists and the plugin name matches exactly.

Boolean settings parsed as strings — When reading from markdown files, true and false are strings. Convert them: value === 'true' or use a proper parser.

Settings reset after plugin update — Plugin updates should not overwrite user settings files. Only update the schema in plugin.json; add migration logic for renamed or removed settings.