From plugin-creator
Implements per-project plugin configuration via .claude/*.local.md files with YAML frontmatter. Covers Bash hook parsing, skill/agent reading, patterns for hooks/agent/loop state, security, and best practices.
npx claudepluginhub jamie-bitflight/claude_skills --plugin plugin-creatorThis skill uses the workspace's default tool permissions.
Plugins store user-configurable settings in `.claude/plugin-name.local.md` files within the project directory. YAML frontmatter provides structured configuration; the markdown body carries prompts or additional context.
Documents .claude/plugin-name.local.md files for per-project plugin settings with YAML frontmatter. Shows bash parsing in hooks and command usage for configurable plugins.
Configures per-project plugin settings using .claude/plugin-name.local.md files with YAML frontmatter. Covers gitignore setup, bash hook reading, and agent state management for customizable plugins.
Provides canonical reference for Claude Code plugin schemas, frontmatter fields, hook events, and naming conventions. Injects into Codex audit prompts for artifact validation.
Share bugs, ideas, or general feedback.
Plugins store user-configurable settings in .claude/plugin-name.local.md files within the project directory. YAML frontmatter provides structured configuration; the markdown body carries prompts or additional context.
flowchart TD
Start(["Plugin needs user-configurable behavior"]) --> Q1{What kind of state?}
Q1 -->|"Per-project configuration<br>(validation level, enabled/disabled, limits)"| Settings["Use .claude/plugin-name.local.md<br>YAML frontmatter for config values"]
Q1 -->|"Agent coordination state<br>(task assignment, session tracking)"| AgentState["Use .claude/plugin-name.local.md<br>Frontmatter for metadata<br>Body for task description"]
Q1 -->|"Hook activation control<br>(enable/disable without editing hooks.json)"| HookControl["Use .claude/plugin-name.local.md<br>enabled: true/false field"]
Q1 -->|"Loop iteration state<br>(iteration counter, completion promise)"| LoopState["Use .claude/plugin-name.local.md<br>Frontmatter tracks loop state<br>Body is the prompt to loop"]
Settings --> Location
AgentState --> Location
HookControl --> Location
LoopState --> Location
Location["File location — .claude/plugin-name.local.md<br>Lifecycle — user-managed, gitignored<br>Structure — YAML frontmatter + markdown body<br>Consumers — hooks, skills, agents"]
---
enabled: true
setting1: value1
numeric_setting: 42
list_setting: ["item1", "item2"]
---
# Additional Context
Markdown body for prompts, task descriptions,
additional instructions, or documentation.
The standard pattern for reading settings in hooks follows three steps — check existence, parse frontmatter, extract fields.
#!/bin/bash
set -euo pipefail
STATE_FILE=".claude/my-plugin.local.md"
# Quick exit if not configured
if [[ ! -f "$STATE_FILE" ]]; then
exit 0
fi
# Parse YAML frontmatter (between --- markers)
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
# Extract fields
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')
if [[ "$ENABLED" != "true" ]]; then
exit 0
fi
Skills and agents read settings with the Read tool, then parse YAML frontmatter inline.
Check for plugin settings at `.claude/my-plugin.local.md`.
If present, parse YAML frontmatter and adapt behavior according to:
- enabled field controls whether the plugin is active
- mode field selects processing behavior (strict, standard, lenient)
Content after the closing --- marker is the body.
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")
Control hook activation via settings file instead of editing hooks.json (which requires restart).
STATE_FILE=".claude/security-scan.local.md"
if [[ ! -f "$STATE_FILE" ]]; then
exit 0
fi
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
if [[ "$ENABLED" != "true" ]]; then
exit 0
fi
# Run hook logic only when enabled
Store agent-specific state and task assignments.
---
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.
Hooks read this to coordinate agents.
AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')
COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')
tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter
Settings drive validation strictness, file size limits, and allowed extensions.
LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')
case "$LEVEL" in
strict) ;; # Maximum validation
standard) ;; # Balanced validation
lenient) ;; # Minimal validation
esac
flowchart TD
Start(["Add settings to a plugin"]) --> S1["Design settings schema<br>— which fields, types, defaults"]
S1 --> S2["Create template in plugin README<br>— document the .local.md format"]
S2 --> S3["Add .gitignore entry<br>— .claude/*.local.md"]
S3 --> S4["Implement parsing in hooks/skills<br>— use quick-exit pattern"]
S4 --> S5["Provide sensible defaults<br>— when settings file is absent"]
S5 --> S6["Document restart requirement<br>— changes need session restart"]
File naming — use .claude/plugin-name.local.md format. The .local suffix signals user-local, gitignored files.
Gitignore — add to project .gitignore:
.claude/*.local.md
.claude/*.local.json
Defaults — provide sensible defaults when the settings file does not exist.
if [[ ! -f "$STATE_FILE" ]]; then
ENABLED=true
MODE=standard
else
# Parse from file
fi
Validation — validate field values before use.
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
echo "Invalid max_value in settings (must be 1-100)" >&2
MAX=10
fi
Atomic updates — use temp file + atomic move to prevent corruption.
TEMP_FILE="${FILE}.tmp.$$"
sed "s/^field: .*/field: $NEW_VALUE/" "$FILE" > "$TEMP_FILE"
mv "$TEMP_FILE" "$FILE"
Restart requirement — settings changes require Claude Code session restart. Document this in the plugin README.
Sanitize user input when writing settings files.
SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')
Validate file paths stored in settings to prevent 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.
For detailed parsing techniques (field extraction, body parsing, atomic updates, edge cases, yq integration), read Parsing Techniques Reference.
For production examples showing complete settings file lifecycles in real plugins, read Real-World Examples.
/plugin-creator:hooks-guide/plugin-creator:component-patterns/plugin-creator:command-developmentSOURCE: Adapted from Anthropic plugin-dev plugin skills/plugin-settings/ (8 files, ~545 lines). Accessed 2026-03-24.