AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载本文系统讲解 Claude Code 插件开发中的.claude/plugin-name.local.md用户配置模式插件如何在项目目录内以「YAML frontmatter Markdown 正文」的结构化文件存储用户可配置设置与运行时状态以及 Hooks、Commands、Agents 三类组件如何读取与更新这些设置。读完本文你将掌握从文件模板设计、Bash 解析、原子更新到安全校验的完整插件配置工程方案并能直接复用在当前仓库的插件开发实践中。模式总览为什么插件需要用户配置Claude Code 插件的核心组件Hooks、Commands、Agents在运行时往往需要根据用户偏好或项目环境调整行为。plugin-settings技能见 SKILL.md提出了一种官方推荐的配置承载模式在项目根目录的.claude/目录下为每个插件存放一个plugin-name.local.md文件用 YAML frontmatter 保存结构化配置用 Markdown 正文保存提示词、任务说明等自由文本。该模式的关键特征文件位置项目根目录.claude/plugin-name.local.md文件结构YAML frontmatter结构化配置 Markdown 正文提示/上下文用途每个项目独立的插件配置与状态持久化消费方Hooks、Commands、Agents 均可读取生命周期由用户管理不入 git应加入.gitignore从仓库中的真实插件可以看到这一模式的普遍落地ralph-loop插件用.claude/ralph-loop.local.md记录循环迭代状态见 stop-hook.shhookify插件的多个 hook 脚本同样读取.local.md配置文件见 pretooluse.pycode-modernization的工作流与命令也引用了该模式如 modernize-status.md。这印证了.local.md是当前仓库插件生态中事实上的配置标准。文件结构frontmatter 与正文的分工基本模板一个标准的插件设置文件由两段---分隔的 YAML frontmatter 和随后的 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 notesfrontmatter 适合存放布尔开关enabled、数值numeric_setting、枚举模式、列表等结构化数据正文则用于存放需要原样回传给 Claude 的提示词、任务描述、联系人备注等非结构化内容。这种「结构化配置 自由文本」的双层设计是插件既能程序化读取配置、又能保留自然语言上下文的关键。实例插件状态文件以下是文档给出的完整状态文件示例.claude/my-plugin.local.md--- 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.其中coordinator_session这类字段展示了设置文件用于跨会话协作的能力——插件可在多个终端会话间共享配置与状态。更丰富的字段模板含allowed_extensions列表、retry_attempts、timeout_seconds等可参考 example-settings.md。从 Hooks 读取设置Bash 解析实战Hooks 是设置文件最主要的消费方。由于 Claude Code 的 hook 脚本以 Bash或 Python执行且每次触发都重新运行解析必须轻量、健壮。文档给出的核心范式是**「快速退出 frontmatter 解析」**#!/bin/bash set -euo pipefail # Define state file path STATE_FILE.claude/my-plugin.local.md # Quick exit if file doesnt exist if [[ ! -f $STATE_FILE ]]; then exit 0 # Plugin not configured, skip fi # Parse YAML frontmatter (between --- markers) 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/) # Check if enabled if [[ $ENABLED ! true ]]; then exit 0 # Disabled fi # Use configuration in hook logic if [[ $STRICT_MODE true ]]; then # Apply strict validation # ... fi要点拆解快速退出Quick Exit文件不存在时直接exit 0既不报错也不执行逻辑——插件未配置时 hook 完全无副作用这是所有真实插件共用的第一原则。frontmatter 提取sed -n /^---$/,/^---$/{ /^---$/d; p; }取出两行---之间的内容-n抑制自动打印区间匹配两处---d删除标记行、p打印其余行。字段提取grep ^enabled:锚定行首精确匹配字段名sed s/enabled: *//剥离字段前缀与空白sed s/^\(.*\)$/\1/剥离 YAML 引号。enabled 开关几乎所有插件都以enabled: true/false作为总开关便于用户临时停用而无需删除文件。一个可直接运行、带路径拦截与文件大小校验的完整 hook 示例见 read-settings-hook.sh它演示了根据strict_mode切换校验策略、依据max_file_size限制写入内容大小的完整闭环。从 Commands 与 Agents 读取设置Commands读取配置以定制行为Commands 通过 Claude 的 Read 工具读取设置文件并解析 frontmatter。文档中的命令骨架如下--- 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注意 frontmatter 中声明allowed-tools: [Read, Bash]确保 Claude 有权限读取设置文件并执行解析命令。这与命令开发的最佳实践一致可参考 command-development 技能中的工具权限说明。Agents在指令中引用设置Agents 通过 system prompt 指示 Claude 在运行前检查设置文件--- 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 可以在不同项目、不同配置下呈现不同行为而无需修改 Agent 定义本身。解析技术深入字段、正文与边界情况各类字段的提取字符串字段含引号剥离VALUE$(echo $FRONTMATTER | grep ^field_name: | sed s/field_name: *// | sed s/^\(.*\)$/\1/)布尔字段ENABLED$(echo $FRONTMATTER | grep ^enabled: | sed s/enabled: *//) # Compare: if [[ $ENABLED true ]]; then数值字段MAX$(echo $FRONTMATTER | grep ^max_value: | sed s/max_value: *//) # Use: if [[ $MAX -gt 100 ]]; then列表字段简单场景可用子串匹配if [[ $LIST *item1* ]]严谨场景推荐先转 JSON 再用 jq 遍历LIST$(echo $FRONTMATTER | yq -o json .list 2/dev/null) echo $LIST | jq -r .[] | while read -r item; do echo Processing: $item done完整的字段解析技术含while IFS: read -r key value批量解析模式、可选字段判空、默认值兜底参见 parsing-techniques.md。提取 Markdown 正文正文第二个---之后的所有内容用 awk 提取BODY$(awk /^---$/{i; next} i2 $FILE)工作原理/^---$/匹配标记行{i; next}递增计数器并跳过标记行i2打印第二个---之后的所有行。使用i2而非i2是为了正确处理正文中再次出现---分隔线的情况——计数器只在前两个标记处递增正文内的---不会干扰提取。这一点在 ralph-loop 的真实实现中被专门注释强调见 stop-hook.sh。边界情况与安全解析引号形式YAML 允许field: value、field: value、field: value三种写法解析时需依次剥离双引号与单引号。空值与 nullfield1:、field2: 、field3: null三种情况都应判空后回退默认值if [[ -z $VALUE ]] || [[ $VALUE null ]]; then VALUEdefault; fi。特殊字符含空格、冒号、正则符号的值在 Bash 中必须始终加引号使用echo $MESSAGE。性能一次解析 frontmatter 后从缓存变量中提取多个字段避免对每个字段重复读文件hook 中先用 jq 快速过滤无关事件、仅在需要时才读取设置文件延迟加载。替代方案yq对复杂 YAML 结构文档建议用yq做正规解析brew install yqENABLED$(echo $FRONTMATTER | yq .enabled)。推荐原则简单字段用 sed/grep零依赖、跨平台复杂嵌套结构用 yq需额外安装。三大常见模式模式 1临时激活 Hooks用设置文件控制 hook 启停避免频繁编辑hooks.json改 hooks.json 需要重启 Claude Code#!/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 # Disabled fi # Run hook logic # ...适用场景安全扫描、格式检查等需要按项目/按时间段启停的 hook。hookify插件即采用类似思路通过.local.md动态控制 hook 是否生效见 pretooluse.py。模式 2Agent 状态管理将 Agent 的运行时状态写入设置文件供 hook 读取以协调多 Agent 协作.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] --- # Task Assignment Implement JWT authentication for the API. **Success Criteria:** - Authentication endpoints created - Tests passing - PR created and CI greenhook 读取后可通过tmux send-keys向协调会话发送通知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配置驱动行为按validation_level等枚举字段分发不同处理分支.claude/my-plugin.local.md:--- 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.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上述三个模式的完整形态含多 Agent 协作、循环任务等深度案例可参考 real-world-examples.md。创建设置文件命令驱动与模板化从 Commands 创建命令可以引导用户完成配置生成参考 create-settings-command.md用AskUserQuestion询问启用与否、校验模式strict/standard/lenient等偏好解析用户回答answers[0]对应 enabledanswers[1]对应 mode用 Write 工具写入.claude/my-plugin.local.md含 frontmatter 与正文告知用户文件位置、配置摘要、手动编辑方式并提醒重启 Claude Code 生效、文件已被 gitignore。写入前必须校验用户输入mode 必须合法、数值字段必须是数字、路径不得包含穿越尝试、自由文本需消毒。模板生成在插件 README 中提供配置模板让用户复制即可用## Configuration Create .claude/my-plugin.local.md in your project: 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.## 最佳实践 ### 文件命名 - ✅ 使用 .claude/plugin-name.local.md 格式文件名与插件名完全一致 - ✅ 使用 .local.md 后缀标识用户本地文件 - ❌ 不要放到 .claude/ 之外的其他目录 - ❌ 不要用不一致的命名 - ❌ 不要用不带 .local 的 .md可能被误提交。 ### Gitignore 始终在项目 .gitignore 中加入 gitignore .claude/*.local.md .claude/*.local.json并在插件 README 中说明。设置文件是用户本地的不应进入版本库。默认值设置文件缺失时提供合理默认值这是所有真实插件的共同做法if [[ ! -f $STATE_FILE ]]; then # Use defaults ENABLEDtrue MODEstandard else # Read from file # ... fi校验对解析出的值做合法性校验非法时回退默认值并输出警告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 MAX10 # Use default fi重启要求设置变更需要重启 Claude Code 才能生效hook 无法在会话内热替换。文档要求将此明确写进 README## 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安全注意事项消毒用户输入从用户输入写设置文件时先转义引号防止注入破坏 YAML 结构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 ⚠️ Invalid path in settings (path traversal) 2 exit 2 fi权限设置文件应仅用户可读chmod 600、不提交 git、不在用户间共享。配置写入命令也应校验 mode 合法性、数值类型、路径穿越与自由文本见 create-settings-command.md 的实现说明。仓库内真实案例验证ralph-loop 插件ralph-loop插件是.local.md模式在仓库中最完整的落地实现。它把循环任务的状态迭代次数、最大次数、完成承诺全部放进.claude/ralph-loop.local.md--- iteration: 1 max_iterations: 10 completion_promise: All tests passing and build successful started_at: 2025-01-15T14:30:00Z --- Fix all the linting errors in the project. Make sure tests pass after each fix.其 stop-hook.sh 完整演绎了本文的所有模式快速退出第 15-18 行文件不存在则放行退出frontmatter 解析第 21-25 行提取iteration、max_iterations、completion_promise数值校验第 38-58 行非数字字段判定状态文件损坏并清理防止算术运算崩溃状态更新第 168-170 行temp 文件 mv原子替换自增迭代计数正文回喂第 150 行用awk /^---$/{i; next} i2提取正文作为下一轮提示通过 hook 的reason字段回传给 Claude第 181-188 行。该案例同时展示了文档未展开的两个进阶点会话隔离通过session_id字段避免其他会话误触发本会话的循环见 第 27-35 行和损坏恢复解析异常时输出诊断信息并删除状态文件。多 Agent 协作场景的完整剖析含agent-stop-notification.sh的 hook 实现见 real-world-examples.md。配套工具脚本仓库为该技能提供了两个可直接复用的开发工具parse-frontmatter.sh通用 frontmatter 解析器。用法# 显示全部 frontmatter ./scripts/parse-frontmatter.sh .claude/my-plugin.local.md # 提取单个字段 ./scripts/parse-frontmatter.sh .claude/my-plugin.local.md enabled # 在脚本中取用 ENABLED$(./scripts/parse-frontmatter.sh .claude/my-plugin.local.md enabled)内部同样基于 sed/grep并支持剥离单双引号。validate-settings.sh设置文件结构校验器逐项检查文件存在与可读、---标记数量至少 2 个、frontmatter 非空、enabled/strict_mode布尔合法性、正文是否存在并列出检测到的字段。可集成进插件的测试或 CI 流程。为插件接入配置的实施工作流按文档给出的七步流程为插件添加设置能力设计设置 schema确定字段、类型与默认值在插件文档中创建模板文件在.gitignore中加入.claude/*.local.md在 hooks/commands 中实现解析逻辑使用快速退出模式先查文件存在、再查 enabled 字段在插件 README 中随模板说明设置项提醒用户修改后需重启 Claude Code。核心原则始终是保持设置简单并在设置文件缺失时提供良好的默认值。快速参考速查表文件位置project-root/ └── .claude/ └── plugin-name.local.mdfrontmatter 解析# Extract frontmatter FRONTMATTER$(sed -n /^---$/,/^---$/{ /^---$/d; p; } $FILE) # Read field VALUE$(echo $FRONTMATTER | grep ^field: | sed s/field: *// | sed s/^\(.*\)$/\1/)正文解析# Extract body (after second ---) BODY$(awk /^---$/{i; next} i2 $FILE)快速退出if [[ ! -f .claude/my-plugin.local.md ]]; then exit 0 # Not configured fi原子更新防止中断损坏TEMP_FILE${FILE}.tmp.$$ sed s/^iteration: .*/iteration: $NEXT/ $FILE $TEMP_FILE mv $TEMP_FILE $FILE避免的反模式据 real-world-examples.md硬编码绝对路径、变量不加引号、用sed -i非原子更新、不提供默认值、假设正文不含---。结语.claude/plugin-name.local.md模式的价值在于用纯文本文件同时承载结构化配置YAML frontmatter与自由内容Markdown 正文配以 sed/grep/awk 等零依赖标准工具即可完成解析天然支持 per-project 隔离、版本控制友好gitignore、用户可读可改。无论是实现可开关的 hook、多 Agent 协同状态、还是配置驱动的行为分支它都是 Claude Code 插件开发中值得优先采用的配置方案。深入源码可继续阅读 parsing-techniques.md解析技术全集、read-settings-hook.sh完整 hook 示例以及 stop-hook.sh生产级实现。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 插件设置实战.claude/plugin-name.local.md 模式在生产插件中的真实用法Claude Code 插件设置实战 .claude/plugin name.local.md 模式在生产插件中的真实用法 本文基于 Claude CodeAI 插件开发工具插件系统Velero CLI 动态资源名自动补全基于 Cobra 回调的集群资源 Tab 补全实现Velero CLI 动态资源名自动补全基于 Cobra 回调的集群资源 Tab 补全实现 导读 本设计文档 design/cli dynamic resoAI 插件开发工具插件系统Claude Code 插件配置模板实战.claude/*.local.md 设置文件的编写与解析Claude Code 插件配置模板实战.claude/ .local.md 设置文件的编写与解析 本文为 Claude Code 插件开发中的「插件设置文件AI 应用AI 技能/插件开发工具上一篇终极指南使用r0capture突破安卓SSL加密抓包全解析下一篇Video2X视频增强神器3步让老旧视频重获新生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Claude Code 插件配置模式详解：.claude/plugin-name.local.md 与 YAML Frontmatter 实战指南
AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载本文系统讲解 Claude Code 插件开发中的.claude/plugin-name.local.md用户配置模式插件如何在项目目录内以「YAML frontmatter Markdown 正文」的结构化文件存储用户可配置设置与运行时状态以及 Hooks、Commands、Agents 三类组件如何读取与更新这些设置。读完本文你将掌握从文件模板设计、Bash 解析、原子更新到安全校验的完整插件配置工程方案并能直接复用在当前仓库的插件开发实践中。模式总览为什么插件需要用户配置Claude Code 插件的核心组件Hooks、Commands、Agents在运行时往往需要根据用户偏好或项目环境调整行为。plugin-settings技能见 SKILL.md提出了一种官方推荐的配置承载模式在项目根目录的.claude/目录下为每个插件存放一个plugin-name.local.md文件用 YAML frontmatter 保存结构化配置用 Markdown 正文保存提示词、任务说明等自由文本。该模式的关键特征文件位置项目根目录.claude/plugin-name.local.md文件结构YAML frontmatter结构化配置 Markdown 正文提示/上下文用途每个项目独立的插件配置与状态持久化消费方Hooks、Commands、Agents 均可读取生命周期由用户管理不入 git应加入.gitignore从仓库中的真实插件可以看到这一模式的普遍落地ralph-loop插件用.claude/ralph-loop.local.md记录循环迭代状态见 stop-hook.shhookify插件的多个 hook 脚本同样读取.local.md配置文件见 pretooluse.pycode-modernization的工作流与命令也引用了该模式如 modernize-status.md。这印证了.local.md是当前仓库插件生态中事实上的配置标准。文件结构frontmatter 与正文的分工基本模板一个标准的插件设置文件由两段---分隔的 YAML frontmatter 和随后的 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 notesfrontmatter 适合存放布尔开关enabled、数值numeric_setting、枚举模式、列表等结构化数据正文则用于存放需要原样回传给 Claude 的提示词、任务描述、联系人备注等非结构化内容。这种「结构化配置 自由文本」的双层设计是插件既能程序化读取配置、又能保留自然语言上下文的关键。实例插件状态文件以下是文档给出的完整状态文件示例.claude/my-plugin.local.md--- 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.其中coordinator_session这类字段展示了设置文件用于跨会话协作的能力——插件可在多个终端会话间共享配置与状态。更丰富的字段模板含allowed_extensions列表、retry_attempts、timeout_seconds等可参考 example-settings.md。从 Hooks 读取设置Bash 解析实战Hooks 是设置文件最主要的消费方。由于 Claude Code 的 hook 脚本以 Bash或 Python执行且每次触发都重新运行解析必须轻量、健壮。文档给出的核心范式是**「快速退出 frontmatter 解析」**#!/bin/bash set -euo pipefail # Define state file path STATE_FILE.claude/my-plugin.local.md # Quick exit if file doesnt exist if [[ ! -f $STATE_FILE ]]; then exit 0 # Plugin not configured, skip fi # Parse YAML frontmatter (between --- markers) 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/) # Check if enabled if [[ $ENABLED ! true ]]; then exit 0 # Disabled fi # Use configuration in hook logic if [[ $STRICT_MODE true ]]; then # Apply strict validation # ... fi要点拆解快速退出Quick Exit文件不存在时直接exit 0既不报错也不执行逻辑——插件未配置时 hook 完全无副作用这是所有真实插件共用的第一原则。frontmatter 提取sed -n /^---$/,/^---$/{ /^---$/d; p; }取出两行---之间的内容-n抑制自动打印区间匹配两处---d删除标记行、p打印其余行。字段提取grep ^enabled:锚定行首精确匹配字段名sed s/enabled: *//剥离字段前缀与空白sed s/^\(.*\)$/\1/剥离 YAML 引号。enabled 开关几乎所有插件都以enabled: true/false作为总开关便于用户临时停用而无需删除文件。一个可直接运行、带路径拦截与文件大小校验的完整 hook 示例见 read-settings-hook.sh它演示了根据strict_mode切换校验策略、依据max_file_size限制写入内容大小的完整闭环。从 Commands 与 Agents 读取设置Commands读取配置以定制行为Commands 通过 Claude 的 Read 工具读取设置文件并解析 frontmatter。文档中的命令骨架如下--- 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注意 frontmatter 中声明allowed-tools: [Read, Bash]确保 Claude 有权限读取设置文件并执行解析命令。这与命令开发的最佳实践一致可参考 command-development 技能中的工具权限说明。Agents在指令中引用设置Agents 通过 system prompt 指示 Claude 在运行前检查设置文件--- 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 可以在不同项目、不同配置下呈现不同行为而无需修改 Agent 定义本身。解析技术深入字段、正文与边界情况各类字段的提取字符串字段含引号剥离VALUE$(echo $FRONTMATTER | grep ^field_name: | sed s/field_name: *// | sed s/^\(.*\)$/\1/)布尔字段ENABLED$(echo $FRONTMATTER | grep ^enabled: | sed s/enabled: *//) # Compare: if [[ $ENABLED true ]]; then数值字段MAX$(echo $FRONTMATTER | grep ^max_value: | sed s/max_value: *//) # Use: if [[ $MAX -gt 100 ]]; then列表字段简单场景可用子串匹配if [[ $LIST *item1* ]]严谨场景推荐先转 JSON 再用 jq 遍历LIST$(echo $FRONTMATTER | yq -o json .list 2/dev/null) echo $LIST | jq -r .[] | while read -r item; do echo Processing: $item done完整的字段解析技术含while IFS: read -r key value批量解析模式、可选字段判空、默认值兜底参见 parsing-techniques.md。提取 Markdown 正文正文第二个---之后的所有内容用 awk 提取BODY$(awk /^---$/{i; next} i2 $FILE)工作原理/^---$/匹配标记行{i; next}递增计数器并跳过标记行i2打印第二个---之后的所有行。使用i2而非i2是为了正确处理正文中再次出现---分隔线的情况——计数器只在前两个标记处递增正文内的---不会干扰提取。这一点在 ralph-loop 的真实实现中被专门注释强调见 stop-hook.sh。边界情况与安全解析引号形式YAML 允许field: value、field: value、field: value三种写法解析时需依次剥离双引号与单引号。空值与 nullfield1:、field2: 、field3: null三种情况都应判空后回退默认值if [[ -z $VALUE ]] || [[ $VALUE null ]]; then VALUEdefault; fi。特殊字符含空格、冒号、正则符号的值在 Bash 中必须始终加引号使用echo $MESSAGE。性能一次解析 frontmatter 后从缓存变量中提取多个字段避免对每个字段重复读文件hook 中先用 jq 快速过滤无关事件、仅在需要时才读取设置文件延迟加载。替代方案yq对复杂 YAML 结构文档建议用yq做正规解析brew install yqENABLED$(echo $FRONTMATTER | yq .enabled)。推荐原则简单字段用 sed/grep零依赖、跨平台复杂嵌套结构用 yq需额外安装。三大常见模式模式 1临时激活 Hooks用设置文件控制 hook 启停避免频繁编辑hooks.json改 hooks.json 需要重启 Claude Code#!/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 # Disabled fi # Run hook logic # ...适用场景安全扫描、格式检查等需要按项目/按时间段启停的 hook。hookify插件即采用类似思路通过.local.md动态控制 hook 是否生效见 pretooluse.py。模式 2Agent 状态管理将 Agent 的运行时状态写入设置文件供 hook 读取以协调多 Agent 协作.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] --- # Task Assignment Implement JWT authentication for the API. **Success Criteria:** - Authentication endpoints created - Tests passing - PR created and CI greenhook 读取后可通过tmux send-keys向协调会话发送通知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配置驱动行为按validation_level等枚举字段分发不同处理分支.claude/my-plugin.local.md:--- 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.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上述三个模式的完整形态含多 Agent 协作、循环任务等深度案例可参考 real-world-examples.md。创建设置文件命令驱动与模板化从 Commands 创建命令可以引导用户完成配置生成参考 create-settings-command.md用AskUserQuestion询问启用与否、校验模式strict/standard/lenient等偏好解析用户回答answers[0]对应 enabledanswers[1]对应 mode用 Write 工具写入.claude/my-plugin.local.md含 frontmatter 与正文告知用户文件位置、配置摘要、手动编辑方式并提醒重启 Claude Code 生效、文件已被 gitignore。写入前必须校验用户输入mode 必须合法、数值字段必须是数字、路径不得包含穿越尝试、自由文本需消毒。模板生成在插件 README 中提供配置模板让用户复制即可用## Configuration Create .claude/my-plugin.local.md in your project: 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.## 最佳实践 ### 文件命名 - ✅ 使用 .claude/plugin-name.local.md 格式文件名与插件名完全一致 - ✅ 使用 .local.md 后缀标识用户本地文件 - ❌ 不要放到 .claude/ 之外的其他目录 - ❌ 不要用不一致的命名 - ❌ 不要用不带 .local 的 .md可能被误提交。 ### Gitignore 始终在项目 .gitignore 中加入 gitignore .claude/*.local.md .claude/*.local.json并在插件 README 中说明。设置文件是用户本地的不应进入版本库。默认值设置文件缺失时提供合理默认值这是所有真实插件的共同做法if [[ ! -f $STATE_FILE ]]; then # Use defaults ENABLEDtrue MODEstandard else # Read from file # ... fi校验对解析出的值做合法性校验非法时回退默认值并输出警告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 MAX10 # Use default fi重启要求设置变更需要重启 Claude Code 才能生效hook 无法在会话内热替换。文档要求将此明确写进 README## 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安全注意事项消毒用户输入从用户输入写设置文件时先转义引号防止注入破坏 YAML 结构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 ⚠️ Invalid path in settings (path traversal) 2 exit 2 fi权限设置文件应仅用户可读chmod 600、不提交 git、不在用户间共享。配置写入命令也应校验 mode 合法性、数值类型、路径穿越与自由文本见 create-settings-command.md 的实现说明。仓库内真实案例验证ralph-loop 插件ralph-loop插件是.local.md模式在仓库中最完整的落地实现。它把循环任务的状态迭代次数、最大次数、完成承诺全部放进.claude/ralph-loop.local.md--- iteration: 1 max_iterations: 10 completion_promise: All tests passing and build successful started_at: 2025-01-15T14:30:00Z --- Fix all the linting errors in the project. Make sure tests pass after each fix.其 stop-hook.sh 完整演绎了本文的所有模式快速退出第 15-18 行文件不存在则放行退出frontmatter 解析第 21-25 行提取iteration、max_iterations、completion_promise数值校验第 38-58 行非数字字段判定状态文件损坏并清理防止算术运算崩溃状态更新第 168-170 行temp 文件 mv原子替换自增迭代计数正文回喂第 150 行用awk /^---$/{i; next} i2提取正文作为下一轮提示通过 hook 的reason字段回传给 Claude第 181-188 行。该案例同时展示了文档未展开的两个进阶点会话隔离通过session_id字段避免其他会话误触发本会话的循环见 第 27-35 行和损坏恢复解析异常时输出诊断信息并删除状态文件。多 Agent 协作场景的完整剖析含agent-stop-notification.sh的 hook 实现见 real-world-examples.md。配套工具脚本仓库为该技能提供了两个可直接复用的开发工具parse-frontmatter.sh通用 frontmatter 解析器。用法# 显示全部 frontmatter ./scripts/parse-frontmatter.sh .claude/my-plugin.local.md # 提取单个字段 ./scripts/parse-frontmatter.sh .claude/my-plugin.local.md enabled # 在脚本中取用 ENABLED$(./scripts/parse-frontmatter.sh .claude/my-plugin.local.md enabled)内部同样基于 sed/grep并支持剥离单双引号。validate-settings.sh设置文件结构校验器逐项检查文件存在与可读、---标记数量至少 2 个、frontmatter 非空、enabled/strict_mode布尔合法性、正文是否存在并列出检测到的字段。可集成进插件的测试或 CI 流程。为插件接入配置的实施工作流按文档给出的七步流程为插件添加设置能力设计设置 schema确定字段、类型与默认值在插件文档中创建模板文件在.gitignore中加入.claude/*.local.md在 hooks/commands 中实现解析逻辑使用快速退出模式先查文件存在、再查 enabled 字段在插件 README 中随模板说明设置项提醒用户修改后需重启 Claude Code。核心原则始终是保持设置简单并在设置文件缺失时提供良好的默认值。快速参考速查表文件位置project-root/ └── .claude/ └── plugin-name.local.mdfrontmatter 解析# Extract frontmatter FRONTMATTER$(sed -n /^---$/,/^---$/{ /^---$/d; p; } $FILE) # Read field VALUE$(echo $FRONTMATTER | grep ^field: | sed s/field: *// | sed s/^\(.*\)$/\1/)正文解析# Extract body (after second ---) BODY$(awk /^---$/{i; next} i2 $FILE)快速退出if [[ ! -f .claude/my-plugin.local.md ]]; then exit 0 # Not configured fi原子更新防止中断损坏TEMP_FILE${FILE}.tmp.$$ sed s/^iteration: .*/iteration: $NEXT/ $FILE $TEMP_FILE mv $TEMP_FILE $FILE避免的反模式据 real-world-examples.md硬编码绝对路径、变量不加引号、用sed -i非原子更新、不提供默认值、假设正文不含---。结语.claude/plugin-name.local.md模式的价值在于用纯文本文件同时承载结构化配置YAML frontmatter与自由内容Markdown 正文配以 sed/grep/awk 等零依赖标准工具即可完成解析天然支持 per-project 隔离、版本控制友好gitignore、用户可读可改。无论是实现可开关的 hook、多 Agent 协同状态、还是配置驱动的行为分支它都是 Claude Code 插件开发中值得优先采用的配置方案。深入源码可继续阅读 parsing-techniques.md解析技术全集、read-settings-hook.sh完整 hook 示例以及 stop-hook.sh生产级实现。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 插件设置实战.claude/plugin-name.local.md 模式在生产插件中的真实用法Claude Code 插件设置实战 .claude/plugin name.local.md 模式在生产插件中的真实用法 本文基于 Claude CodeAI 插件开发工具插件系统Velero CLI 动态资源名自动补全基于 Cobra 回调的集群资源 Tab 补全实现Velero CLI 动态资源名自动补全基于 Cobra 回调的集群资源 Tab 补全实现 导读 本设计文档 design/cli dynamic resoAI 插件开发工具插件系统Claude Code 插件配置模板实战.claude/*.local.md 设置文件的编写与解析Claude Code 插件配置模板实战.claude/ .local.md 设置文件的编写与解析 本文为 Claude Code 插件开发中的「插件设置文件AI 应用AI 技能/插件开发工具上一篇终极指南使用r0capture突破安卓SSL加密抓包全解析下一篇Video2X视频增强神器3步让老旧视频重获新生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
