[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79PCTFHAVCHH2V3V008AB7E":3,"skill-same:01M79PCTFHAVCHH2V3V008AB7E":76},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":13,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M79PCTFHAVCHH2V3V008AB7E","plugin-settings",null,"Implements per-project plugin configuration using .claude\u002Fplugin-name.local.md files — YAML frontmatter for structured settings, markdown body for prompts or context. Use when adding user-configurable settings to a Claude Code plugin, creating or reading .claude\u002Fplugin-name.local.md files, storing per-project plugin state, implementing the plugin settings pattern, reading YAML frontmatter from bash hooks, making plugin behavior configurable per project, managing plugin state files, or enabling\u002Fdisabling plugin behavior without editing hooks.json.","AndreHahm\u002Fandres-cc-marketplace","AndreHahm","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F80748019?v=4","01M79N2VZJT9MAJ7K695C9VXQ4","01M79N2W06PFX8BSCQ592M8K8K",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: plugin-settings\ndescription: >-\n  Implements per-project plugin configuration using .claude\u002Fplugin-name.local.md\n  files — YAML frontmatter for structured settings, markdown body for prompts or\n  context. Use when adding user-configurable settings to a Claude Code plugin,\n  creating or reading .claude\u002Fplugin-name.local.md files, storing per-project\n  plugin state, implementing the plugin settings pattern, reading YAML frontmatter\n  from bash hooks, making plugin behavior configurable per project, managing plugin\n  state files, or enabling\u002Fdisabling plugin behavior without editing hooks.json.\nallowed-tools: Read Write Edit Glob\n---\n\n# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store per-project configuration in `.claude\u002Fplugin-name.local.md` — a file with YAML frontmatter for structured settings and a markdown body for prompts or context.\n\n**Key characteristics:**\n- File location: `.claude\u002Fplugin-name.local.md` in project root\n- Structure: YAML frontmatter + markdown body\n- Purpose: Per-project plugin configuration and state\n- Usage: Read from hooks, commands, and agents\n- Lifecycle: User-managed (not in git, should be in `.gitignore`)\n\n## Quick Start\n\n1. **Design settings schema** — decide which fields, types, and defaults are needed\n2. **Add gitignore entry** — `.claude\u002F*.local.md` so the file is never committed\n3. **Create settings file** — `.claude\u002Fplugin-name.local.md` in project root (see File Structure below)\n4. **Implement quick-exit in hooks** — check file exists and `enabled: true` before any logic\n5. **Parse frontmatter** — `FRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$FILE\")`\n6. **Extract fields** — `VALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's\u002Ffield: *\u002F\u002F')`\n7. **Document in README** — provide a template and note that changes require Claude Code restart\n\n## When to Use\n\n- Adding configurable settings that differ per project\n- Enabling\u002Fdisabling hooks without modifying `hooks.json` (which requires restart anyway)\n- Passing agent state between Claude Code sessions (multi-agent coordination)\n- Feeding a prompt back as a loop continuation (ralph-loop pattern)\n- Storing structured task assignments for subagents\n\n## When NOT to Use\n\n- Global settings shared across all projects — use environment variables instead\n- Secrets or credentials — use environment variables, never settings files\n- Configuration identical for all users — hardcode defaults or use plugin.json\n\n---\n\n## File Structure\n\n### Basic Template\n\n```markdown\n---\nenabled: true\nsetting1: value1\nsetting2: value2\nnumeric_setting: 42\nlist_setting: [\"item1\", \"item2\"]\n---\n\n# Additional Context\n\nThis markdown body can contain:\n- Task descriptions\n- Additional instructions\n- Prompts to feed back to Claude\n- Documentation or notes\n```\n\n### Example: Plugin State File\n\n**.claude\u002Fmy-plugin.local.md:**\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_retries: 3\nnotification_level: info\ncoordinator_session: team-leader\n---\n\n# Plugin Configuration\n\nThis plugin is configured for standard validation mode.\nContact @team-lead with questions.\n```\n\n## Reading Settings Files\n\n### From Hooks (Bash Scripts)\n\n**Pattern: Check existence and parse frontmatter**\n\n```bash\nSTATE_FILE=\".claude\u002Fmy-plugin.local.md\"\n[[ ! -f \"$STATE_FILE\" ]] && exit 0\n\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n[[ \"$ENABLED\" != \"true\" ]] && exit 0\n\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | grep '^strict_mode:' | sed 's\u002Fstrict_mode: *\u002F\u002F')\n# Use $STRICT_MODE in hook logic\n```\n\nSee `scripts\u002Fread-settings-hook.sh` for complete working example.\n\n### From Commands\n\nCommands can read settings files to customize behavior:\n\n```markdown\n---\ndescription: Process data with plugin\nallowed-tools: Read\n---\n\n# Process Command\n\nSteps:\n1. Check if settings exist at `.claude\u002Fmy-plugin.local.md`\n2. Read configuration using Read tool\n3. Parse YAML frontmatter to extract settings\n4. Apply settings to processing logic\n5. Execute with configured behavior\n```\n\n### From Agents\n\nAgents can reference settings in their instructions:\n\n```markdown\n---\nname: configured-agent\ndescription: Agent that adapts to project settings\n---\n\nCheck for plugin settings at `.claude\u002Fmy-plugin.local.md`.\nIf present, parse YAML frontmatter and adapt behavior according to:\n- enabled: Whether plugin is active\n- mode: Processing mode (strict, standard, lenient)\n- Additional configuration fields\n```\n\n## Parsing Techniques\n\nFor complete parsing patterns — lists, yq, multi-field extraction, atomic updates, validation, edge cases, and performance optimization — see `references\u002Fparsing-techniques.md`.\n\n---\n\n## Common Patterns\n\n### Pattern 1: Temporarily Active Hooks\n\nUse settings file to control hook activation:\n\n```bash\nSTATE_FILE=\".claude\u002Fsecurity-scan.local.md\"\n# Parse frontmatter as shown in Quick Start steps 5-6\n[[ ! -f \"$STATE_FILE\" ]] && exit 0\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n[[ \"$ENABLED\" != \"true\" ]] && exit 0\n# Hook logic here\n```\n\n**Use case:** Enable\u002Fdisable hooks without editing hooks.json (requires restart).\n\n### Pattern 2: Agent State Management\n\nStore agent-specific state and configuration:\n\n**.claude\u002Fmulti-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-agent\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\n---\n\n# Task Assignment\n\nImplement JWT authentication for the API.\n\n**Success Criteria:**\n- Authentication endpoints created\n- Tests passing\n- PR created and CI green\n```\n\nRead from hooks to coordinate agents:\n\n```bash\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's\u002Fagent_name: *\u002F\u002F')\nCOORDINATOR=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's\u002Fcoordinator_session: *\u002F\u002F')\n\n# Send notification to coordinator\ntmux send-keys -t \"$COORDINATOR\" \"Agent $AGENT_NAME completed task\" Enter\n```\n\n### Pattern 3: Configuration-Driven Behavior\n\n**.claude\u002Fmy-plugin.local.md:**\n```markdown\n---\nvalidation_level: strict\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\n---\n\n# Validation Configuration\n\nStrict mode enabled for this project.\nAll writes validated against security policies.\n```\n\nUse in hooks or commands:\n\n```bash\nLEVEL=$(echo \"$FRONTMATTER\" | grep '^validation_level:' | sed 's\u002Fvalidation_level: *\u002F\u002F')\n\ncase \"$LEVEL\" in\n  strict)\n    # Apply strict validation\n    ;;\n  standard)\n    # Apply standard validation\n    ;;\n  lenient)\n    # Apply lenient validation\n    ;;\nesac\n```\n\n---\n\n## Creating Settings Files\n\n### From Commands\n\nCommands can create settings files:\n\n```markdown\n# Setup Command\n\nSteps:\n1. Use `AskUserQuestion` to gather configuration preferences\n2. Create `.claude\u002Fmy-plugin.local.md` with YAML frontmatter\n3. Set appropriate values based on user input\n4. Inform user that settings are saved\n5. Remind user to restart Claude Code for hooks to recognize changes\n```\n\n### Template Generation\n\nProvide template in plugin README:\n\n```markdown\n## Configuration\n\nCreate `.claude\u002Fmy-plugin.local.md` in your project:\n\n\\`\\`\\`markdown\n---\nenabled: true\nmode: standard\nmax_retries: 3\n---\n\n# Plugin Configuration\n\nYour settings are active.\n\\`\\`\\`\n\nAfter creating or editing, restart Claude Code for changes to take effect.\n```\n\n---\n\n## Best Practices\n\n### File Naming\n\n✅ **DO:**\n- Use `.claude\u002Fplugin-name.local.md` format\n- Match plugin name exactly\n- Use `.local.md` suffix for user-local files\n\n❌ **DON'T:**\n- Use different directory (not `.claude\u002F`)\n- Use inconsistent naming\n- Use `.md` without `.local` (might be committed)\n\n### Gitignore\n\nAlways add to `.gitignore`:\n\n```gitignore\n.claude\u002F*.local.md\n.claude\u002F*.local.json\n```\n\nDocument this in plugin README.\n\n### Defaults\n\nProvide sensible defaults when settings file doesn't exist:\n\n```bash\nif [[ ! -f \"$STATE_FILE\" ]]; then\n  # Use defaults\n  ENABLED=true\n  MODE=standard\nelse\n  # Read from file\n  # ...\nfi\n```\n\n### Validation\n\nValidate settings values:\n\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's\u002Fmax_value: *\u002F\u002F')\n\n# Validate numeric range\nif ! [[ \"$MAX\" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then\n  echo \"⚠️  Invalid max_value in settings (must be 1-100)\" >&2\n  MAX=10  # Use default\nfi\n```\n\n### Restart Requirement\n\n**Important:** Settings changes require Claude Code restart.\n\nDocument in your README:\n\n```markdown\n## Changing Settings\n\nAfter editing `.claude\u002Fmy-plugin.local.md`:\n1. Save the file\n2. Exit Claude Code\n3. Restart: `claude` or `cc`\n4. New settings will be loaded\n```\n\nHooks cannot be hot-swapped within a session.\n\n---\n\n## Security Considerations\n\n### Sanitize User Input\n\nWhen writing settings files from user input:\n\n```bash\n# Escape quotes in user input\nSAFE_VALUE=$(echo \"$USER_INPUT\" | sed 's\u002F\"\u002F\\\\\"\u002Fg')\n\n# Write to file\ncat > \"$STATE_FILE\" \u003C\u003CEOF\n---\nuser_setting: \"$SAFE_VALUE\"\n---\nEOF\n```\n\n### Validate File Paths\n\nIf settings contain file paths:\n\n```bash\nFILE_PATH=$(echo \"$FRONTMATTER\" | grep '^data_file:' | sed 's\u002Fdata_file: *\u002F\u002F')\n\n# Check for path traversal\nif [[ \"$FILE_PATH\" == *\"..\"* ]]; then\n  echo \"⚠️  Invalid path in settings (path traversal)\" >&2\n  exit 2\nfi\n```\n\n### Permissions\n\nSettings files should be:\n- Readable by user only (`chmod 600`)\n- Not committed to git\n- Not shared between users\n\n## Real-World Examples\n\nFor deep dives into production plugin implementations — multi-agent-swarm (agent coordination with tmux notifications) and ralph-loop (loop state management with completion detection) — see `references\u002Freal-world-examples.md`.\n\n---\n\n## Testing & Validation\n\nAfter implementing the plugin settings pattern:\n\n1. **File existence check** — hook exits cleanly (`exit 0`) when settings file is absent\n2. **Enabled flag** — hook is skipped when `enabled: false` in frontmatter\n3. **Field defaults** — all fields have fallback values when absent or empty\n4. **Gitignore** — `.claude\u002F*.local.md` is listed in `.gitignore`\n5. **Restart documented** — README includes restart instruction after settings change\n\n**Quality gates:**\n- [ ] Quick-exit pattern used in all hooks before any file I\u002FO\n- [ ] All frontmatter fields have defaults for the missing-file case\n- [ ] No credentials or secrets stored in settings files (use env vars)\n- [ ] No path traversal possible from settings-derived file paths\n- [ ] Settings file template provided in plugin README\n- [ ] `.claude\u002F*.local.md` in `.gitignore`\n\n---\n\n## Reference Guide\n\n| Resource | Purpose |\n|---|---|\n| `references\u002Fparsing-techniques.md` | Complete bash parsing guide — lists, yq, multi-field extraction, atomic updates, validation, edge cases |\n| `references\u002Freal-world-examples.md` | Deep dive: multi-agent-swarm (agent coordination) and ralph-loop (loop control) |\n| `scripts\u002Fread-settings-hook.sh` | Working hook that reads and applies settings |\n| `references\u002Fcreate-settings-command.md` | Command that creates a settings file |\n| `references\u002Fexample-settings.md` | Template settings file |\n| `scripts\u002Fvalidate-settings.sh` | Validate settings file structure |\n| `scripts\u002Fparse-frontmatter.sh` | Extract frontmatter fields |\n","# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store per-project configuration in `.claude\u002Fplugin-name.local.md` — a file with YAML frontmatter for structured settings and a markdown body for prompts or context.\n\n**Key characteristics:**\n- File location: `.claude\u002Fplugin-name.local.md` in project root\n- Structure: YAML frontmatter + markdown body\n- Purpose: Per-project plugin configuration and state\n- Usage: Read from hooks, commands, and agents\n- Lifecycle: User-managed (not in git, should be in `.gitignore`)\n\n## Quick Start\n\n1. **Design settings schema** — decide which fields, types, and defaults are needed\n2. **Add gitignore entry** — `.claude\u002F*.local.md` so the file is never committed\n3. **Create settings file** — `.claude\u002Fplugin-name.local.md` in project root (see File Structure below)\n4. **Implement quick-exit in hooks** — check file exists and `enabled: true` before any logic\n5. **Parse frontmatter** — `FRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$FILE\")`\n6. **Extract fields** — `VALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's\u002Ffield: *\u002F\u002F')`\n7. **Document in README** — provide a template and note that changes require Claude Code restart\n\n## When to Use\n\n- Adding configurable settings that differ per project\n- Enabling\u002Fdisabling hooks without modifying `hooks.json` (which requires restart anyway)\n- Passing agent state between Claude Code sessions (multi-agent coordination)\n- Feeding a prompt back as a loop continuation (ralph-loop pattern)\n- Storing structured task assignments for subagents\n\n## When NOT to Use\n\n- Global settings shared across all projects — use environment variables instead\n- Secrets or credentials — use environment variables, never settings files\n- Configuration identical for all users — hardcode defaults or use plugin.json\n\n---\n\n## File Structure\n\n### Basic Template\n\n```markdown\n---\nenabled: true\nsetting1: value1\nsetting2: value2\nnumeric_setting: 42\nlist_setting: [\"item1\", \"item2\"]\n---\n\n# Additional Context\n\nThis markdown body can contain:\n- Task descriptions\n- Additional instructions\n- Prompts to feed back to Claude\n- Documentation or notes\n```\n\n### Example: Plugin State File\n\n**.claude\u002Fmy-plugin.local.md:**\n```markdown\n---\nenabled: true\nstrict_mode: false\nmax_retries: 3\nnotification_level: info\ncoordinator_session: team-leader\n---\n\n# Plugin Configuration\n\nThis plugin is configured for standard validation mode.\nContact @team-lead with questions.\n```\n\n## Reading Settings Files\n\n### From Hooks (Bash Scripts)\n\n**Pattern: Check existence and parse frontmatter**\n\n```bash\nSTATE_FILE=\".claude\u002Fmy-plugin.local.md\"\n[[ ! -f \"$STATE_FILE\" ]] && exit 0\n\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n[[ \"$ENABLED\" != \"true\" ]] && exit 0\n\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | grep '^strict_mode:' | sed 's\u002Fstrict_mode: *\u002F\u002F')\n# Use $STRICT_MODE in hook logic\n```\n\nSee `scripts\u002Fread-settings-hook.sh` for complete working example.\n\n### From Commands\n\nCommands can read settings files to customize behavior:\n\n```markdown\n---\ndescription: Process data with plugin\nallowed-tools: Read\n---\n\n# Process Command\n\nSteps:\n1. Check if settings exist at `.claude\u002Fmy-plugin.local.md`\n2. Read configuration using Read tool\n3. Parse YAML frontmatter to extract settings\n4. Apply settings to processing logic\n5. Execute with configured behavior\n```\n\n### From Agents\n\nAgents can reference settings in their instructions:\n\n```markdown\n---\nname: configured-agent\ndescription: Agent that adapts to project settings\n---\n\nCheck for plugin settings at `.claude\u002Fmy-plugin.local.md`.\nIf present, parse YAML frontmatter and adapt behavior according to:\n- enabled: Whether plugin is active\n- mode: Processing mode (strict, standard, lenient)\n- Additional configuration fields\n```\n\n## Parsing Techniques\n\nFor complete parsing patterns — lists, yq, multi-field extraction, atomic updates, validation, edge cases, and performance optimization — see `references\u002Fparsing-techniques.md`.\n\n---\n\n## Common Patterns\n\n### Pattern 1: Temporarily Active Hooks\n\nUse settings file to control hook activation:\n\n```bash\nSTATE_FILE=\".claude\u002Fsecurity-scan.local.md\"\n# Parse frontmatter as shown in Quick Start steps 5-6\n[[ ! -f \"$STATE_FILE\" ]] && exit 0\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n[[ \"$ENABLED\" != \"true\" ]] && exit 0\n# Hook logic here\n```\n\n**Use case:** Enable\u002Fdisable hooks without editing hooks.json (requires restart).\n\n### Pattern 2: Agent State Management\n\nStore agent-specific state and configuration:\n\n**.claude\u002Fmulti-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-agent\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\n---\n\n# Task Assignment\n\nImplement JWT authentication for the API.\n\n**Success Criteria:**\n- Authentication endpoints created\n- Tests passing\n- PR created and CI green\n```\n\nRead from hooks to coordinate agents:\n\n```bash\nAGENT_NAME=$(echo \"$FRONTMATTER\" | grep '^agent_name:' | sed 's\u002Fagent_name: *\u002F\u002F')\nCOORDINATOR=$(echo \"$FRONTMATTER\" | grep '^coordinator_session:' | sed 's\u002Fcoordinator_session: *\u002F\u002F')\n\n# Send notification to coordinator\ntmux send-keys -t \"$COORDINATOR\" \"Agent $AGENT_NAME completed task\" Enter\n```\n\n### Pattern 3: Configuration-Driven Behavior\n\n**.claude\u002Fmy-plugin.local.md:**\n```markdown\n---\nvalidation_level: strict\nmax_file_size: 1000000\nallowed_extensions: [\".js\", \".ts\", \".tsx\"]\nenable_logging: true\n---\n\n# Validation Configuration\n\nStrict mode enabled for this project.\nAll writes validated against security policies.\n```\n\nUse in hooks or commands:\n\n```bash\nLEVEL=$(echo \"$FRONTMATTER\" | grep '^validation_level:' | sed 's\u002Fvalidation_level: *\u002F\u002F')\n\ncase \"$LEVEL\" in\n  strict)\n    # Apply strict validation\n    ;;\n  standard)\n    # Apply standard validation\n    ;;\n  lenient)\n    # Apply lenient validation\n    ;;\nesac\n```\n\n---\n\n## Creating Settings Files\n\n### From Commands\n\nCommands can create settings files:\n\n```markdown\n# Setup Command\n\nSteps:\n1. Use `AskUserQuestion` to gather configuration preferences\n2. Create `.claude\u002Fmy-plugin.local.md` with YAML frontmatter\n3. Set appropriate values based on user input\n4. Inform user that settings are saved\n5. Remind user to restart Claude Code for hooks to recognize changes\n```\n\n### Template Generation\n\nProvide template in plugin README:\n\n```markdown\n## Configuration\n\nCreate `.claude\u002Fmy-plugin.local.md` in your project:\n\n\\`\\`\\`markdown\n---\nenabled: true\nmode: standard\nmax_retries: 3\n---\n\n# Plugin Configuration\n\nYour settings are active.\n\\`\\`\\`\n\nAfter creating or editing, restart Claude Code for changes to take effect.\n```\n\n---\n\n## Best Practices\n\n### File Naming\n\n✅ **DO:**\n- Use `.claude\u002Fplugin-name.local.md` format\n- Match plugin name exactly\n- Use `.local.md` suffix for user-local files\n\n❌ **DON'T:**\n- Use different directory (not `.claude\u002F`)\n- Use inconsistent naming\n- Use `.md` without `.local` (might be committed)\n\n### Gitignore\n\nAlways add to `.gitignore`:\n\n```gitignore\n.claude\u002F*.local.md\n.claude\u002F*.local.json\n```\n\nDocument this in plugin README.\n\n### Defaults\n\nProvide sensible defaults when settings file doesn't exist:\n\n```bash\nif [[ ! -f \"$STATE_FILE\" ]]; then\n  # Use defaults\n  ENABLED=true\n  MODE=standard\nelse\n  # Read from file\n  # ...\nfi\n```\n\n### Validation\n\nValidate settings values:\n\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's\u002Fmax_value: *\u002F\u002F')\n\n# Validate numeric range\nif ! [[ \"$MAX\" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then\n  echo \"⚠️  Invalid max_value in settings (must be 1-100)\" >&2\n  MAX=10  # Use default\nfi\n```\n\n### Restart Requirement\n\n**Important:** Settings changes require Claude Code restart.\n\nDocument in your README:\n\n```markdown\n## Changing Settings\n\nAfter editing `.claude\u002Fmy-plugin.local.md`:\n1. Save the file\n2. Exit Claude Code\n3. Restart: `claude` or `cc`\n4. New settings will be loaded\n```\n\nHooks cannot be hot-swapped within a session.\n\n---\n\n## Security Considerations\n\n### Sanitize User Input\n\nWhen writing settings files from user input:\n\n```bash\n# Escape quotes in user input\nSAFE_VALUE=$(echo \"$USER_INPUT\" | sed 's\u002F\"\u002F\\\\\"\u002Fg')\n\n# Write to file\ncat > \"$STATE_FILE\" \u003C\u003CEOF\n---\nuser_setting: \"$SAFE_VALUE\"\n---\nEOF\n```\n\n### Validate File Paths\n\nIf settings contain file paths:\n\n```bash\nFILE_PATH=$(echo \"$FRONTMATTER\" | grep '^data_file:' | sed 's\u002Fdata_file: *\u002F\u002F')\n\n# Check for path traversal\nif [[ \"$FILE_PATH\" == *\"..\"* ]]; then\n  echo \"⚠️  Invalid path in settings (path traversal)\" >&2\n  exit 2\nfi\n```\n\n### Permissions\n\nSettings files should be:\n- Readable by user only (`chmod 600`)\n- Not committed to git\n- Not shared between users\n\n## Real-World Examples\n\nFor deep dives into production plugin implementations — multi-agent-swarm (agent coordination with tmux notifications) and ralph-loop (loop state management with completion detection) — see `references\u002Freal-world-examples.md`.\n\n---\n\n## Testing & Validation\n\nAfter implementing the plugin settings pattern:\n\n1. **File existence check** — hook exits cleanly (`exit 0`) when settings file is absent\n2. **Enabled flag** — hook is skipped when `enabled: false` in frontmatter\n3. **Field defaults** — all fields have fallback values when absent or empty\n4. **Gitignore** — `.claude\u002F*.local.md` is listed in `.gitignore`\n5. **Restart documented** — README includes restart instruction after settings change\n\n**Quality gates:**\n- [ ] Quick-exit pattern used in all hooks before any file I\u002FO\n- [ ] All frontmatter fields have defaults for the missing-file case\n- [ ] No credentials or secrets stored in settings files (use env vars)\n- [ ] No path traversal possible from settings-derived file paths\n- [ ] Settings file template provided in plugin README\n- [ ] `.claude\u002F*.local.md` in `.gitignore`\n\n---\n\n## Reference Guide\n\n| Resource | Purpose |\n|---|---|\n| `references\u002Fparsing-techniques.md` | Complete bash parsing guide — lists, yq, multi-field extraction, atomic updates, validation, edge cases |\n| `references\u002Freal-world-examples.md` | Deep dive: multi-agent-swarm (agent coordination) and ralph-loop (loop control) |\n| `scripts\u002Fread-settings-hook.sh` | Working hook that reads and applies settings |\n| `references\u002Fcreate-settings-command.md` | Command that creates a settings file |\n| `references\u002Fexample-settings.md` | Template settings file |\n| `scripts\u002Fvalidate-settings.sh` | Validate settings file structure |\n| `scripts\u002Fparse-frontmatter.sh` | Extract frontmatter fields |\n",{"name":5,"description":7,"allowed-tools":23},"Read Write Edit Glob","main","1bf12900cac6f28e346abd2912bdb78d306de723",".claude\u002Fskills\u002Fplugin-settings","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace","https:\u002F\u002Fgithub.com\u002FAndreHahm","2026-11-15 04:26:16",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add AndreHahm\u002Fandres-cc-marketplace --skill plugin-settings",{"tool":36,"command":37},"bunx","bunx skills add AndreHahm\u002Fandres-cc-marketplace --skill plugin-settings",{"tool":39,"command":40},"pnpm","pnpm dlx skills add AndreHahm\u002Fandres-cc-marketplace --skill plugin-settings","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002FSKILL.md",true,[44,50,54,58,62,68,72],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"references\u002Fcreate-settings-command.md","REFERENCE","参考文档",2419,"https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002Freferences\u002Fcreate-settings-command.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fexample-settings.md",2500,"https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002Freferences\u002Fexample-settings.md",{"path":55,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fparsing-techniques.md",11713,"https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002Freferences\u002Fparsing-techniques.md",{"path":59,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Freal-world-examples.md",9660,"https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002Freferences\u002Freal-world-examples.md",{"path":63,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":66,"sourceHtmlUrl":67},"scripts\u002Fparse-frontmatter.sh","SCRIPT","脚本",1507,"https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002Fscripts\u002Fparse-frontmatter.sh",{"path":69,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":70,"sourceHtmlUrl":71},"scripts\u002Fread-settings-hook.sh",2506,"https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002Fscripts\u002Fread-settings-hook.sh",{"path":73,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":74,"sourceHtmlUrl":75},"scripts\u002Fvalidate-settings.sh",2720,"https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplugin-settings\u002Fscripts\u002Fvalidate-settings.sh",[77,84,91,98,105,112],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":18},"01M79R0K918Z0XDM74R0EY5H3P","demo","Fixture skill used by scripts.marketplace_ci sync tests.","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002Ftests\u002Fmarketplace_ci\u002Ffixtures\u002Fplugins\u002Fsample-kit\u002Fskills\u002Fdemo\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":18},"01M79R08VMDJA2FPJKH3ZM309K","export-demo","Fixture skill used by scripts.marketplace_ci export tests.","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002Ftests\u002Fmarketplace_ci\u002Ffixtures\u002Fclaude\u002Fskills\u002Fexport-demo\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":18},"01M79R042FS581DS2JNW5AZ1MK","work-to-development","Validate an accepted Linear Issue's readiness for implementation (criteria, dependencies, duplicate\u002Fexisting artifacts) and request governed branch\u002Fworktree creation through git-kit:starting-work — recording work-started Git\u002FGitHub evidence and a deliberate Linear Started transition only after Git identity is read back and verified. Use when asked to start work on a Linear issue, begin development for an accepted issue, or prepare an accepted issue for implementation. Never creates a branch directly — always delegates to git-kit.","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fworkmanagement-kit\u002Fskills\u002Fwork-to-development\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":18},"01M79QZZD4EHB82P72P4N92BKT","work-linking","Create and maintain stable cross-system links and authority labels between Notion and Linear records, and detect\u002Frepair drift between them. Use when asked to link a Notion record to a Linear record, check for drift between Notion and Linear, or repair a broken\u002Fstale link. Repairs only the bounded non-authoritative copy or link — never chooses by newest timestamp, and never creates a reverse-write loop against either system's own authority.","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fworkmanagement-kit\u002Fskills\u002Fwork-linking\u002FSKILL.md",[],[],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":18},"01M79QZVFA3GTVNZMJ51NESVSP","status-and-learning","Produce a dated, explicitly non-live Linear-to-Notion progress summary, or capture an outcome\u002Flearning after work completes. Use when asked to summarize progress to Notion, report portfolio status, or capture what was learned from a completed piece of work — not to disposition open follow-up items (see open-item-management for that). Never runs automatically or continuously — every summary is a deliberate, approved snapshot, not a live sync.","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fworkmanagement-kit\u002Fskills\u002Fstatus-and-learning\u002FSKILL.md",[],[],{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":18},"01M79QZNSKSABK7X2PT93X8QT5","repository-gates","Discover, delegate, record, and invalidate this repository's actual Git\u002FGitHub lifecycle gates (pre-commit, pre-push, PR required checks, Codex delta review, review requirements, merge rights) and the repository-policy provider profile that maps governed operations to git-kit. Use when asked what gates apply to this repository, to discover repository policy before starting Wave 2 work, or to check whether prior gate evidence is still valid after new commits. Discovery and delegation only — never executes a gate's own internal logic, and never invents a gate the repository doesn't actually define (in particular, never assumes a \"Review Changes\" gate exists).","https:\u002F\u002Fgithub.com\u002FAndreHahm\u002Fandres-cc-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fworkmanagement-kit\u002Fskills\u002Frepository-gates\u002FSKILL.md",[],[]]