surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / plugin-settings / SKILL.md

544 lines · 11.8 KBPreview CodeRaw

1	---
2	name: Plugin Settings
3	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.
4	version: 0.1.0
5	---
6
7	# Plugin Settings Pattern for Claude Code Plugins
8
9	## Overview
10
11	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.
12
13	Key characteristics:
14	- File location: `.claude/plugin-name.local.md` in project root
15	- Structure: YAML frontmatter + markdown body
16	- Purpose: Per-project plugin configuration and state
17	- Usage: Read from hooks, commands, and agents
18	- Lifecycle: User-managed (not in git, should be in `.gitignore`)
19
20	## File Structure
21
22	### Basic Template
23
24	```markdown
25	---
26	enabled: true
27	setting1: value1
28	setting2: value2
29	numeric_setting: 42
30	list_setting: ["item1", "item2"]
31	---
32
33	# Additional Context
34
35	This markdown body can contain:
36	- Task descriptions
37	- Additional instructions
38	- Prompts to feed back to Claude
39	- Documentation or notes
40	```
41
42	### Example: Plugin State File
43
44	.claude/my-plugin.local.md:
45	```markdown
46	---
47	enabled: true
48	strict_mode: false
49	max_retries: 3
50	notification_level: info
51	coordinator_session: team-leader
52	---
53
54	# Plugin Configuration
55
56	This plugin is configured for standard validation mode.
57	Contact @team-lead with questions.
58	```
59
60	## Reading Settings Files
61
62	### From Hooks (Bash Scripts)
63
64	Pattern: Check existence and parse frontmatter
65
66	```bash
67	#!/bin/bash
68	set -euo pipefail
69
70	# Define state file path
71	STATE_FILE=".claude/my-plugin.local.md"
72
73	# Quick exit if file doesn't exist
74	if [[ ! -f "$STATE_FILE" ]]; then
75	exit 0 # Plugin not configured, skip
76	fi
77
78	# Parse YAML frontmatter (between --- markers)
79	FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
80
81	# Extract individual fields
82	ENABLED=$(echo "$FRONTMATTER" \| grep '^enabled:' \| sed 's/enabled: //' \| sed 's/^"$.$"$/\1/')
83	STRICT_MODE=$(echo "$FRONTMATTER" \| grep '^strict_mode:' \| sed 's/strict_mode: //' \| sed 's/^"$.$"$/\1/')
84
85	# Check if enabled
86	if [[ "$ENABLED" != "true" ]]; then
87	exit 0 # Disabled
88	fi
89
90	# Use configuration in hook logic
91	if [[ "$STRICT_MODE" == "true" ]]; then
92	# Apply strict validation
93	# ...
94	fi
95	```
96
97	See `examples/read-settings-hook.sh` for complete working example.
98
99	### From Commands
100
101	Commands can read settings files to customize behavior:
102
103	```markdown
104	---
105	description: Process data with plugin
106	allowed-tools: ["Read", "Bash"]
107	---
108
109	# Process Command
110
111	Steps:
112	1. Check if settings exist at `.claude/my-plugin.local.md`
113	2. Read configuration using Read tool
114	3. Parse YAML frontmatter to extract settings
115	4. Apply settings to processing logic
116	5. Execute with configured behavior
117	```
118
119	### From Agents
120
121	Agents can reference settings in their instructions:
122
123	```markdown
124	---
125	name: configured-agent
126	description: Agent that adapts to project settings
127	---
128
129	Check for plugin settings at `.claude/my-plugin.local.md`.
130	If present, parse YAML frontmatter and adapt behavior according to:
131	- enabled: Whether plugin is active
132	- mode: Processing mode (strict, standard, lenient)
133	- Additional configuration fields
134	```
135
136	## Parsing Techniques
137
138	### Extract Frontmatter
139
140	```bash
141	# Extract everything between --- markers
142	FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")
143	```
144
145	### Read Individual Fields
146
147	String fields:
148	```bash
149	VALUE=$(echo "$FRONTMATTER" \| grep '^field_name:' \| sed 's/field_name: //' \| sed 's/^"$.$"$/\1/')
150	```
151
152	Boolean fields:
153	```bash
154	ENABLED=$(echo "$FRONTMATTER" \| grep '^enabled:' \| sed 's/enabled: *//')
155	# Compare: if [[ "$ENABLED" == "true" ]]; then
156	```
157
158	Numeric fields:
159	```bash
160	MAX=$(echo "$FRONTMATTER" \| grep '^max_value:' \| sed 's/max_value: *//')
161	# Use: if [[ $MAX -gt 100 ]]; then
162	```
163
164	### Read Markdown Body
165
166	Extract content after second `---`:
167
168	```bash
169	# Get everything after closing ---
170	BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")
171	```
172
173	## Common Patterns
174
175	### Pattern 1: Temporarily Active Hooks
176
177	Use settings file to control hook activation:
178
179	```bash
180	#!/bin/bash
181	STATE_FILE=".claude/security-scan.local.md"
182
183	# Quick exit if not configured
184	if [[ ! -f "$STATE_FILE" ]]; then
185	exit 0
186	fi
187
188	# Read enabled flag
189	FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
190	ENABLED=$(echo "$FRONTMATTER" \| grep '^enabled:' \| sed 's/enabled: *//')
191
192	if [[ "$ENABLED" != "true" ]]; then
193	exit 0 # Disabled
194	fi
195
196	# Run hook logic
197	# ...
198	```
199
200	Use case: Enable/disable hooks without editing hooks.json (requires restart).
201
202	### Pattern 2: Agent State Management
203
204	Store agent-specific state and configuration:
205
206	.claude/multi-agent-swarm.local.md:
207	```markdown
208	---
209	agent_name: auth-agent
210	task_number: 3.5
211	pr_number: 1234
212	coordinator_session: team-leader
213	enabled: true
214	dependencies: ["Task 3.4"]
215	---
216
217	# Task Assignment
218
219	Implement JWT authentication for the API.
220
221	Success Criteria:
222	- Authentication endpoints created
223	- Tests passing
224	- PR created and CI green
225	```
226
227	Read from hooks to coordinate agents:
228
229	```bash
230	AGENT_NAME=$(echo "$FRONTMATTER" \| grep '^agent_name:' \| sed 's/agent_name: *//')
231	COORDINATOR=$(echo "$FRONTMATTER" \| grep '^coordinator_session:' \| sed 's/coordinator_session: *//')
232
233	# Send notification to coordinator
234	tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter
235	```
236
237	### Pattern 3: Configuration-Driven Behavior
238
239	.claude/my-plugin.local.md:
240	```markdown
241	---
242	validation_level: strict
243	max_file_size: 1000000
244	allowed_extensions: [".js", ".ts", ".tsx"]
245	enable_logging: true
246	---
247
248	# Validation Configuration
249
250	Strict mode enabled for this project.
251	All writes validated against security policies.
252	```
253
254	Use in hooks or commands:
255
256	```bash
257	LEVEL=$(echo "$FRONTMATTER" \| grep '^validation_level:' \| sed 's/validation_level: *//')
258
259	case "$LEVEL" in
260	strict)
261	# Apply strict validation
262	;;
263	standard)
264	# Apply standard validation
265	;;
266	lenient)
267	# Apply lenient validation
268	;;
269	esac
270	```
271
272	## Creating Settings Files
273
274	### From Commands
275
276	Commands can create settings files:
277
278	```markdown
279	# Setup Command
280
281	Steps:
282	1. Ask user for configuration preferences
283	2. Create `.claude/my-plugin.local.md` with YAML frontmatter
284	3. Set appropriate values based on user input
285	4. Inform user that settings are saved
286	5. Remind user to restart Claude Code for hooks to recognize changes
287	```
288
289	### Template Generation
290
291	Provide template in plugin README:
292
293	```markdown
294	## Configuration
295
296	Create `.claude/my-plugin.local.md` in your project:
297
298	\`\`\`markdown
299	---
300	enabled: true
301	mode: standard
302	max_retries: 3
303	---
304
305	# Plugin Configuration
306
307	Your settings are active.
308	\`\`\`
309
310	After creating or editing, restart Claude Code for changes to take effect.
311	```
312
313	## Best Practices
314
315	### File Naming
316
317	✅ DO:
318	- Use `.claude/plugin-name.local.md` format
319	- Match plugin name exactly
320	- Use `.local.md` suffix for user-local files
321
322	❌ DON'T:
323	- Use different directory (not `.claude/`)
324	- Use inconsistent naming
325	- Use `.md` without `.local` (might be committed)
326
327	### Gitignore
328
329	Always add to `.gitignore`:
330
331	```gitignore
332	.claude/*.local.md
333	.claude/*.local.json
334	```
335
336	Document this in plugin README.
337
338	### Defaults
339
340	Provide sensible defaults when settings file doesn't exist:
341
342	```bash
343	if [[ ! -f "$STATE_FILE" ]]; then
344	# Use defaults
345	ENABLED=true
346	MODE=standard
347	else
348	# Read from file
349	# ...
350	fi
351	```
352
353	### Validation
354
355	Validate settings values:
356
357	```bash
358	MAX=$(echo "$FRONTMATTER" \| grep '^max_value:' \| sed 's/max_value: *//')
359
360	# Validate numeric range
361	if ! [[ "$MAX" =~ ^[0-9]+$ ]] \|\| [[ $MAX -lt 1 ]] \|\| [[ $MAX -gt 100 ]]; then
362	echo "⚠️ Invalid max_value in settings (must be 1-100)" >&2
363	MAX=10 # Use default
364	fi
365	```
366
367	### Restart Requirement
368
369	Important: Settings changes require Claude Code restart.
370
371	Document in your README:
372
373	```markdown
374	## Changing Settings
375
376	After editing `.claude/my-plugin.local.md`:
377	1. Save the file
378	2. Exit Claude Code
379	3. Restart: `claude` or `cc`
380	4. New settings will be loaded
381	```
382
383	Hooks cannot be hot-swapped within a session.
384
385	## Security Considerations
386
387	### Sanitize User Input
388
389	When writing settings files from user input:
390
391	```bash
392	# Escape quotes in user input
393	SAFE_VALUE=$(echo "$USER_INPUT" \| sed 's/"/\\"/g')
394
395	# Write to file
396	cat > "$STATE_FILE" <<EOF
397	---
398	user_setting: "$SAFE_VALUE"
399	---
400	EOF
401	```
402
403	### Validate File Paths
404
405	If settings contain file paths:
406
407	```bash
408	FILE_PATH=$(echo "$FRONTMATTER" \| grep '^data_file:' \| sed 's/data_file: *//')
409
410	# Check for path traversal
411	if [[ "$FILE_PATH" == ".." ]]; then
412	echo "⚠️ Invalid path in settings (path traversal)" >&2
413	exit 2
414	fi
415	```
416
417	### Permissions
418
419	Settings files should be:
420	- Readable by user only (`chmod 600`)
421	- Not committed to git
422	- Not shared between users
423
424	## Real-World Examples
425
426	### multi-agent-swarm Plugin
427
428	.claude/multi-agent-swarm.local.md:
429	```markdown
430	---
431	agent_name: auth-implementation
432	task_number: 3.5
433	pr_number: 1234
434	coordinator_session: team-leader
435	enabled: true
436	dependencies: ["Task 3.4"]
437	additional_instructions: Use JWT tokens, not sessions
438	---
439
440	# Task: Implement Authentication
441
442	Build JWT-based authentication for the REST API.
443	Coordinate with auth-agent on shared types.
444	```
445
446	Hook usage (agent-stop-notification.sh):
447	- Checks if file exists (line 15-18: quick exit if not)
448	- Parses frontmatter to get coordinator_session, agent_name, enabled
449	- Sends notifications to coordinator if enabled
450	- Allows quick activation/deactivation via `enabled: true/false`
451
452	### ralph-wiggum Plugin
453
454	.claude/ralph-loop.local.md:
455	```markdown
456	---
457	iteration: 1
458	max_iterations: 10
459	completion_promise: "All tests passing and build successful"
460	---
461
462	Fix all the linting errors in the project.
463	Make sure tests pass after each fix.
464	```
465
466	Hook usage (stop-hook.sh):
467	- Checks if file exists (line 15-18: quick exit if not active)
468	- Reads iteration count and max_iterations
469	- Extracts completion_promise for loop termination
470	- Reads body as the prompt to feed back
471	- Updates iteration count on each loop
472
473	## Quick Reference
474
475	### File Location
476
477	```
478	project-root/
479	└── .claude/
480	└── plugin-name.local.md
481	```
482
483	### Frontmatter Parsing
484
485	```bash
486	# Extract frontmatter
487	FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")
488
489	# Read field
490	VALUE=$(echo "$FRONTMATTER" \| grep '^field:' \| sed 's/field: //' \| sed 's/^"$.$"$/\1/')
491	```
492
493	### Body Parsing
494
495	```bash
496	# Extract body (after second ---)
497	BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")
498	```
499
500	### Quick Exit Pattern
501
502	```bash
503	if [[ ! -f ".claude/my-plugin.local.md" ]]; then
504	exit 0 # Not configured
505	fi
506	```
507
508	## Additional Resources
509
510	### Reference Files
511
512	For detailed implementation patterns:
513
514	- `references/parsing-techniques.md` - Complete guide to parsing YAML frontmatter and markdown bodies
515	- `references/real-world-examples.md` - Deep dive into multi-agent-swarm and ralph-wiggum implementations
516
517	### Example Files
518
519	Working examples in `examples/`:
520
521	- `read-settings-hook.sh` - Hook that reads and uses settings
522	- `create-settings-command.md` - Command that creates settings file
523	- `example-settings.md` - Template settings file
524
525	### Utility Scripts
526
527	Development tools in `scripts/`:
528
529	- `validate-settings.sh` - Validate settings file structure
530	- `parse-frontmatter.sh` - Extract frontmatter fields
531
532	## Implementation Workflow
533
534	To add settings to a plugin:
535
536	1. Design settings schema (which fields, types, defaults)
537	2. Create template file in plugin documentation
538	3. Add gitignore entry for `.claude/*.local.md`
539	4. Implement settings parsing in hooks/commands
540	5. Use quick-exit pattern (check file exists, check enabled field)
541	6. Document settings in plugin README with template
542	7. Remind users that changes require Claude Code restart
543
544	Focus on keeping settings simple and providing good defaults when settings file doesn't exist.