鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

plugin-settings

通过在项目根目录创建特定格式的本地配置文件,实现插件行为的灵活定制与状态管理,支持按项目设置启用状态、运行模式及参数阈值,并结合结构化数据与文本内容动态调整自动化流程。

效率工具数据与分析软件开发
访问 GitHub
文档Skills.MD
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

Plugin Settings Pattern for Claude Code Plugins

Overview

Plugins can store user-configurable settings and state in .claude/plugin-name.local.md files 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.md in project root
  • Structure: YAML frontmatter + markdown body
  • Purpose: Per-project plugin configuration and state
  • Usage: Read from hooks, commands, and agents
  • Lifecycle: User-managed (not in git, should be in .gitignore)

File Structure

Basic Template

▼
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 notes

Example: Plugin State File

.claude/my-plugin.local.md:

▼
markdown
复制代码
--- 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 Files

From Hooks (Bash Scripts)

Pattern: Check existence and parse frontmatter

▼
bash
复制代码
#!/bin/bash set -euo pipefail # Define state file path STATE_FILE=".claude/my-plugin.local.md" # Quick exit if file doesn't 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

See examples/read-settings-hook.sh for complete working example.

From Commands

Commands can read settings files to customize behavior:

▼
markdown
复制代码
--- 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

From Agents

Agents can reference settings in their instructions:

▼
markdown
复制代码
--- 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

Parsing Techniques

Extract Frontmatter

▼
bash
复制代码
# Extract everything between --- markers FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

Read Individual Fields

String fields:

▼
bash
复制代码
VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')

Boolean fields:

▼
bash
复制代码
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//') # Compare: if [[ "$ENABLED" == "true" ]]; then

Numeric fields:

▼
bash
复制代码
MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//') # Use: if [[ $MAX -gt 100 ]]; then

Read Markdown Body

Extract content after second ---:

▼
bash
复制代码
# Get everything after closing --- BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Common Patterns

Pattern 1: Temporarily Active Hooks

Use settings file to control hook activation:

▼
bash
复制代码
#!/bin/bash STATE_FILE=".claude/security-scan.local.md" # Quick exit if not configured if [[ ! -f "$STATE_FILE" ]]; then exit 0 fi # Read enabled flag 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 # ...

Use case: Enable/disable hooks without editing hooks.json (requires restart).

Pattern 2: Agent State Management

Store agent-specific state and configuration:

.claude/multi-agent-swarm.local.md:

▼
markdown
复制代码
--- 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 green

Read from hooks to coordinate agents:

▼
bash
复制代码
AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//') COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//') # Send notification to coordinator tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

Pattern 3: Configuration-Driven Behavior

.claude/my-plugin.local.md:

▼
markdown
复制代码
--- 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:

▼
bash
复制代码
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

Creating Settings Files

From Commands

Commands can create settings files:

▼
markdown
复制代码
# 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 changes

Template Generation

Provide template in plugin README:

▼
markdown
复制代码
## 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 Practices

File Naming

✅ DO:

  • Use .claude/plugin-name.local.md format
  • Match plugin name exactly
  • Use .local.md suffix for user-local files

❌ DON'T:

  • Use different directory (not .claude/)
  • Use inconsistent naming
  • Use .md without .local (might be committed)

Gitignore

Always add to .gitignore:

▼
gitignore
复制代码
.claude/*.local.md .claude/*.local.json

Document this in plugin README.

Defaults

Provide sensible defaults when settings file doesn't exist:

▼
bash
复制代码
if [[ ! -f "$STATE_FILE" ]]; then # Use defaults ENABLED=true MODE=standard else # Read from file # ... fi

Validation

Validate settings values:

▼
bash
复制代码
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 MAX=10 # Use default fi

Restart Requirement

Important: Settings changes require Claude Code restart.

Document in your README:

▼
markdown
复制代码
## 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

Hooks cannot be hot-swapped within a session.

Security Considerations

Sanitize User Input

When writing settings files from user input:

▼
bash
复制代码
# Escape quotes in user input SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g') # Write to file cat > "$STATE_FILE" <<EOF --- user_setting: "$SAFE_VALUE" --- EOF

Validate File Paths

If settings contain file paths:

▼
bash
复制代码
FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//') # Check for path traversal if [[ "$FILE_PATH" == *".."* ]]; then echo "⚠️ Invalid path in settings (path traversal)" >&2 exit 2 fi

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, enabled
  • Sends notifications to coordinator if enabled
  • Allows quick activation/deactivation via enabled: true/false

ralph-loop Plugin

.claude/ralph-loop.local.md:

▼
markdown
复制代码
--- 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_iterations
  • Extracts completion_promise for loop termination
  • Reads body as the prompt to feed back
  • Updates iteration count on each loop

Quick Reference

File Location

▼
text
复制代码
project-root/ └── .claude/ └── plugin-name.local.md

Frontmatter Parsing

▼
bash
复制代码
# Extract frontmatter FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE") # Read field VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: *//' | sed 's/^"\(.*\)"$/\1/')

Body Parsing

▼
bash
复制代码
# Extract body (after second ---) BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Quick Exit Pattern

▼
bash
复制代码
if [[ ! -f ".claude/my-plugin.local.md" ]]; then exit 0 # Not configured fi

Additional Resources

Reference Files

For detailed implementation patterns:

  • references/parsing-techniques.md - Complete guide to parsing YAML frontmatter and markdown bodies
  • references/real-world-examples.md - Deep dive into multi-agent-swarm and ralph-loop implementations

Example Files

Working examples in examples/:

  • read-settings-hook.sh - Hook that reads and uses settings
  • create-settings-command.md - Command that creates settings file
  • example-settings.md - Template settings file

Utility Scripts

Development tools in scripts/:

  • validate-settings.sh - Validate settings file structure
  • parse-frontmatter.sh - Extract frontmatter fields

Implementation Workflow

To add settings to a plugin:

  1. Design settings schema (which fields, types, defaults)
  2. Create template file in plugin documentation
  3. Add gitignore entry for .claude/*.local.md
  4. Implement settings parsing in hooks/commands
  5. Use quick-exit pattern (check file exists, check enabled field)
  6. Document settings in plugin README with template
  7. Remind users that changes require Claude Code restart

Focus on keeping settings simple and providing good defaults when settings file doesn't exist.

效率工具
数据与分析
软件开发

快捷安装

复制到终端去安装 Skill

npxskillsaddanthropics/claude-plugins-official--skill"plugin-settings"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。