[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M718B96YP8C46R8KW4KYYMPZ":3,"skill-same:01M718B96YP8C46R8KW4KYYMPZ":105},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":50,"commitSha":51,"skillDirectory":52,"forksCount":53,"repositoryHtmlUrl":54,"repositoryHomepageUrl":55,"ownerHtmlUrl":56,"ownerBlogUrl":57,"ownerDescription":6,"updatedAt":58,"install":59,"resources":72},"01M718B96YP8C46R8KW4KYYMPZ","plugin-settings",null,"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\u002Fplugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.","anthropics\u002Fclaude-plugins-official","anthropics","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F76263028?v=4","01M697XGDPXJAVQ8391V2BCYTE","Anthropic","01M7188MR49TZ9N2ZKPXJ7M7HY",46789,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"plugin","Plugin Settings","settings","when","documents","make plugin","frontmatter","for","with","make","store","name","project","local","pattern","files","read","markdown content","markdown","state","2026-11-10 10:12:30",false,"---\nname: plugin-settings\ndescription: 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\u002Fplugin-name.local.md pattern for storing plugin-specific configuration with YAML frontmatter and markdown content.\nversion: 0.1.0\n---\n\n# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store user-configurable settings and state in `.claude\u002Fplugin-name.local.md` files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional 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## 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\n#!\u002Fbin\u002Fbash\nset -euo pipefail\n\n# Define state file path\nSTATE_FILE=\".claude\u002Fmy-plugin.local.md\"\n\n# Quick exit if file doesn't exist\nif [[ ! -f \"$STATE_FILE\" ]]; then\n  exit 0  # Plugin not configured, skip\nfi\n\n# Parse YAML frontmatter (between --- markers)\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\n\n# Extract individual fields\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | grep '^strict_mode:' | sed 's\u002Fstrict_mode: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n  exit 0  # Disabled\nfi\n\n# Use configuration in hook logic\nif [[ \"$STRICT_MODE\" == \"true\" ]]; then\n  # Apply strict validation\n  # ...\nfi\n```\n\nSee `examples\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\", \"Bash\"]\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\n### Extract Frontmatter\n\n```bash\n# Extract everything between --- markers\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$FILE\")\n```\n\n### Read Individual Fields\n\n**String fields:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's\u002Ffield_name: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n# Compare: if [[ \"$ENABLED\" == \"true\" ]]; then\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's\u002Fmax_value: *\u002F\u002F')\n# Use: if [[ $MAX -gt 100 ]]; then\n```\n\n### Read Markdown Body\n\nExtract content after second `---`:\n\n```bash\n# Get everything after closing ---\nBODY=$(awk '\u002F^---$\u002F{i++; next} i>=2' \"$FILE\")\n```\n\n## Common Patterns\n\n### Pattern 1: Temporarily Active Hooks\n\nUse settings file to control hook activation:\n\n```bash\n#!\u002Fbin\u002Fbash\nSTATE_FILE=\".claude\u002Fsecurity-scan.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$STATE_FILE\" ]]; then\n  exit 0\nfi\n\n# Read enabled flag\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n\nif [[ \"$ENABLED\" != \"true\" ]]; then\n  exit 0  # Disabled\nfi\n\n# Run hook logic\n# ...\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## Creating Settings Files\n\n### From Commands\n\nCommands can create settings files:\n\n```markdown\n# Setup Command\n\nSteps:\n1. Ask user for 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## 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## 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\n### multi-agent-swarm Plugin\n\n**.claude\u002Fmulti-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: Use JWT tokens, not sessions\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\nCoordinate with auth-agent on shared types.\n```\n\n**Hook usage (agent-stop-notification.sh):**\n- Checks if file exists (line 15-18: quick exit if not)\n- Parses frontmatter to get coordinator_session, agent_name, enabled\n- Sends notifications to coordinator if enabled\n- Allows quick activation\u002Fdeactivation via `enabled: true\u002Ffalse`\n\n### ralph-loop Plugin\n\n**.claude\u002Fralph-loop.local.md:**\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\n```\n\n**Hook usage (stop-hook.sh):**\n- Checks if file exists (line 15-18: quick exit if not active)\n- Reads iteration count and max_iterations\n- Extracts completion_promise for loop termination\n- Reads body as the prompt to feed back\n- Updates iteration count on each loop\n\n## Quick Reference\n\n### File Location\n\n```\nproject-root\u002F\n└── .claude\u002F\n    └── plugin-name.local.md\n```\n\n### Frontmatter Parsing\n\n```bash\n# Extract frontmatter\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$FILE\")\n\n# Read field\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's\u002Ffield: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\n```\n\n### Body Parsing\n\n```bash\n# Extract body (after second ---)\nBODY=$(awk '\u002F^---$\u002F{i++; next} i>=2' \"$FILE\")\n```\n\n### Quick Exit Pattern\n\n```bash\nif [[ ! -f \".claude\u002Fmy-plugin.local.md\" ]]; then\n  exit 0  # Not configured\nfi\n```\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed implementation patterns:\n\n- **`references\u002Fparsing-techniques.md`** - Complete guide to parsing YAML frontmatter and markdown bodies\n- **`references\u002Freal-world-examples.md`** - Deep dive into multi-agent-swarm and ralph-loop implementations\n\n### Example Files\n\nWorking examples in `examples\u002F`:\n\n- **`read-settings-hook.sh`** - Hook that reads and uses settings\n- **`create-settings-command.md`** - Command that creates settings file\n- **`example-settings.md`** - Template settings file\n\n### Utility Scripts\n\nDevelopment tools in `scripts\u002F`:\n\n- **`validate-settings.sh`** - Validate settings file structure\n- **`parse-frontmatter.sh`** - Extract frontmatter fields\n\n## Implementation Workflow\n\nTo add settings to a plugin:\n\n1. Design settings schema (which fields, types, defaults)\n2. Create template file in plugin documentation\n3. Add gitignore entry for `.claude\u002F*.local.md`\n4. Implement settings parsing in hooks\u002Fcommands\n5. Use quick-exit pattern (check file exists, check enabled field)\n6. Document settings in plugin README with template\n7. Remind users that changes require Claude Code restart\n\nFocus on keeping settings simple and providing good defaults when settings file doesn't exist.\n","# Plugin Settings Pattern for Claude Code Plugins\n\n## Overview\n\nPlugins can store user-configurable settings and state in `.claude\u002Fplugin-name.local.md` files within the project directory. This pattern uses YAML frontmatter for structured configuration and markdown content for prompts or additional 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## 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\n#!\u002Fbin\u002Fbash\nset -euo pipefail\n\n# Define state file path\nSTATE_FILE=\".claude\u002Fmy-plugin.local.md\"\n\n# Quick exit if file doesn't exist\nif [[ ! -f \"$STATE_FILE\" ]]; then\n  exit 0  # Plugin not configured, skip\nfi\n\n# Parse YAML frontmatter (between --- markers)\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\n\n# Extract individual fields\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\nSTRICT_MODE=$(echo \"$FRONTMATTER\" | grep '^strict_mode:' | sed 's\u002Fstrict_mode: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\n\n# Check if enabled\nif [[ \"$ENABLED\" != \"true\" ]]; then\n  exit 0  # Disabled\nfi\n\n# Use configuration in hook logic\nif [[ \"$STRICT_MODE\" == \"true\" ]]; then\n  # Apply strict validation\n  # ...\nfi\n```\n\nSee `examples\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\", \"Bash\"]\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\n### Extract Frontmatter\n\n```bash\n# Extract everything between --- markers\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$FILE\")\n```\n\n### Read Individual Fields\n\n**String fields:**\n```bash\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field_name:' | sed 's\u002Ffield_name: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\n```\n\n**Boolean fields:**\n```bash\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n# Compare: if [[ \"$ENABLED\" == \"true\" ]]; then\n```\n\n**Numeric fields:**\n```bash\nMAX=$(echo \"$FRONTMATTER\" | grep '^max_value:' | sed 's\u002Fmax_value: *\u002F\u002F')\n# Use: if [[ $MAX -gt 100 ]]; then\n```\n\n### Read Markdown Body\n\nExtract content after second `---`:\n\n```bash\n# Get everything after closing ---\nBODY=$(awk '\u002F^---$\u002F{i++; next} i>=2' \"$FILE\")\n```\n\n## Common Patterns\n\n### Pattern 1: Temporarily Active Hooks\n\nUse settings file to control hook activation:\n\n```bash\n#!\u002Fbin\u002Fbash\nSTATE_FILE=\".claude\u002Fsecurity-scan.local.md\"\n\n# Quick exit if not configured\nif [[ ! -f \"$STATE_FILE\" ]]; then\n  exit 0\nfi\n\n# Read enabled flag\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$STATE_FILE\")\nENABLED=$(echo \"$FRONTMATTER\" | grep '^enabled:' | sed 's\u002Fenabled: *\u002F\u002F')\n\nif [[ \"$ENABLED\" != \"true\" ]]; then\n  exit 0  # Disabled\nfi\n\n# Run hook logic\n# ...\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## Creating Settings Files\n\n### From Commands\n\nCommands can create settings files:\n\n```markdown\n# Setup Command\n\nSteps:\n1. Ask user for 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## 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## 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\n### multi-agent-swarm Plugin\n\n**.claude\u002Fmulti-agent-swarm.local.md:**\n```markdown\n---\nagent_name: auth-implementation\ntask_number: 3.5\npr_number: 1234\ncoordinator_session: team-leader\nenabled: true\ndependencies: [\"Task 3.4\"]\nadditional_instructions: Use JWT tokens, not sessions\n---\n\n# Task: Implement Authentication\n\nBuild JWT-based authentication for the REST API.\nCoordinate with auth-agent on shared types.\n```\n\n**Hook usage (agent-stop-notification.sh):**\n- Checks if file exists (line 15-18: quick exit if not)\n- Parses frontmatter to get coordinator_session, agent_name, enabled\n- Sends notifications to coordinator if enabled\n- Allows quick activation\u002Fdeactivation via `enabled: true\u002Ffalse`\n\n### ralph-loop Plugin\n\n**.claude\u002Fralph-loop.local.md:**\n```markdown\n---\niteration: 1\nmax_iterations: 10\ncompletion_promise: \"All tests passing and build successful\"\n---\n\nFix all the linting errors in the project.\nMake sure tests pass after each fix.\n```\n\n**Hook usage (stop-hook.sh):**\n- Checks if file exists (line 15-18: quick exit if not active)\n- Reads iteration count and max_iterations\n- Extracts completion_promise for loop termination\n- Reads body as the prompt to feed back\n- Updates iteration count on each loop\n\n## Quick Reference\n\n### File Location\n\n```\nproject-root\u002F\n└── .claude\u002F\n    └── plugin-name.local.md\n```\n\n### Frontmatter Parsing\n\n```bash\n# Extract frontmatter\nFRONTMATTER=$(sed -n '\u002F^---$\u002F,\u002F^---$\u002F{ \u002F^---$\u002Fd; p; }' \"$FILE\")\n\n# Read field\nVALUE=$(echo \"$FRONTMATTER\" | grep '^field:' | sed 's\u002Ffield: *\u002F\u002F' | sed 's\u002F^\"\\(.*\\)\"$\u002F\\1\u002F')\n```\n\n### Body Parsing\n\n```bash\n# Extract body (after second ---)\nBODY=$(awk '\u002F^---$\u002F{i++; next} i>=2' \"$FILE\")\n```\n\n### Quick Exit Pattern\n\n```bash\nif [[ ! -f \".claude\u002Fmy-plugin.local.md\" ]]; then\n  exit 0  # Not configured\nfi\n```\n\n## Additional Resources\n\n### Reference Files\n\nFor detailed implementation patterns:\n\n- **`references\u002Fparsing-techniques.md`** - Complete guide to parsing YAML frontmatter and markdown bodies\n- **`references\u002Freal-world-examples.md`** - Deep dive into multi-agent-swarm and ralph-loop implementations\n\n### Example Files\n\nWorking examples in `examples\u002F`:\n\n- **`read-settings-hook.sh`** - Hook that reads and uses settings\n- **`create-settings-command.md`** - Command that creates settings file\n- **`example-settings.md`** - Template settings file\n\n### Utility Scripts\n\nDevelopment tools in `scripts\u002F`:\n\n- **`validate-settings.sh`** - Validate settings file structure\n- **`parse-frontmatter.sh`** - Extract frontmatter fields\n\n## Implementation Workflow\n\nTo add settings to a plugin:\n\n1. Design settings schema (which fields, types, defaults)\n2. Create template file in plugin documentation\n3. Add gitignore entry for `.claude\u002F*.local.md`\n4. Implement settings parsing in hooks\u002Fcommands\n5. Use quick-exit pattern (check file exists, check enabled field)\n6. Document settings in plugin README with template\n7. Remind users that changes require Claude Code restart\n\nFocus on keeping settings simple and providing good defaults when settings file doesn't exist.\n",{"name":5,"version":49,"description":7},"0.1.0","main","dceb15d50832e6adf380bedc26dde03d251324b9","plugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings",4865,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official","https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fplugins","https:\u002F\u002Fgithub.com\u002Fanthropics","https:\u002F\u002Fanthropic.com","2026-11-11 08:12:44",{"source":8,"skillName":5,"commands":60,"prompt":70,"zipAvailable":71},[61,64,67],{"tool":62,"command":63},"npx","npx skills add anthropics\u002Fclaude-plugins-official --skill plugin-settings",{"tool":65,"command":66},"bunx","bunx skills add anthropics\u002Fclaude-plugins-official --skill plugin-settings",{"tool":68,"command":69},"pnpm","pnpm dlx skills add anthropics\u002Fclaude-plugins-official --skill plugin-settings","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002FSKILL.md",true,[73,79,83,89,93,97,101],{"path":74,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":77,"sourceHtmlUrl":78},"examples\u002Fcreate-settings-command.md","REFERENCE","参考文档",2177,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002Fexamples\u002Fcreate-settings-command.md",{"path":80,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":81,"sourceHtmlUrl":82},"examples\u002Fexample-settings.md",2930,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002Fexamples\u002Fexample-settings.md",{"path":84,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":87,"sourceHtmlUrl":88},"examples\u002Fread-settings-hook.sh","SCRIPT","脚本",2205,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002Fexamples\u002Fread-settings-hook.sh",{"path":90,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":91,"sourceHtmlUrl":92},"references\u002Fparsing-techniques.md",11513,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002Freferences\u002Fparsing-techniques.md",{"path":94,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":95,"sourceHtmlUrl":96},"references\u002Freal-world-examples.md",9492,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002Freferences\u002Freal-world-examples.md",{"path":98,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":99,"sourceHtmlUrl":100},"scripts\u002Fparse-frontmatter.sh",1269,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002Fscripts\u002Fparse-frontmatter.sh",{"path":102,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":103,"sourceHtmlUrl":104},"scripts\u002Fvalidate-settings.sh",2712,"https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-settings\u002Fscripts\u002Fvalidate-settings.sh",[106,133,159,182,206,226],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":110,"sourceHtmlUrl":111,"categories":112,"keywords":114,"publishedAt":44},"01M718BVSPNAK6S5NZCYFDBG6E","skill-creator","Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fskill-creator\u002Fskills\u002Fskill-creator\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fskill-creator\u002Fskills\u002Fskill-creator\u002FSKILL.md",[113],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[115,116,117,118,119,120,27,121,122,123,124,125,126,127,128,129,31,130,131,132],"skill creator","creator","performance","improve","run evals","new","analysis","create","optimize","variance analysis","run","edit","benchmark","existing skill","evals","accuracy","scratch","use",{"skillNo":134,"name":135,"nameZh":6,"description":136,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":137,"categories":138,"keywords":144,"publishedAt":44},"01M718BSVAWJRFN6MRCZZ0QX4X","session-report","Generate an explorable HTML report of Claude Code session usage (tokens, cache, subagents, skills, expensive prompts) from ~\u002F.claude\u002Fprojects transcripts.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fsession-report\u002Fskills\u002Fsession-report\u002FSKILL.md",[139],{"categoryNo":140,"categoryName":141,"taxonomyType":142,"taxonomyTypeDesc":143},"01JBSEEDCAT000000000000034","行政与办公人员","PROFESSION","适用职业",[145,146,147,148,149,150,151,152,153,154,155,156,157,158],"session","report","session report","projects","usage","generate","tokens","html report","transcripts","prompts","cache","code","html","subagents",{"skillNo":160,"name":161,"nameZh":6,"description":162,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":163,"categories":164,"keywords":168,"publishedAt":44},"01M718BPKHVD214FAS1T4E5XCE","receipts","Generate a personal Claude Code usage & impact report (\"receipts\") from this machine's local session transcripts — for justifying Claude Code usage\u002Fspend to a manager, self-review, or \"what have I been using this for\" check-ins. Mines ~\u002F.claude\u002Fprojects locally (no extra API calls beyond one final write-up), cross-references local git history, and writes a markdown report plus a self-contained HTML receipt to your home directory. Use when the user asks for \"receipts\", an \"impact report\", \"usage report\", wants to \"show my Claude Code activity\", \"prove the value of Claude Code\", or runs `\u002Freceipts`.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Freceipts\u002Fskills\u002Freceipts\u002FSKILL.md",[165],{"categoryNo":166,"categoryName":167,"taxonomyType":142,"taxonomyTypeDesc":143},"01JBSEEDCAT000000000000030","开发工程师",[161,148,169,170,37,171,27,156,172,173,174,175,150,42,176,177,178,179,180,181],"show","up","impact","api","review","self","references","directory","write","git","activity","my","manager",{"skillNo":183,"name":184,"nameZh":6,"description":185,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":186,"categories":187,"keywords":188,"publishedAt":44},"01M718BJMX0T4691FJQ62GYY5C","project-artifact","Generate and publish a project status artifact — an opinionated, tabbed status page for a project too big for one update (overview & success criteria, the workstream sequence, next steps, plus background, plan, risks & open questions, and decisions\u002FFAQ when they earn a tab) — published with the built-in Artifact tool to a default-private claude.ai page the user can share with teammates. Use when a piece of work spans several workstreams and you want a shareable overview kept current. Each artifact is backed by a small per-project config in the plugin data dir, so refreshing it re-gathers live state, redeploys the same URL, and reports only the delta. For software projects whose workstreams are PRs, also read swe.md (the X.Y PR-numbering convention; pulling PR state with gh\u002Fgit; a per-PR detail block). Needs the built-in Artifact tool (claude.ai login). Not for single-PR changes or public docs.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fproject-artifact\u002Fskills\u002Fproject-artifact\u002FSKILL.md",[],[36,189,190,191,148,192,193,194,195,196,197,27,198,199,200,201,202,203,204,205],"artifact","project artifact","project status","re","default","next steps","open","only","SWE","URL","you","reports","publish","work","plan","status page","next",{"skillNo":207,"name":208,"nameZh":6,"description":209,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":210,"categories":211,"keywords":213,"publishedAt":44},"01M718BF1TTFP5CM0S5HBW64FJ","skill-development","This skill should be used when the user wants to \"create a skill\", \"add a skill to plugin\", \"write a new skill\", \"improve skill description\", \"organize skill content\", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fskill-development\u002FSKILL.md",[212],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[214,215,216,118,120,217,27,156,122,218,177,219,220,221,222,31,223,224,225,24],"development","skill development","skill to plugin","improve skill","structure","organize","new skill","claude code plugins","add","progressive","best practices","progressive disclosure",{"skillNo":227,"name":228,"nameZh":6,"description":229,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":230,"categories":231,"keywords":233,"publishedAt":44},"01M718BCARZ2J4PW0X3AJCZ8MZ","plugin-structure","This skill should be used when the user asks to \"create a plugin\", \"scaffold a plugin\", \"understand plugin structure\", \"organize plugin components\", \"set up plugin.json\", \"use ${CLAUDE_PLUGIN_ROOT}\", \"add commands\u002Fagents\u002Fskills\u002Fhooks\", \"configure auto-discovery\", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.","https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-plugins-official\u002Fblob\u002Fmain\u002Fplugins\u002Fplugin-dev\u002Fskills\u002Fplugin-structure\u002FSKILL.md",[232],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[218,234,24,235,236,237,170,238,239,27,240,156,241,242,122,243,244,245,176,246],"Plugin Structure","SET","plugin architecture","hooks","auto-discovery","auto","configure","components","architecture","component","layout","organization","commands"]