SuperAPI AI 工具集

configuring-plugin-settings

编程与开发

查看项目

更新于 10-16 07:06

技能介绍

用途

本技能用于指导开发者为 Claude Code 插件实现「用户可配置的设置与状态」,核心是项目目录下的 .claude/plugin-name.local.md 文件模式。该文件用 YAML frontmatter 承载结构化配置,用 Markdown 正文承载提示词或补充上下文,让插件具备按项目定制的行为。

主要能力

  • 文件结构约定:位置为项目根目录 .claude/plugin-name.local.md;结构为 YAML frontmatter + Markdown 正文;用途为按项目的插件配置与状态;由用户管理,不纳入 git。
  • 多入口读取:可从 hooks(Bash 脚本)、commands、agents 中读取设置文件并解析。
  • 解析技巧:提供了用 sed、grep、awk 提取 frontmatter、读取字符串/布尔/数值字段、以及读取第二个 --- 之后正文的方法。
  • 常见模式:临时启用的 hooks(通过 enabled 标志控制)、多 agent 状态管理(存 agent 名称、任务号、PR 号、协调会话、依赖等)、配置驱动行为(如 validation_level: strict/standard/lenient 决定校验策略)。
  • 设置文件创建:可由命令向用户询问配置偏好后生成文件,并在 README 中提供模板。
  • 最佳实践:命名规范(.claude/plugin-name.local.md、.local.md 后缀)、加入 .gitignore、提供默认值、校验取值、说明修改后需重启。
  • 安全注意事项:写入用户输入时转义引号、检查路径穿越(..)、设置文件权限只读于用户(chmod 600)、不提交、不跨用户共享。

使用方式

  1. 设计设置 schema(字段、类型、默认值)。
  2. 在插件文档中提供模板文件。
  3. 为 .claude/*.local.md 添加 gitignore 条目。
  4. 在 hooks/commands 中实现设置解析。
  5. 使用「快速退出」模式:文件不存在或 enabled 不为 true 时直接结束。
  6. 在插件 README 中记录设置与模板。
  7. 提醒用户修改设置后需重启 Claude Code(hooks 无法在会话内热替换)。

关键解析示例:

# 提取 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

适用场景

适用于为 Claude Code 插件添加按项目生效的可配置项与状态,例如:通过 enabled 快速启用/停用某个 hook、多 agent 协同任务的状态与协调、按配置切换校验严格程度等。文档给出了 multi-agent-swarm 与 ralph-wiggum 两个实际示例。

限制

  • 设置变更需要重启 Claude Code 才能生效,hooks 不能在单次会话内热切换。
  • 设置文件应由用户本地管理,不应提交 git,也不应在用户之间共享。
  • 其他具体功能、收费、价格、平台与效果信息暂未提供。