Guide · Agent skill
How to use the Plugin Settings Pattern agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The plugin-settings skill is a set of instructions, examples and helper scripts that teaches an AI agent how to build Claude Code plugins that remember user preferences for each project. It is written for plugin developers and teams who want a hook or command to change its behaviour based on a small saved configuration. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what it needs to run.
Plugin Settings Patternanthropics/claude-plugins-official · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from the directory page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder.
- 2Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 3Describe the setting you need. Ask for a configurable behaviour in plain words, for example a per-project on/off switch for a hook.
- 4Create the settings file. The agent creates .claude/plugin-name.local.md with a YAML header for values and an optional markdown body for notes.
- 5Read the file from your hook or command. Use the frontmatter snippet to check that the file exists, read enabled, then read the other values and act on them.
- 6Validate and restart. Check numeric and boolean values, use defaults where needed, add the .local.md pattern to .gitignore, and restart Claude Code after changes.
What the plugin-settings skill makes the agent do
The skill documents one pattern: a plugin stores its user-configurable settings in a file called .claude/plugin-name.local.md inside the project directory. The file has a YAML header (the frontmatter) for structured values such as on/off switches and numbers, and a markdown body for notes or prompts to feed back to Claude.
With the skill loaded, the agent can write plugin hooks, commands and agents that check this file, read the values, and adjust what they do. The skill gives ready-made bash snippets for reading the frontmatter, along with example files and two helper scripts for reading and checking these files.
- File location: .claude/plugin-name.local.md in the project root
- Structure: YAML frontmatter followed by a markdown body
- Read from hooks, commands and agents
- Settings are user-managed and meant to be listed in .gitignore
Install the plugin-settings skill
Download the ZIP for the skill from the directory page, then choose one of the following options. The skill is in the anthropics/claude-plugins-official repository under plugins/plugin-dev/skills/plugin-settings and is licensed under Apache-2.0.
For a personal install, unzip the folder into ~/.claude/skills/. To limit it to one project, unzip it into the .claude/skills/ folder of that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Single project: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Ask for the skill with natural requests
You do not need to name the skill. The skill is meant to be used when you ask about the topics in its description, so phrases like the ones below should bring it into play. Be specific about what you want the plugin to remember or toggle.
Good requests name the behaviour you want to control. Vague requests such as 'make it better' give the agent little to work from.
- Store plugin configuration for a hook that runs on file writes, with an on/off switch.
- Make my plugin's validation level user-configurable per project.
- Read YAML frontmatter from a .local.md file in my hook script.
- Show me how to add per-project plugin settings to a slash command.
- Add a max_retries setting that users can change without editing the code.
Build a settings file and read it from a hook
A typical settings file has an enabled flag and a few tuned values. The hook first checks whether the file exists. If it does not, the plugin is treated as not configured and the hook exits quietly. If it does exist, the hook reads the frontmatter and uses the values.
The skill's bash pattern extracts the frontmatter with sed, then reads each field with grep and sed. The example hook script in the skill (examples/read-settings-hook.sh) shows the complete version.
- Check for .claude/my-plugin.local.md and exit if it is missing
- Extract the block between the two --- markers
- Read fields such as enabled, strict_mode or max_retries
- Exit early when enabled is not true
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")Validate values and handle missing settings
The skill recommends validating every value before using it. For a numeric setting, check that it is a number and falls inside an allowed range, and fall back to a default with a warning if it does not. Defaults should be set in the script for the case where the settings file does not exist.
Settings are read from the file, so after you create or edit one, the skill says to restart Claude Code for hooks to recognise the change.
- Validate numeric ranges and report bad values to stderr
- Use defaults when the file is absent
- Restart Claude Code after creating or editing a settings file
- Read the body of the file with awk when you need the notes or prompt text
Keep settings out of git and avoid secrets
The skill treats these files as user-local. Add the .local.md and .local.json patterns to .gitignore and document this in the plugin README so each user keeps their own copy.
Do not store secrets or API keys here. The files are plain text inside the project, and the skill does not cover secure storage.
.claude/*.local.md
.claude/*.local.jsonWhat people use it for
- A plugin hook that runs only in projects where the user has set enabled: true.
- A validation hook whose strictness is set per project with a validation_level value.
- A slash command that reads a saved notification_level or retry count before it runs.
- An agent that reads a state file to know which task it has been assigned and who its coordinator is.
Frequently asked questions
Do I need a paid plan or pay to use the plugin-settings skill?
The skill is published under the Apache-2.0 licence, as stated on its directory page. This page does not list any prices, so check the licence and the Claude product you use for any costs.
What do I need installed to use it?
You need a Claude Code plugin environment, a Bash shell, and the standard Unix tools sed, grep and awk. The example hook script also uses jq. The skill runs scripts and does not use the network.
Where do I put the skill files?
Unzip the ZIP into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to use it in one project. In the Claude apps, you can upload the ZIP under Settings, then Capabilities, then Skills.
Where are plugin settings stored?
Settings are stored in .claude/plugin-name.local.md inside the project root. They use YAML frontmatter for values and a markdown body for extra notes or prompts.
Can I store API keys or passwords in the settings file?
No. The files are plain text inside the project and the skill does not cover secure storage. Keep secrets out of these files.
Why does my plugin ignore changes to the settings file?
The skill says to restart Claude Code after creating or editing a settings file so that hooks recognise the change. Also check that the file is named .claude/plugin-name.local.md and that the frontmatter sits between two --- lines.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building a Claude Code plugin and want users to toggle or tune its behaviour per project with a small saved file. Pick something else if you need secure secret storage or an end-user settings app, since the skill is a build pattern for plugin authors and does not cover either.
Download the skill