用途
本技能用于指导开发者为 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)、不提交、不跨用户共享。
使用方式
- 设计设置 schema(字段、类型、默认值)。
- 在插件文档中提供模板文件。
- 为
.claude/*.local.md添加 gitignore 条目。 - 在 hooks/commands 中实现设置解析。
- 使用「快速退出」模式:文件不存在或
enabled不为true时直接结束。 - 在插件 README 中记录设置与模板。
- 提醒用户修改设置后需重启 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,也不应在用户之间共享。
- 其他具体功能、收费、价格、平台与效果信息暂未提供。