jackproai/jackproai-claudecode3.1/plugin-settings
Claude Code and agent skill by jackproai/jackproai-claudecode3.1
- community
- ext:[{"type":"config","description":"Configuration overrides"}]
Checking that the SKILL.md file is still in the repository.
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.
Install
npx vskill@latest install jackproai/jackproai-claudecode3.1/plugin-settingsSemi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard
SKILL.md
The same SKILL.md was published earlier as anthropics/claude-plugins-official/plugin-settings.
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.mdin 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
Example: Plugin State File
.claude/my-plugin.local.md:
Reading Settings Files
From Hooks (Bash Scripts)
Pattern: Check existence and parse frontmatter
See examples/read-settings-hook.sh for complete working example.
From Commands
Commands can read settings files to customize behavior:
From Agents
Agents can reference settings in their instructions:
Parsing Techniques
Extract Frontmatter
Read Individual Fields
String fields:
Boolean fields:
Numeric fields:
Read Markdown Body
Extract content after second ---:
Common Patterns
Pattern 1: Temporarily Active Hooks
Use settings file to control hook activation:
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:
Read from hooks to coordinate agents:
Pattern 3: Configuration-Driven Behavior
.claude/my-plugin.local.md:
Use in hooks or commands:
Creating Settings Files
From Commands
Commands can create settings files:
Template Generation
Provide template in plugin README:
Best Practices
File Naming
✅ DO:
- Use
.claude/plugin-name.local.mdformat - Match plugin name exactly
- Use
.local.mdsuffix for user-local files
❌ DON'T:
- Use different directory (not
.claude/) - Use inconsistent naming
- Use
.mdwithout.local(might be committed)
Gitignore
Always add to .gitignore:
Document this in plugin README.
Defaults
Provide sensible defaults when settings file doesn't exist:
Validation
Validate settings values:
Restart Requirement
Important: Settings changes require Claude Code restart.
Document in your README:
Hooks cannot be hot-swapped within a session.
Security Considerations
Sanitize User Input
When writing settings files from user input:
Validate File Paths
If settings contain file paths:
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:
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:
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
Frontmatter Parsing
Body Parsing
Quick Exit Pattern
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:
- Design settings schema (which fields, types, defaults)
- Create template file in plugin documentation
- Add gitignore entry for
.claude/*.local.md - Implement settings parsing in hooks/commands
- Use quick-exit pattern (check file exists, check enabled field)
- Document settings in plugin README with template
- Remind users that changes require Claude Code restart
Focus on keeping settings simple and providing good defaults when settings file doesn't exist.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryChecking.claude-local-runtime/home/plugins/marketplaces/claude-plugins-official/plugins/plugin-dev/skills/plugin-settings/SKILL.md
Popularity
- Repository stars
- 251
- Repository forks
- 199
- 7-day trend score
- 28
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Extension points
configConfiguration overrides
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/jackproai/jackproai-claudecode3.1/plugin-settings)