skills.rest
ace8991
ace8991COMMUNITY
Explore all skills by this author →
GitHub

Plugin Settings

Implements per-project plugin configuration using .claude/plugin-name.local.md files with YAML frontmatter.

Updated Mar 22, 2026
Search Tags:#claude code#hooks#plugin development#yaml frontmatter#plugin configuration#bash parsing#settings file
One-click install
npx skills add https://github.com/ace8991/agentos --skill plugin-settings-ace8991
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: Plugin Settings
Source: https://github.com/ace8991/agentos/tree/main/.tmp_claude_code/claude-code-main/plugins/plugin-dev/skills/plugin-settings
Command: npx skills add https://github.com/ace8991/agentos --skill plugin-settings-ace8991

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Claude Code plugins often need user-configurable behavior and persistent state, but there is no built-in settings mechanism. This Skill documents the .claude/plugin-name.local.md pattern so plugin authors can store per-project configuration and state in a structured, gitignored file. ## Core Features & Use Cases - Settings File Pattern: Defines a standard file structure combining YAML frontmatter for structured fields with a markdown body for prompts and context. - Bash Parsing Techniques: Provides sed, grep, and awk patterns for extracting frontmatter fields and markdown bodies from hooks, commands, and agents. - Validation & Utility Scripts: Includes validate-settings.sh and parse-frontmatter.sh scripts plus real-world examples from the multi-agent-swarm and ralph-wiggum plugins. - Use Case: A plugin author building a validation hook can let users toggle strict mode, file size limits, and enable/disable flags by editing .claude/my-plugin.local.md instead of modifying hook code. ## Quick Start Ask the AI to add a configurable settings file to your plugin using the .claude/plugin-name.local.md pattern with YAML frontmatter and hook parsing logic.

Frequently Asked Questions about Plugin Settings

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make a Claude Code plugin configurable per project?▼

Create a `.claude/plugin-name.local.md` file in the project root with YAML frontmatter for settings and a markdown body for context. Hooks and commands parse the frontmatter with sed and grep to read fields like enabled, mode, and max_file_size.

How do I parse YAML frontmatter in a bash hook script?▼

Extract the frontmatter with `sed -n '/^---$/,/^---$/{ /^---$/d; p; }'` on the file, then pull individual fields using grep and sed. For the markdown body, use `awk '/^---$/{i++; next} i>=2'` to capture everything after the second marker.

Should plugin settings files be committed to git?▼

No, settings files are user-local and should be gitignored. Add `.claude/*.local.md` and `.claude/*.local.json` to the project .gitignore, and document this requirement in the plugin README.

Do plugin settings changes take effect immediately in Claude Code?▼

No, changes to settings files require restarting Claude Code because hooks cannot be hot-swapped within a session. Users must save the file, exit, and restart for new settings to load.

How do I update a settings file field without corrupting it?▼

Use atomic updates: write the modified content to a temporary file with sed, then move it over the original with mv. This prevents corruption if the process is interrupted mid-write.

Related Skills

Explore More Software Engineering Skills→
thevibeworksthevibeworks
28

plugin-structure

Define Claude Code plugin directory layout, manifest configuration, and component discovery rules.

Official
Intermediate
anselsourceanselsource

write-plugin-marketplaces

Create and distribute Claude Code plugin marketplaces with marketplace.json.

Official
Intermediate
VimuraiVimurai

scope_safety

Enforces filesystem and shell scope boundaries on every file and shell operation.

Community
Basic
open-sessionopen-session

Plugin Settings

Parse and validate plugin settings from markdown files with YAML frontmatter.

Official
Advanced