⚡

插件设置模式 plugin-settings

Claude代码插件配置管理技能，提供插件设置文件创建、读取、解析和管理的完整解决方案。关键词：Claude插件配置、YAML frontmatter解析、插件状态管理、项目特定设置、钩子配置、代理协调、配置驱动开发、插件自定义设置、开发工具配置、AI助手插件开发

DevOps 0 次安装 0 次浏览 更新于 3/2/2026

name: plugin-settings description: 当用户询问“插件设置”、“存储插件配置”、“用户可配置插件”、“.local.md文件”、“插件状态文件”、“读取YAML frontmatter”、“每个项目的插件设置”，或希望使插件行为可配置时使用此技能。记录.claude/插件名称.local.md模式，用于通过YAML frontmatter和markdown内容存储插件特定配置。 version: 0.1.0

Claude代码插件的插件设置模式

概述

插件可以在项目目录内的.claude/插件名称.local.md文件中存储用户可配置的设置和状态。此模式使用YAML frontmatter进行结构化配置，并使用markdown内容作为提示或附加上下文。

关键特性:

  • 文件位置: 项目根目录下的.claude/插件名称.local.md
  • 结构: YAML frontmatter + markdown正文
  • 目的: 每个项目的插件配置和状态
  • 使用: 从钩子、命令和代理中读取
  • 生命周期: 用户管理（不在git中，应放在.gitignore中）

文件结构

基本模板

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

# 附加上下文

此markdown正文可以包含:
- 任务描述
- 附加指令
- 反馈给Claude的提示
- 文档或笔记

示例: 插件状态文件

.claude/my-plugin.local.md:

---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

# 插件配置

此插件为标准验证模式配置。
如有问题请联系@team-lead。

读取设置文件

从钩子（Bash脚本）

模式: 检查存在性并解析frontmatter

#!/bin/bash
set -euo pipefail

# 定义状态文件路径
STATE_FILE=".claude/my-plugin.local.md"

# 如果文件不存在则快速退出
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0  # 插件未配置，跳过
fi

# 解析YAML frontmatter（在---标记之间）
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# 提取单个字段
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/')

# 检查是否启用
if [[ "$ENABLED" != "true" ]]; then
  exit 0  # 已禁用
fi

# 在钩子逻辑中使用配置
if [[ "$STRICT_MODE" == "true" ]]; then
  # 应用严格验证
  # ...
fi

完整工作示例请参见examples/read-settings-hook.sh。

从命令

命令可以读取设置文件以自定义行为:

---
description: 使用插件处理数据
allowed-tools: ["Read", "Bash"]
---

# 处理命令

步骤:
1. 检查设置是否存在于`.claude/my-plugin.local.md`
2. 使用Read工具读取配置
3. 解析YAML frontmatter以提取设置
4. 将设置应用于处理逻辑
5. 使用配置的行为执行

从代理

代理可以在其指令中引用设置:

---
name: configured-agent
description: 适应项目设置的代理
---

检查`.claude/my-plugin.local.md`处的插件设置。
如果存在，解析YAML frontmatter并根据以下内容调整行为:
- enabled: 插件是否激活
- mode: 处理模式（严格、标准、宽松）
- 附加配置字段

解析技术

提取Frontmatter

# 提取---标记之间的所有内容
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

读取单个字段

字符串字段:

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

布尔字段:

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

数字字段:

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

读取Markdown正文

提取第二个---之后的内容:

# 获取结束---之后的所有内容
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

常见模式

模式1: 临时激活钩子

使用设置文件控制钩子激活:

#!/bin/bash
STATE_FILE=".claude/security-scan.local.md"

# 如果未配置则快速退出
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0
fi

# 读取启用标志
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

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

# 运行钩子逻辑
# ...

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

模式2: 代理状态管理

存储代理特定状态和配置:

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

---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
---

# 任务分配

为API实现JWT身份验证。

**成功标准:**
- 创建身份验证端点
- 测试通过
- 创建PR且CI通过

从钩子读取以协调代理:

AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')
COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')

# 向协调者发送通知
tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

模式3: 配置驱动行为

.claude/my-plugin.local.md:

---
validation_level: strict
max_file_size: 1000000
allowed_extensions: [".js", ".ts", ".tsx"]
enable_logging: true
---

# 验证配置

此项目启用严格模式。
所有写入都根据安全策略进行验证。

在钩子或命令中使用:

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

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

创建设置文件

从命令

命令可以创建设置文件:

# 设置命令

