Development
ai-coding-agents-settings-policy
Designs settings and policy layers for coding-agent runtimes. Use when modeling source precedence, managed policy, env controls, or runtime settings validation.
vasilyu1983 · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add vasilyu1983/AI-Agents-public --skill ai-coding-agents-settings-policyAbout this skill
name: ai-coding-agents-settings-policy description: "Designs settings and policy layers for coding-agent runtimes. Use when modeling source precedence, managed policy, env controls, or runtime settings validation." compatibility: Portable core. Works on Claude Code and Codex. version: "1.1" last_validated: 2026-07-11
AI Coding Agents Settings Policy
Use this skill to design or review the settings and policy layer of a coding-agent runtime: settings sources, precedence, managed policy, validation, safe environment handling, and runtime application of settings changes.
This skill owns configuration and policy architecture for coding-agent runtimes. For project memory in AGENTS.md or CLAUDE.md, use ../agents-memory/SKILL.md.
ASCII Flow
settings sources
defaults + managed policy + user + project + local + flags + env
|
v
precedence merge
deterministic order + source provenance + plugin-only restrictions
|
v
validation
schema + forbidden keys + unsafe env + unknown options
|
v
runtime application
provider policy + tools + permissions + plugins + UI + cache invalidation
|
v
audit record
effective settings without secrets
Quick Reference
| Question | Read | Outcome |
|---|---|---|
| How should settings sources and policy precedence work? | references/settings-source-precedence-and-managed-policy.md | Source model, merge order, managed policy, plugin-only restrictions |
| How should settings be validated and applied safely? | references/settings-validation-and-safe-runtime-application.md | Schema validation, invalid-rule handling, safe env controls, runtime re-application |
| What are the exact override examples for each settings layer? | references/settings-precedence-table.md | Full precedence table: managed > CLI flags > local > project > user, with concrete examples and cache invalidation |
| Which sources can enable plugin surfaces? | references/plugin-only-restriction-recipes.md | Trust-class recipes for locking, scoping, and logging plugin-surface activations |
| How is ToolSearch gated by settings policy? | references/deferred-tool-policy-layer.md | Settings keys, policy decision flow, and interaction with tool-pool assembly |
| How does OpenAI Codex separate config layers from managed requirements? | references/openai-codex-managed-config-and-requirements.md | Layer stack, requirements constraints, managed-hooks-only mode, debug surfaces |
When To Use
- Design a settings system for a coding-agent CLI or runtime
- Separate user, project, local, flag, and managed policy sources
- Review how managed settings should override user configuration
- Define which environment variables or customization surfaces are safe to accept
- Apply runtime settings changes without restarting the whole process
Use Other Skills
| Need | Use Instead |
|---|---|
| Broader coding-agent architecture | ../ai-coding-agents/SKILL.md |
| Tool approval and permission modes | ../ai-coding-agents-permissions/SKILL.md |
| Plugin package architecture | ../ai-coding-agents-plugins/SKILL.md |
| AGENTS.md or CLAUDE.md repo memory | ../agents-memory/SKILL.md |
| Generic config or schema design outside agent runtimes | ../software-devtools/SKILL.md |
Default Workflow
- Define source layers. Separate user, shared project, local gitignored, CLI-flag, and managed-policy sources.
- Freeze precedence. Document one merge order and keep it consistent across disk reads, UI display, and runtime application.
- Make managed policy authoritative. Policy layers should override user-controlled settings and bypass local customization where required.
- Validate at the boundary. Parse, coerce, and validate settings before they mutate runtime state.
- Fail soft on invalid fragments. Preserve the file on disk, but ignore invalid pieces when safe to do so.
- Protect dangerous env and customization surfaces. Whitelist what can be applied automatically; strip or gate anything that could redirect providers or execute shell code.
- Separate cache tiers. Keep merged settings, per-source reads, and parsed-file caches distinct so invalidation is targeted and explainable.
- Apply changes through one runtime path. Re-read settings, snapshot hooks or dependent callbacks, reload dependent subsystems, and update app state through a single function.
- Test hostile cases. Cover malformed JSON, invalid permission rules, drop-in conflicts, managed overrides, and live settings-change notifications.
Host Rules
- Keep source precedence explicit and stable.
- Always include managed-policy and CLI-flag sources even when users restrict editable sources.
- Distinguish editable sources from read-only policy and flag overlays.
- Prefer schema validation plus targeted filtering over all-or-nothing rejection when individual rules are bad.
- Keep dangerous environment settings and shell-like helper values behind explicit trust gates.
- Apply settings changes by recomputing derived runtime state, not by mutating scattered subsystems in place.
- Treat plugin-only customization policy as source-aware. Not every settings source is equally trusted to enable plugin surfaces.
- Sanitize persisted permission rules after reload before they become active state.
Build Order
- Define settings sources and immutable precedence.
- Define t