plugin-settings

Implements per-project plugin configuration using YAML frontmatter in .local.md files.

Updated Jul 10, 2026
One-click install
npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill plugin-settings-avatar-arts
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: plugin-settings
Source: https://github.com/AvaTar-ArTs/.Agent-skills/tree/main/skills/plugin-settings
Command: npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill plugin-settings-avatar-arts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Plugin developers need a consistent way to let users customize behavior per project without hardcoding values or committing personal settings to version control. This Skill provides a complete pattern for user-managed configuration files. ## Core Features & Use Cases - Settings File Pattern: Defines the .Codex/plugin-name.local.md convention using YAML frontmatter for structured settings and markdown body for prompts or context. - Parsing Snippets: Provides ready-to-use Bash snippets for extracting frontmatter fields (strings, booleans, numbers) and markdown bodies with sed, grep, and awk. - Security & Best Practices: Covers gitignore rules, input sanitization, path traversal validation, file permissions, and sensible defaults. - Use Case: A hook checks .Codex/my-plugin.local.md at startup, reads the enabled flag, and exits early if the feature is disabled, letting users toggle behavior without editing hook code. ## Quick Start Add a settings file to my plugin that lets users toggle a feature on and off using a .local.md configuration file.

Frequently Asked Questions about plugin-settings

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

FAQPage Schema
How do I add user-configurable settings to a plugin?▼

Create a .local.md file in the project's .Codex directory with YAML frontmatter for settings and a markdown body for context. Hooks and commands parse the frontmatter with sed and grep to read values at runtime.

How to parse YAML frontmatter from a markdown file in Bash?▼

Use sed -n '/^---$/,/^---$/{ /^---$/d; p; }' to extract content between the --- delimiters, then grep and sed to read individual fields. Use awk to extract the markdown body after the second delimiter.

Should .local.md settings files be committed to git?▼

No, .local.md files contain user-specific configuration and must not be committed. Add .Codex/*.local.md and .Codex/*.local.json to .gitignore and document this in the plugin README.

Why do settings changes not take effect immediately?▼

Hooks cannot be hot-reloaded within a running session, so editing a settings file requires restarting the tool. Document this restart requirement in the plugin README so users know to restart after changes.

How do I prevent security issues when reading settings files?▼

Sanitize user input by escaping quotes before writing values, reject file paths containing .. to prevent path traversal, and set restrictive permissions like chmod 600. Validate numeric ranges and provide defaults for missing files.