步骤:
1. 询问用户配置偏好
2. 使用YAML frontmatter创建`.claude/my-plugin.local.md`
3. 根据用户输入设置适当的值
4. 通知用户设置已保存
5. 提醒用户重启Claude Code以使钩子识别更改

模板生成

在插件README中提供模板:

## 配置

在您的项目中创建`.claude/my-plugin.local.md`:

\`\`\`markdown
---
enabled: true
mode: standard
max_retries: 3
---

# 插件配置

您的设置已激活。
\`\`\`

创建或编辑后，重启Claude Code以使更改生效。

最佳实践

文件命名

✅ 应做:

  • 使用.claude/插件名称.local.md格式
  • 与插件名称完全匹配
  • 对用户本地文件使用.local.md后缀

❌ 不应做:

  • 使用不同的目录（非.claude/）
  • 使用不一致的命名
  • 使用没有.local的.md（可能会被提交）

Gitignore

始终添加到.gitignore:

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

在插件README中记录此内容。

默认值

当设置文件不存在时提供合理的默认值:

if [[ ! -f "$STATE_FILE" ]]; then
  # 使用默认值
  ENABLED=true
  MODE=standard
else
  # 从文件读取
  # ...
fi

验证

验证设置值:

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

# 验证数字范围
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
  echo "⚠️  设置中的max_value无效（必须为1-100）" >&2
  MAX=10  # 使用默认值
fi

重启要求

重要: 设置更改需要重启Claude Code。

在您的README中记录:

## 更改设置

编辑`.claude/my-plugin.local.md`后:
1. 保存文件
2. 退出Claude Code
3. 重启: `claude` 或 `cc`
4. 新设置将被加载

钩子不能在会话内热交换。

安全考虑

清理用户输入

从用户输入写入设置文件时:

# 转义用户输入中的引号
SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')

# 写入文件
cat > "$STATE_FILE" <<EOF
---
user_setting: "$SAFE_VALUE"
---
EOF

验证文件路径

如果设置包含文件路径:

FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')

# 检查路径遍历
if [[ "$FILE_PATH" == *".."* ]]; then
  echo "⚠️  设置中的路径无效（路径遍历）" >&2
  exit 2
fi

权限

设置文件应:

  • 仅用户可读（chmod 600）
  • 不提交到git
  • 不在用户之间共享

实际示例

multi-agent-swarm插件

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

---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: 使用JWT令牌，而非会话
---

# 任务: 实现身份验证

为REST API构建基于JWT的身份验证。
与auth-agent协调共享类型。

钩子使用（agent-stop-notification.sh）:

  • 检查文件是否存在（第15-18行: 如果不存在则快速退出）
  • 解析frontmatter以获取coordinator_session、agent_name、enabled
  • 如果启用则向协调者发送通知
  • 允许通过enabled: true/false快速激活/停用

ralph-loop插件

.claude/ralph-loop.local.md:

---
iteration: 1
max_iterations: 10
completion_promise: "所有测试通过且构建成功"
---

修复项目中的所有linting错误。
确保每次修复后测试通过。

钩子使用（stop-hook.sh）:

  • 检查文件是否存在（第15-18行: 如果不活动则快速退出）
  • 读取迭代计数和max_iterations
  • 提取completion_promise用于循环终止
  • 读取正文作为反馈的提示
  • 每次循环更新迭代计数

快速参考

文件位置

项目根目录/
└── .claude/
    └── 插件名称.local.md

Frontmatter解析

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

# 读取字段
VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: *//' | sed 's/^"\(.*\)"$/\1/')

正文解析

# 提取正文（第二个---之后）
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

快速退出模式

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

附加资源

参考文件

有关详细实现模式:

  • references/parsing-techniques.md - 解析YAML frontmatter和markdown正文的完整指南
  • references/real-world-examples.md - multi-agent-swarm和ralph-loop实现的深入探讨

示例文件

examples/中的工作示例:

  • read-settings-hook.sh - 读取并使用设置的钩子
  • create-settings-command.md - 创建设置文件的命令
  • example-settings.md - 模板设置文件

实用脚本

scripts/中的开发工具:

  • validate-settings.sh - 验证设置文件结构
  • parse-frontmatter.sh - 提取frontmatter字段

实现工作流

向插件添加设置:

  1. 设计设置模式（哪些字段、类型、默认值）
  2. 在插件文档中创建模板文件
  3. 为.claude/*.local.md添加gitignore条目
  4. 在钩子/命令中实现设置解析
  5. 使用快速退出模式（检查文件是否存在，检查启用字段）
  6. 在插件README中记录设置并附带模板
  7. 提醒用户更改需要重启Claude Code

专注于保持设置简单，并在设置文件不存在时提供良好的默认值。