Back to Details

plugin-settings

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plugin Settings Pattern for Claude Code Plugins

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
    )
插件可以在项目目录内的
.claude/plugin-name.local.md
文件中存储用户可配置的设置和状态。该模式使用YAML frontmatter用于结构化配置，markdown内容用于提示或额外上下文。
核心特性：
  • 文件位置：项目根目录下的
    .claude/plugin-name.local.md
  • 结构：YAML frontmatter + markdown正文
  • 用途：每个项目的插件配置和状态
  • 使用场景：从钩子、命令和Agent中读取
  • 生命周期：用户管理（不纳入git，应添加到
    .gitignore
    中）

File Structure

文件结构

Basic Template

基础模板

markdown
---
enabled: true
setting1: value1
setting2: value2
numeric_setting: 42
list_setting: ["item1", "item2"]
---
markdown
---
enabled: true
setting1: value1
setting2: value2
numeric_setting: 42
list_setting: ["item1", "item2"]
---

Additional Context

额外上下文

This markdown body can contain:
  • Task descriptions
  • Additional instructions
  • Prompts to feed back to Claude
  • Documentation or notes
undefined
该markdown正文可包含：
  • 任务描述
  • 额外说明
  • 反馈给Claude的提示词
  • 文档或备注
undefined

Example: Plugin State File

示例：插件状态文件

.claude/my-plugin.local.md:
markdown
---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---
.claude/my-plugin.local.md：
markdown
---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

Plugin Configuration

插件配置

This plugin is configured for standard validation mode. Contact @team-lead with questions.
undefined
本插件已配置为标准验证模式。 如有问题请联系@team-lead。
undefined

Reading Settings Files

读取设置文件

From Hooks (Bash Scripts)

从钩子（Bash脚本）读取

Pattern: Check existence and parse frontmatter
bash
#!/bin/bash
set -euo pipefail
模式：检查文件是否存在并解析frontmatter
bash
#!/bin/bash
set -euo pipefail

Define state file path

定义状态文件路径

STATE_FILE=".claude/my-plugin.local.md"
STATE_FILE=".claude/my-plugin.local.md"

Quick exit if file doesn't exist

如果文件不存在则快速退出

if [[ ! -f "$STATE_FILE" ]]; then exit 0 # Plugin not configured, skip fi
if [[ ! -f "$STATE_FILE" ]]; then exit 0 # 插件未配置，跳过 fi

Parse YAML frontmatter (between --- markers)

解析YAML frontmatter（---标记之间的内容）

FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

Extract individual fields

