Plugin Settings

anthropics/claude-code/plugins/plugin-dev/skills/plugin-settings

作者 anthropics398b6d71cb850ddaa0a92e7005146d0f676a5db1無授權條款156K 個星標收錄於 2026年11月20日更新於 2026年11月20日儲存庫今天更新

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.

AI 產生的概覽

說明以 .claude/plugin-name.local.md 搭配 YAML frontmatter 與 markdown 存放專案層級外掛設定的做法。

功能
介紹 Claude Code 外掛如何把使用者可設定的設定與狀態存放在專案內的 .claude/plugin-name.local.md 檔案,以 YAML frontmatter 存結構化欄位,以 markdown 內文存提示詞或說明。說明 hook、指令與 agent 如何讀取並解析該檔案,包含擷取 frontmatter、讀取個別欄位、擷取內文,以及檔案不存在時快速結束的寫法。另涵蓋建立設定檔、預設值、驗證、gitignore 與重新啟動才生效等事項,並附上解析與驗證設定檔的輔助腳本。
適用情境
適用於開發或記錄需要專案層級、使用者可編輯設定或狀態的外掛,或當 hook、指令、agent 需要從 .local.md 檔案讀取設定時。也適用於規劃如何安全存放外掛設定並避免提交到版本控制。
執行需求
需要具備 .claude 目錄的 Claude Code 外掛專案;解析範例依賴 sed、grep、awk 等 bash 工具。附有解析 frontmatter 與驗證設定檔的可執行腳本,以及範例 hook 與指令檔案。

Plugin Settings Pattern for Claude Code Plugins

Overview

Plugins can store user-configurable settings and state in .claude/plugin-name.local.md files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.

Key characteristics:

  • File location: .claude/plugin-name.local.md in project root
  • Structure: YAML frontmatter + markdown body
  • Purpose: Per-project plugin configuration and state
  • Usage: Read from hooks, commands, and agents
  • Lifecycle: User-managed (not in git, should be in .gitignore)

File Structure

Basic Template

markdown
---enabled: truesetting1: value1setting2: value2numeric_setting: 42list_setting: ["item1", "item2"]---
# Additional Context
This markdown body can contain:- Task descriptions- Additional instructions- Prompts to feed back to Claude- Documentation or notes

Example: Plugin State File

.claude/my-plugin.local.md:

markdown
---enabled: truestrict_mode: falsemax_retries: 3notification_level: infocoordinator_session: team-leader---
# Plugin Configuration
This plugin is configured for standard validation mode.Contact @team-lead with questions.

Reading Settings Files

From Hooks (Bash Scripts)

Pattern: Check existence and parse frontmatter

bash
#!/bin/bashset -euo pipefail
# Define state file pathSTATE_FILE=".claude/my-plugin.local.md"
# Quick exit if file doesn't existif [[ ! -f "$STATE_FILE" ]]; then  exit 0  # Plugin not configured, skipfi
# Parse YAML frontmatter (between --- markers)FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
# Extract individual fieldsENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')STRICT_MODE=$(echo "$FRONTMATTER" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^"\(.*\)"$/\1/')
# Check if enabledif [[ "$ENABLED" != "true" ]]; then  exit 0  # Disabledfi
# Use configuration in hook logicif [[ "$STRICT_MODE" == "true" ]]; then  # Apply strict validation  # ...fi

See examples/read-settings-hook.sh for complete working example.

From Commands

Commands can read settings files to customize behavior:

markdown
---description: Process data with pluginallowed-tools: ["Read", "Bash"]---
# Process Command
Steps:1. Check if settings exist at `.claude/my-plugin.local.md`2. Read configuration using Read tool3. Parse YAML frontmatter to extract settings4. Apply settings to processing logic5. Execute with configured behavior

From Agents

Agents can reference settings in their instructions:

markdown
---name: configured-agentdescription: Agent that adapts to project settings---
Check for plugin settings at `.claude/my-plugin.local.md`.If present, parse YAML frontmatter and adapt behavior according to:- enabled: Whether plugin is active- mode: Processing mode (strict, standard, lenient)- Additional configuration fields

