以下为本文档的中文说明该技能用于实现Claude Code插件的用户可配置设置使用.claude/plugin-name.local.md模式来存储插件特定的配置信息。主要功能是允许插件在项目目录中存储用户可配置的设置和状态使用YAML前置元数据作为结构化配置内容。使用场景包括当用户询问插件设置、“存储插件配置”、“用户可配置插件”、.local.md文件等概念时需要为每个项目单独配置插件行为需要持久化插件的运行状态。核心文件结构包括文件位置——项目根目录下的.claude/plugin-name.local.md结构组成——YAML前置元数据加Markdown正文用途——每个项目的插件配置和状态存储使用方式——从hooks、commands和agents中读取生命周期——由用户管理不应提交到Git仓库。该技能的核心设计理念是将配置与代码分离通过本地配置文件实现对插件行为的灵活定制同时保证配置的隔离性和可移植性。Plugin Settings Pattern for Claude Code PluginsOverviewPlugins can store user-configurable settings and state in.claude/plugin-name.local.mdfiles within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional context.Key characteristics:File location:.claude/plugin-name.local.mdin project rootStructure: YAML frontmatter markdown bodyPurpose: Per-project plugin configuration and stateUsage: Read from hooks, commands, and agentsLifecycle: User-managed (not in git, should be in.gitignore)File StructureBasic Template--- 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 notesExample: Plugin State File.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.Reading Settings FilesFrom Hooks (Bash Scripts)Pattern: Check existence and parse frontmatter#!/bin/bashset-euopipefail# Define state file pathSTATE_FILE.claude/my-plugin.local.md# Quick exit if file doesnt existif[[!-f$STATE_FILE]];thenexit0# Plugin not configured, skipfi# Parse YAML frontmatter (between --- markers)FRONTMATTER$(sed-n/^---$/,/^---$/{ /^---$/d; p; }$STATE_FILE)# Extract individual fieldsENABLED$(echo$FRONTMATTER|grep^enabled:|seds/enabled: *//|seds/^\\(.*\\)$/\\1/)STRICT_MODE$(echo$FRONTMATTER|grep^strict_mode:|seds/strict_mode: *//|seds/^\\(.*\\)$/\\1/)# Check if enabledif[[$ENABLED!true]];thenexit0# Disabledfi# Use configuration in hook logicif[[$STRICT_MODEtrue]];then# Apply strict validation# ...fiSeeexamples/read-settings-hook.shfor complete working example.From CommandsCommands can read settings files to customize behavior:--- 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 behaviorFrom AgentsAgents can reference settings in their instructions:--- 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 fieldsParsing TechniquesExtract Frontmatter# Extract everything between --- markersFRONTMATTER$(sed-n/^---$/,/^---$/{ /^---$/d; p; }$FILE)Read Individual FieldsString fields:VALUE$(echo$FRONTMATTER|grep^field_name:|seds/field_name: *//|seds/^\\(.*\\)$/\\1/)Boolean fields:ENABLED$(echo$FRONTMATTER|grep^enabled:|seds/enabled: *//)# Compare: if [[ $ENABLED true ]]; thenNumeric fields:MAX$(echo$FRONTMATTER|grep^max_value:|seds/max_value: *//)# Use: if [[ $MAX -gt 100 ]]; thenRead Markdown BodyExtract content after second---:# Get everything after closing ---BODY$(awk/^---$/{i; next} i2$FILE)Common PatternsPattern 1: Temporarily Active HooksUse settings file to control hook activation:#!/bin/bashSTATE_FILE.claude/security-scan.local.md# Quick exit if not configuredif[[!-f$STATE_FILE]];thenexit0fi# Read enabled flagFRONTMATTER$(s ed-n/^---$/,/^---$/{ /^---$/d; p; }$STATE_FILE)ENABLED$(echo$FRONTMATTER|grep^enabled:|seds/enabled: *//)if[[$ENABLED!true]];thenexit0# Disabledfi# Run hook logic# ...Use case:Enable/disable hooks without editing hooks.json (requires restart).Pattern 2: Agent State ManagementStore agent-specific state and configuration:.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 greenRead from hooks to coordinate agents:AGENT_NAME$(echo$FRONTMATTER|grep^agent_name:|seds/agent_name: *//)COORDINATOR$(echo$FRONTMATTER|grep^coordinator_session:|seds/coordinator_session: *//)# Send notification to coordinatortmux send-keys-t$COORDINATORAgent$AGENT_NAMEcompleted taskEnterPattern 3: Configuration-Driven Behavior.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.Use in hooks or commands:LEVEL$(echo$FRONTMATTER|grep^validation_level:|seds/validation_level: *//)case$LEVELinstrict)# Apply strict validation;;standard)# Apply standard validation;;lenient)# Apply lenient validation;;esacCreating Settings FilesFrom CommandsCommands can create settings files:# Setup Command Steps: 1. Ask user for configuration preferences 2. Create .claude/my-plugin.local.md with YAML frontmatter 3. Set appropriate values based on user input 4. Inform user that settings are saved 5. Remind user to restart Claude Code for hooks to recognize changesTemplate GenerationProvide template in plugin 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.Best PracticesFile Naming✅DO:Use.claude/plugin-name.local.mdformatMatch plugin name exactlyUse.local.mdsuffix for user-local files❌DON’T:Use different directory (not.claude/)Use inconsistent namingUse.mdwithout.local(might be committed)GitignoreAlways add to.gitignore:.claude/*.local.md .claude/*.local.jsonDocument this in plugin README.DefaultsProvide sensible defaults when settings file doesn’t exist:if[[!-f$STATE_FILE]];then# Use defaultsENABLEDtrueMODEstandardelse# Read from file# ...fiValidationValidate settings values:MAX$(echo$FRONTMATTER|grep^max_value:|seds/max_value: *//)# Validate numeric rangeif![[$MAX~^[0-9]$]]||[[$MAX-lt1]]||[[$MAX-gt100]];thenecho⚠️ Invalid max_value in settings (must be 1-100)2MAX10# Use defaultfiRestart RequirementImportant:Settings changes require Claude Code restart.Document in your 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 loadedHooks cannot be hot-swapped within a session.Security ConsiderationsSanitize User InputWhen writing settings files from user input:# Escape quotes in user inputSAFE_VALUE$(echo$USER_INPUT|seds//\\\\/g)# Write to filecat$STATE_FILEEOF --- user_setting: $SAFE_VALUE --- EOFValidate File PathsIf settings contain file paths:bashFILE_PATH(echo(echo (echoFRONTMATTER | grep ‘^data_file:’ | sed ‘s/data_file: *//’)Check for path traversalif [[ “$FILE_PATH” “…”]]; thenecho “⚠️ Invalid path in settings (path traversal)” 2exit 2fi### Permissions Settings files should be: - Readable by user only (chmod 600) - Not committed to git - Not shared between users ## Real-World Examples ### multi-agent-swarm Plugin **.claude/multi-agent-swarm.local.md:** markdown --- agent_name: auth-implementation task_number: 3.5 pr_number: 1234 coordinator_session: team-leader enabled: true dependencies: [Task 3.4] additional_instructions: Use JWT tokens, not sessions --- # Task: Implement Authentication Build JWT-based authentication for the REST API. Coordinate with auth-agent on shared types.Hook usage (agent-stop-notification.sh):Checks if file exists (line 15-18: quick exit if not)Parses frontmatter to get coordinator_session, agent_name, enabledSends notifications to coordinator if enabledAllows quick activation/deactivation viaenabled: true/falseralph-wiggum Plugin.claude/ralph-loop.local.md:--- iteration: 1 max_iterations: 10 completion_promise: All tests passing and build successful --- Fix all the linting errors in the project. Make sure tests pass after each fix.Hook usage (stop-hook.sh):Checks if file exists (line 15-18: quick exit if not active)Reads iteration count and max_iterationsExtracts completion_promise for loop terminationReads body as the prompt to feed backUpdates iteration count on each loopQuick ReferenceFile Locationproject-root/ └── .claude/ └── plugin-name.local.mdFrontmatter Parsing# Extract frontmatterFRONTMATTER$(sed-n/^---$/,/^---$/{ /^---$/d; p; }$FILE)# Read fieldVALUE$(echo$FRONTMATTER|grep^field:|seds/field: *//|seds/^\\(.*\\)$/\\1/)Body Parsing# Extract body (after second ---)BODY$(awk/^---$/{i; next} i2$FILE)Quick Exit Patternif[[!-f.claude/my-plugin.local.md]];thenexit0# Not configuredfiAdditional ResourcesReference FilesFor detailed implementation patterns:references/parsing-techniques.md- Complete guide to parsing YAML frontmatter and markdown bodiesreferences/real-world-examples.md- Deep dive into multi-agent-swarm and ralph-wiggum implementationsExample FilesWorking examples inexamples/:read-settings-hook.sh- Hook that reads and uses settingscreate-settings-command.md- Command that creates settings fileexample-settings.md- Template settings fileUtility ScriptsDevelopment tools inscripts/:validate-settings.sh- Validate settings file structureparse-frontmatter.sh- Extract frontmatter fieldsImplementation WorkflowTo add settings to a plugin:Design settings schema (which fields, types, defaults)Create template file in plugin documentationAdd gitignore entry for.claude/*.local.mdImplement settings parsing in hooks/commandsUse quick-exit pattern (check file exists, check enabled field)Document settings in plugin README with templateRemind users that changes require Claude Code restartFocus on keeping settings simple and providing good defaults when settings file doesn’t exist.3c:[“,,,L3f”,null,{“content”:“$40”,“frontMatter”:{“name”:“Plugin Settings”,“description”:“This skill should be used when the user asks about \“plugin settings\”, \“store plugin configuration\”, \“user-configurable plugin\”, \”.local.md files\“, \“plugin state files\”, \“read YAML frontmatter\”, \“per-project plugin settings\”, or wants to make plugin behavior configurable. Documents the .claude/plugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.”,“version”:“0.1.0”}}]3d:[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[[”,“div”,null,{“className”:“flex items-center justify-between border-b border-border bg-muted/30 px-4 py-2.5”,“children”:[[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[”,“span”,null,{“className”:“truncate text-xs font-medium text-muted-foreground”,“children”:“同仓库更多 Skills”}]}],[“KaTeX parse error: Expected EOF, got } at position 88: …ldren:同仓库}]]}̲],[”,“div”,null,{“className”:“p-4 sm:p-5”,“children”:[[“,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[,h2,null,{id:related-skills-heading,className:text-2xl font-semibold tracking-normal text-foreground,children:同仓库更多 Skills}],[,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[”,“div”,null,{“className”:“mt-4 grid gap-3 sm:grid-cols-2”,“children”:[“L41,L41,L41,L42”,“L43,L43,L43,L44”,“L45,L45,L45,L46”]}]]}]]}]47:I[206516,[“/_next/static/chunks/051aanbhrv4br.js”,“/_next/static/chunks/0mizr60h7ayzt.js”,“/_next/static/chunks/0v9lm1dmbdoo-.js”,“/_next/static/chunks/0rxr1j1j3j-.r.js”,“/_next/static/chunks/02ftybezfvqjd.js”,“/_next/static/chunks/0.v9ksvnnj8ia.js”,“/_next/static/chunks/0bn6id96nx3k.js,“/_next/static/chunks/13ybnhn37c.tc.js”,“/_next/static/chunks/0_fnrdtruz8uf.js”,“/_next/static/chunks/0r6l15utt1mwb.js”,“/_next/static/chunks/0dm9a5into854.js”,/_next/static/chunks/07k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]