提取单个字段

ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: //' | sed 's/^"(.)"$/\1/') STRICT_MODE=$(echo "$FRONTMATTER" | grep '^strict_mode:' | sed 's/strict_mode: //' | sed 's/^"(.)"$/\1/')
ENABLED=$(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 enabled

检查是否启用

if [[ "$ENABLED" != "true" ]]; then exit 0 # Disabled fi
if [[ "$ENABLED" != "true" ]]; then exit 0 # 已禁用 fi

Use configuration in hook logic

在钩子逻辑中应用配置

if [[ "$STRICT_MODE" == "true" ]]; then

Apply strict validation

...

fi

See `examples/read-settings-hook.sh` for complete working example.
if [[ "$STRICT_MODE" == "true" ]]; then

应用严格验证

...

fi

完整工作示例请查看`examples/read-settings-hook.sh`。

From Commands

从命令读取

Commands can read settings files to customize behavior:
markdown
---
description: Process data with plugin
allowed-tools: ["Read", "Bash"]
---
命令可以读取设置文件来自定义行为：
markdown
---
description: Process data with plugin
allowed-tools: ["Read", "Bash"]
---

Process Command

处理命令

Steps:
  1. Check if settings exist at 
    .claude/my-plugin.local.md
  2. Read configuration using Read tool
  3. Parse YAML frontmatter to extract settings
  4. Apply settings to processing logic
  5. Execute with configured behavior
undefined
步骤：
  1. 检查
    .claude/my-plugin.local.md
    是否存在设置
  2. 使用Read工具读取配置
  3. 解析YAML frontmatter以提取设置
  4. 将设置应用到处理逻辑
  5. 按照配置的行为执行
undefined

From Agents

从Agent读取

Agents can reference settings in their instructions:
markdown
---
name: configured-agent
description: 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
Agent可以在其指令中引用设置：
markdown
---
name: configured-agent
description: Agent that adapts to project settings
---

检查`.claude/my-plugin.local.md`中的插件设置。
如果存在，解析YAML frontmatter并根据以下内容调整行为：
- enabled：插件是否激活
- mode：处理模式（strict、standard、lenient）
- 其他配置字段

Parsing Techniques

解析技巧

Extract Frontmatter

提取Frontmatter

bash
undefined
bash
undefined

Extract everything between --- markers

提取---标记之间的所有内容

FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")
undefined
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")
undefined

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: *//')
字符串字段：
bash
VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')
布尔字段：
bash
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

Compare: if [[ "$ENABLED" == "true" ]]; then

比较：if [[ "$ENABLED" == "true" ]]; then


**Numeric fields:**
```bash
MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')

**数值字段：**
```bash
MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')

Use: if [[ $MAX -gt 100 ]]; then

使用：if [[ $MAX -gt 100 ]]; then

undefined
undefined

Read Markdown Body

读取Markdown正文

Extract content after second 
---
:
bash
undefined
提取第二个
---
之后的内容：
bash
undefined

Get everything after closing ---

获取结束---之后的所有内容

BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")
undefined
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")
undefined

Common Patterns

常见模式

Pattern 1: Temporarily Active Hooks

模式1：临时激活钩子

Use settings file to control hook activation:
bash
#!/bin/bash
STATE_FILE=".claude/security-scan.local.md"
使用设置文件控制钩子的激活：
bash
#!/bin/bash
STATE_FILE=".claude/security-scan.local.md"

Quick exit if not configured

如果未配置则快速退出

if [[ ! -f "$STATE_FILE" ]]; then exit 0 fi
if [[ ! -f "$STATE_FILE" ]]; then exit 0 fi

Read enabled flag

读取启用标志

FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE") ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
if [[ "$ENABLED" != "true" ]]; then exit 0 # Disabled fi
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE") ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
if [[ "$ENABLED" != "true" ]]; then exit 0 # 已禁用 fi

Run hook logic

运行钩子逻辑

...

...


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

**使用场景：**无需编辑hooks.json即可启用/禁用钩子（需要重启）。

Pattern 2: Agent State Management

模式2：Agent状态管理

Store agent-specific state and configuration:
.claude/multi-agent-swarm.local.md:
markdown
---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
---
存储Agent特定的状态和配置：
.claude/multi-agent-swarm.local.md：
markdown
---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["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: *//')
为API实现JWT认证。
成功标准：
  • 已创建认证端点
  • 测试通过
  • 已创建PR且CI检测通过

从钩子读取以协调Agent：

```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 coordinator

向协调者发送通知

tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter
undefined
tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter
undefined

Pattern 3: Configuration-Driven Behavior

模式3：配置驱动的行为

.claude/my-plugin.local.md:
markdown
---
validation_level: strict
max_file_size: 1000000
allowed_extensions: [".js", ".ts", ".tsx"]
enable_logging: true
---
.claude/my-plugin.local.md：
markdown
---
validation_level: strict
max_file_size: 1000000
allowed_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
本项目已启用严格模式。 所有写入操作均需符合安全策略验证。

在钩子或命令中使用：

```bash
LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')

case "$LEVEL" in
  strict)
    # 应用严格验证
    ;;
  standard)
    # 应用标准验证
    ;;
  lenient)
    # 应用宽松验证
    ;;
esac

Creating Settings Files

创建设置文件

From Commands

从命令创建

Commands can create settings files:
markdown
undefined
命令可以创建设置文件：
markdown
undefined

Setup Command

设置命令