Parsing Techniques

Extract Frontmatter

bash
# Extract everything between --- markersFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

Read Individual Fields

String fields:

bash
VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')

Boolean fields:

bash
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')# Compare: if [[ "$ENABLED" == "true" ]]; then

Numeric fields:

bash
MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')# Use: if [[ $MAX -gt 100 ]]; then

Read Markdown Body

Extract content after second ---:

bash
# Get everything after closing ---BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Common Patterns

Pattern 1: Temporarily Active Hooks

Use settings file to control hook activation:

bash
#!/bin/bashSTATE_FILE=".claude/security-scan.local.md"
# Quick exit if not configuredif [[ ! -f "$STATE_FILE" ]]; then  exit 0fi
# Read enabled flagFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
if [[ "$ENABLED" != "true" ]]; then  exit 0  # Disabledfi
# Run hook logic# ...

Use case: Enable/disable hooks without editing hooks.json (requires restart).

Pattern 2: Agent State Management

Store agent-specific state and configuration:

.claude/multi-agent-swarm.local.md:

markdown
---agent_name: auth-agenttask_number: 3.5pr_number: 1234coordinator_session: team-leaderenabled: truedependencies: ["Task 3.4"]---
# Task Assignment
Implement JWT authentication for the API.
**Success Criteria:**- Authentication endpoints created- Tests passing- PR created and CI green

Read from hooks to coordinate agents:

bash
AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')
# Send notification to coordinatortmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

Pattern 3: Configuration-Driven Behavior

.claude/my-plugin.local.md:

markdown
---validation_level: strictmax_file_size: 1000000allowed_extensions: [".js", ".ts", ".tsx"]enable_logging: true---
# Validation Configuration
Strict mode enabled for this project.All writes validated against security policies.

Use in hooks or commands:

bash
LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')
case "$LEVEL" in  strict)    # Apply strict validation    ;;  standard)    # Apply standard validation    ;;  lenient)    # Apply lenient validation    ;;esac

Creating Settings Files

From Commands

Commands can create settings files:

markdown
# Setup Command
Steps:1. Ask user for configuration preferences2. Create `.claude/my-plugin.local.md` with YAML frontmatter3. Set appropriate values based on user input4. Inform user that settings are saved5. Remind user to restart Claude Code for hooks to recognize changes

Template Generation

Provide template in plugin README:

markdown
## Configuration
Create `.claude/my-plugin.local.md` in your project:
\`\`\`markdown---enabled: truemode: standardmax_retries: 3---
# Plugin Configuration
Your settings are active.\`\`\`
After creating or editing, restart Claude Code for changes to take effect.

Best Practices

File Naming

✅ DO:

  • Use .claude/plugin-name.local.md format
  • Match plugin name exactly
  • Use .local.md suffix for user-local files

❌ DON'T:

  • Use different directory (not .claude/)
  • Use inconsistent naming
  • Use .md without .local (might be committed)

Gitignore

Always add to .gitignore:

gitignore
.claude/*.local.md.claude/*.local.json

Document this in plugin README.

Defaults

Provide sensible defaults when settings file doesn't exist:

bash
if [[ ! -f "$STATE_FILE" ]]; then  # Use defaults  ENABLED=true  MODE=standardelse  # Read from file  # ...fi

Validation

Validate settings values:

bash
MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')
# Validate numeric rangeif ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then  echo "⚠️  Invalid max_value in settings (must be 1-100)" >&2  MAX=10  # Use defaultfi

Restart Requirement

Important: Settings changes require Claude Code restart.

Document in your README:

markdown
## Changing Settings
After editing `.claude/my-plugin.local.md`:1. Save the file2. Exit Claude Code3. Restart: `claude` or `cc`4. New settings will be loaded

Hooks cannot be hot-swapped within a session.

Security Considerations

Sanitize User Input

When writing settings files from user input:

bash
# Escape quotes in user inputSAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')
# Write to filecat > "$STATE_FILE" <<EOF---user_setting: "$SAFE_VALUE"---EOF

Validate File Paths

If settings contain file paths:

bash
FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')
# Check for path traversalif [[ "$FILE_PATH" == *".."* ]]; then  echo "⚠️  Invalid path in settings (path traversal)" >&2  exit 2fi

Permissions

Settings files should be:

  • Readable by user only (chmod 600)
  • Not committed to git
  • Not shared between users

Real-World Examples

multi-agent-swarm Plugin

.claude/multi-agent-swarm.local.md:

markdown
---agent_name: auth-implementationtask_number: 3.5pr_number: 1234coordinator_session: team-leaderenabled: truedependencies: ["Task 3.4"]additional_instructions: Use JWT tokens, not sessions---
# Task: Implement Authentication
Build JWT-based authentication for the REST API.Coordinate with auth-agent on shared types.

Hook usage (agent-stop-notification.sh):

  • Checks if file exists (line 15-18: quick exit if not)
  • Parses frontmatter to get coordinator_session, agent_name, enabled
  • Sends notifications to coordinator if enabled
  • Allows quick activation/deactivation via enabled: true/false

ralph-wiggum Plugin

.claude/ralph-loop.local.md:

markdown
---iteration: 1max_iterations: 10completion_promise: "All tests passing and build successful"---
Fix all the linting errors in the project.Make sure tests pass after each fix.

Hook usage (stop-hook.sh):

  • Checks if file exists (line 15-18: quick exit if not active)
  • Reads iteration count and max_iterations
  • Extracts completion_promise for loop termination
  • Reads body as the prompt to feed back
  • Updates iteration count on each loop

Quick Reference

File Location

project-root/└── .claude/    └── plugin-name.local.md

Frontmatter Parsing

bash
# Extract frontmatterFRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")
# Read fieldVALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: *//' | sed 's/^"\(.*\)"$/\1/')

Body Parsing

bash
# Extract body (after second ---)BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Quick Exit Pattern

bash
if [[ ! -f ".claude/my-plugin.local.md" ]]; then  exit 0  # Not configuredfi

Additional Resources

Reference Files

For detailed implementation patterns:

  • references/parsing-techniques.md - Complete guide to parsing YAML frontmatter and markdown bodies
  • references/real-world-examples.md - Deep dive into multi-agent-swarm and ralph-wiggum implementations

Example Files

Working examples in examples/:

  • read-settings-hook.sh - Hook that reads and uses settings
  • create-settings-command.md - Command that creates settings file
  • example-settings.md - Template settings file

Utility Scripts

Development tools in scripts/:

  • validate-settings.sh - Validate settings file structure
  • parse-frontmatter.sh - Extract frontmatter fields

Implementation Workflow

To add settings to a plugin:

  1. Design settings schema (which fields, types, defaults)
  2. Create template file in plugin documentation
  3. Add gitignore entry for .claude/*.local.md
  4. Implement settings parsing in hooks/commands
  5. Use quick-exit pattern (check file exists, check enabled field)
  6. Document settings in plugin README with template
  7. Remind users that changes require Claude Code restart

Focus on keeping settings simple and providing good defaults when settings file doesn't exist.

來源與署名

來源:anthropics/claude-code位於plugins/plugin-dev/skills/plugin-settings提交398b6d7

授權條款: 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

在 README 中新增徽章

向讀者展示該技能已收錄於 SourceWeft,徽章連結到本頁。

「Listed on SourceWeft」徽章預覽
[![Listed on SourceWeft](https://sourceweft.com/badge/skills/gh-anthropics-claude-code-plugin-settings-9c715873-plugins-plugin-dev-skills-plugin-settings-0b448f739c148777.svg)](https://sourceweft.com/skills/gh-anthropics-claude-code-plugin-settings-9c715873-plugins-plugin-dev-skills-plugin-settings-0b448f739c148777?utm_source=readme&utm_medium=badge)

檢舉或申請下架