用途
Plugin Settings 模式用于让 Claude Code 插件在项目内保存用户可配置的设置和状态。设置文件位于项目根目录的 .claude/plugin-name.local.md,采用 YAML frontmatter 加 Markdown 正文的结构,前者存放结构化配置,后者可包含提示词或额外上下文。该文件由用户管理,不进入 git,应加入 .gitignore。
主要能力
- 定义设置文件的基本结构:YAML frontmatter 可包含布尔、字符串、数字、列表等字段;Markdown 正文可包含任务描述、额外指令、反馈给 Claude 的提示词或文档说明。
- 支持从 hooks(Bash 脚本)、命令和 agents 中读取设置文件,并根据配置调整行为。
- 提供 frontmatter 与正文的解析技巧,包括提取 --- 之间的内容、读取单个字段、提取第二个 --- 之后的正文。
- 总结常见模式:用设置文件控制 hook 的临时启用;存储多 agent 协作状态(如 agent 名称、任务编号、PR 编号、协调会话、依赖列表);以及配置驱动的校验行为(如 strict/standard/lenient 模式、文件大小限制、允许的扩展名、日志开关)。
- 说明如何从命令创建设置文件、在 README 中提供模板,并提醒用户修改设置后需要重启 Claude Code。
使用方式
在项目中创建 .claude/plugin-name.local.md,按模板写入 frontmatter 和正文。在 hooks、命令或 agents 中先检查文件是否存在,不存在则按默认值处理或直接退出;存在则解析 frontmatter 字段(如 enabled、mode、max_retries 等),据此执行逻辑。技能中给出了 Bash 解析示例,包括用 sed 提取 frontmatter、用 grep/sed 读取字段、用 awk 读取正文。
适用场景
适用于需要按项目保存插件配置的 Claude Code 插件开发,尤其是需要临时启用/禁用 hooks、管理多 agent 状态、或让校验/处理行为随项目配置变化的场景。文档中提到了 multi-agent-swarm 和 ralph-loop 两个实际示例。
限制与注意事项
设置变更需要重启 Claude Code 才能生效,hooks 无法在会话内热替换。文件命名应使用 .claude/plugin-name.local.md 格式,并加入 .gitignore(如 .claude/*.local.md)。应为缺失设置文件提供合理默认值,并对设置值进行验证。从用户输入写设置文件时需转义引号,若包含文件路径需检查路径遍历。设置文件应仅用户可读(chmod 600),不提交到 git,不在用户间共享。技能还提供了 references/、examples/ 和 scripts/ 下的参考文件与工具脚本,但具体内容暂未提供。