Steps:
  1. Ask user for configuration preferences
  2. Create 
    .claude/my-plugin.local.md
    with YAML frontmatter
  3. Set appropriate values based on user input
  4. Inform user that settings are saved
  5. Remind user to restart Claude Code for hooks to recognize changes
undefined
步骤：
  1. 询问用户的配置偏好
  2. 创建包含YAML frontmatter的.claude/my-plugin.local.md文件
  3. 根据用户输入设置相应的值
  4. 告知用户设置已保存
  5. 提醒用户重启Claude Code以使钩子识别更改
undefined

Template Generation

模板生成

Provide template in plugin README:
markdown
undefined
在插件README中提供模板：
markdown
undefined

Configuration

配置

Create 
.claude/my-plugin.local.md
in your project:

```markdown

enabled: true mode: standard max_retries: 3

在你的项目中创建.claude/my-plugin.local.md：

```markdown

enabled: true mode: standard max_retries: 3

Plugin Configuration

插件配置

Your settings are active. ```
After creating or editing, restart Claude Code for changes to take effect.
undefined
你的设置已生效。 ```
创建或编辑后，请重启Claude Code以使更改生效。
undefined

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)
✅ 推荐做法：
  • 使用
    .claude/plugin-name.local.md
    格式
  • 与插件名称完全匹配
  • 使用
    .local.md
    后缀表示用户本地文件
❌ 不推荐：
  • 使用不同目录（非.claude/）
  • 使用不一致的命名
  • 使用不带
    .local
    的
    .md
    文件（可能会被提交到git）

Gitignore

Gitignore

Always add to 
.gitignore
:
gitignore
.claude/*.local.md
.claude/*.local.json
Document this in plugin README.
务必添加到.gitignore中：
gitignore
.claude/*.local.md
.claude/*.local.json
在插件README中记录此配置。

Defaults

默认值

Provide sensible defaults when settings file doesn't exist:
bash
if [[ ! -f "$STATE_FILE" ]]; then
  # Use defaults
  ENABLED=true
  MODE=standard
else
  # Read from file
  # ...
fi
当设置文件不存在时提供合理的默认值：
bash
if [[ ! -f "$STATE_FILE" ]]; then
  # 使用默认值
  ENABLED=true
  MODE=standard
else
  # 从文件读取
  # ...
fi

Validation

验证

Validate settings values:
bash
MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')
验证设置值的有效性：
bash
MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')

Validate numeric range

验证数值范围

if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then echo "⚠️ Invalid max_value in settings (must be 1-100)" >&2 MAX=10 # Use default fi
undefined
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then echo "⚠️ 设置中的max_value无效（必须为1-100）" >&2 MAX=10 # 使用默认值 fi
undefined

Restart Requirement

重启要求

Important: Settings changes require Claude Code restart.
Document in your README:
markdown
undefined
**重要提示：**更改设置后需要重启Claude Code。
在README中记录：
markdown
undefined

Changing Settings

更改设置

After editing 
.claude/my-plugin.local.md
:
  1. Save the file
  2. Exit Claude Code
  3. Restart: 
    claude
    or 
    cc
  4. New settings will be loaded

Hooks cannot be hot-swapped within a session.
编辑.claude/my-plugin.local.md后：
  1. 保存文件
  2. 退出Claude Code
  3. 重启：
    claude
    或
    cc
  4. 新设置将生效

钩子无法在会话中热替换。

Security Considerations

安全注意事项

Sanitize User Input

清理用户输入

When writing settings files from user input:
bash
undefined
当从用户输入写入设置文件时：
bash
undefined

Escape quotes in user input

转义用户输入中的引号

SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\"/g')
SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\"/g')

Write to file

写入文件

cat > "$STATE_FILE" <<EOF

user_setting: "$SAFE_VALUE"

EOF
undefined

cat > "$STATE_FILE" <<EOF

user_setting: "$SAFE_VALUE"

EOF
undefined

Validate File Paths

验证文件路径

If settings contain file paths:
bash
FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')
如果设置中包含文件路径：
bash
FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')

Check for path traversal

检查路径遍历

if [[ "$FILE_PATH" == ".." ]]; then echo "⚠️ Invalid path in settings (path traversal)" >&2 exit 2 fi
undefined
if [[ "$FILE_PATH" == ".." ]]; then echo "⚠️ 设置中的路径无效（存在路径遍历风险）" >&2 exit 2 fi
undefined

Permissions

权限

Settings files should be:
  • Readable by user only (
    chmod 600
    )
  • Not committed to git
  • Not shared between users
设置文件应：
  • 仅对用户可读（
    chmod 600
    ）
  • 不提交到git
  • 不在用户之间共享

Real-World Examples

真实世界示例

multi-agent-swarm Plugin

multi-agent-swarm插件

.claude/multi-agent-swarm.local.md:
markdown
---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: Use JWT tokens, not sessions
---
.claude/multi-agent-swarm.local.md：
markdown
---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["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`
为REST API构建基于JWT的认证。 与auth-agent协调共享类型定义。

**钩子用法（agent-stop-notification.sh）：**
- 检查文件是否存在（第15-18行：如果不存在则快速退出）
- 解析frontmatter以获取coordinator_session、agent_name和enabled字段
- 如果启用则向协调者发送通知
- 允许通过`enabled: true/false`快速激活/停用

ralph-wiggum Plugin

ralph-wiggum插件

.claude/ralph-loop.local.md:
markdown
---
iteration: 1
max_iterations: 10
completion_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
.claude/ralph-loop.local.md：
markdown
---
iteration: 1
max_iterations: 10
completion_promise: "All tests passing and build successful"
---

修复项目中的所有linting错误。
确保每次修复后测试都能通过。
钩子用法（stop-hook.sh）：
  • 检查文件是否存在（第15-18行：如果未激活则快速退出）
  • 读取迭代次数和最大迭代次数
  • 提取completion_promise用于循环终止
  • 读取正文作为反馈提示词
  • 每次循环更新迭代次数

Quick Reference

快速参考

File Location

文件位置

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

Frontmatter Parsing

Frontmatter解析

bash
undefined
bash
undefined

Extract frontmatter

提取frontmatter

FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

Read field

读取字段

VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: //' | sed 's/^"(.)"$/\1/')
undefined
VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: //' | sed 's/^"(.)"$/\1/')
undefined

Body Parsing

正文解析

bash
undefined
bash
undefined

Extract body (after second ---)

提取正文（第二个---之后的内容）

BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")
undefined
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")
undefined

Quick Exit Pattern

快速退出模式

bash
if [[ ! -f ".claude/my-plugin.local.md" ]]; then
  exit 0  # Not configured
fi
bash
if [[ ! -f ".claude/my-plugin.local.md" ]]; then
  exit 0  # 未配置
fi

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
如需详细的实现模式：
  • references/parsing-techniques.md
     - 解析YAML frontmatter和markdown正文的完整指南
  • references/real-world-examples.md
     - 深入分析multi-agent-swarm和ralph-wiggum的实现

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
examples/
目录下的工作示例：
  • read-settings-hook.sh
     - 读取并使用设置的钩子
  • create-settings-command.md
     - 创建设置文件的命令
  • example-settings.md
     - 模板设置文件

Utility Scripts

实用脚本

Development tools in 
scripts/
:
  • validate-settings.sh
     - Validate settings file structure
  • parse-frontmatter.sh
     - Extract frontmatter fields
scripts/
目录下的开发工具：
  • validate-settings.sh
     - 验证设置文件结构
  • parse-frontmatter.sh
     - 提取frontmatter字段

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.
为插件添加设置的步骤：
  1. 设计设置 schema（包含哪些字段、类型、默认值）
  2. 在插件文档中创建模板文件
  3. 添加.gitignore条目
    .claude/*.local.md
  4. 在钩子/命令中实现设置解析
  5. 使用快速退出模式（检查文件是否存在，检查enabled字段）
  6. 在插件README中记录设置并提供模板
  7. 提醒用户更改设置后需要重启Claude Code
重点在于保持设置简洁，并在设置文件不存在时提供良好的默认值。