Evolving Agent Configuration
Audit AI coding-agent configuration with local evidence first and current vendor
docs second. Default to review-only. Apply fixes only after explicit approval.
For installed cc-thingz resource/version diagnostics, use installation-doctor
first. Continue here for broader configuration review or authorized changes.
Read first
references/RUBRIC.md for shared review dimensions and severity.
references/platforms/claude-code.md for Claude Code surfaces.
references/platforms/codex.md for Codex surfaces.
references/platforms/pi.md for Pi surfaces.
references/apply-fixes.md only when the user asks to fix or passes --fix.
Modes
Review-only is the default for prompts such as "review my config", "audit
config", "check setup", or "what should I improve".
Fix mode starts only when the user explicitly asks for changes or passes --fix.
Even in fix mode, ask before risky changes: permissions, sandbox policy, hooks,
MCP servers, model routing, deletes, moves, broad rewrites, or private config.
Scope
Review these AI-agent configuration surfaces:
- Instruction files:
AGENTS.md, CLAUDE.md, command prompts, skill and agent bodies.
- Claude Code:
.claude/, user/project/local settings, hooks, skills, agents, MCP, permissions.
- Codex:
.codex/, ~/.codex/config.toml, project config, profiles, sandbox, approvals, MCP, skills, subagents.
- Pi:
.pi/, ~/.pi/agent/, settings, packages, skills, extensions, prompts, themes, context files.
- Plugin/package manifests and source-to-generated export rules.
- chezmoi or dotfile copies only when deployment is part of the request.
Do not review:
- app runtime config
- git hook hygiene
- score-only instruction prose or prompt quality; use
reviewing-instructions
- product docs
- source-code quality
- generated output as the source of truth
Workflow
- Identify the requested platform, config root, and mode.
- If ambiguous, list detected config surfaces and ask which to audit.
- Inventory relevant files with paths, sizes, and source/generated status.
- Read current files before recommending changes.
- Use the platform reference and shared rubric to check expected structure, high-risk settings, invocation fit, and always-loaded context cost.
- When the audit touches skills, agents, prompts, or package manifests, inspect thin-router risk, weak pointers to must-read support files, and whether plugin grouping forces unrelated instructions into startup context.
- Use official docs or changelogs when syntax, feature availability, or deprecation status is uncertain.
- Use broad web research only for gaps or ecosystem comparisons; do not recommend changes from uncited blogs alone.
- Classify findings by impact and disruption.
- In fix mode, apply only approved changes and verify with available validation commands.
Priorities
Flag these first:
- unsupported or stale config keys, tool names, hook events, or model names
- unsafe permissions, sandbox bypasses, broad MCP access, or secret exposure
- generated exports edited by hand instead of source files
- duplicate or overlapping skills, agents, hooks, prompts, or trigger descriptions
- model-invoked descriptions that do not earn their always-loaded cost
- thin-router skills or prompts with little independent capability
- weak pointers from entrypoints to must-read support files
- bloated startup context or plugin grouping that should be on demand
- hooks or extensions that hide errors, block safe work, or run risky commands
- missing validation for config that produces skills, agents, hooks, or packages
Output
Use optional finding tags such as routing/thin-router,
context/weak-pointer, or invocation/over-model-invoked when they sharpen the
issue.
## Config Audit
Scope: <platforms/files>
Mode: review-only | fix-approved
Sources: <local files and docs checked>
Confidence: high | medium | low
### Summary
- Files reviewed: N
- Generated files skipped: N
- Main risk: <one sentence>
### Critical
- `path:line` — <category[/subtype]>: <issue>. Evidence: <fact>. Fix: <action>.
### Important
- `path:line` — <category[/subtype]>: <issue>. Evidence: <fact>. Fix: <action>.
### Suggested
- `path:line` — <category[/subtype]>: <issue>. Evidence: <fact>. Fix: <action>.
### Working Well
- <config that should stay as-is>
### Verification
- <command run or recommended>
Omit empty severity sections. If no findings are confirmed, say No confirmed findings.
Failure handling
- Ambiguous target: ask one scoped question before auditing.
- Missing official docs: use local evidence, lower confidence, and report the gap.
- Generated file target: report the source path and regeneration command instead of editing it.
- Secrets or private data: do not quote secret values; identify only the path and key name when needed.
- Validation failure after a fix: revert the change unless the user asks to keep it, then report the exact error.
1---2description:3 Audit and improve AI coding-agent configuration. Use when reviewing or4 changing Claude Code, Pi, Codex, skill, agent, hook, MCP, permission, package, or5 generated-export setup. Default is review-only; fixes require explicit user approval6 or --fix. NOT for score-only instruction review or prompt lint; use reviewing-instructions.7 NOT for application config, git hygiene, code bugs, ordinary docs, or generated8 files without their source.9name: evolving-config10metadata:11 source: https://skillmd.com/skills/alexei-led/evolving-config12---1314# Evolving Agent Configuration1516Audit AI coding-agent configuration with local evidence first and current vendor17docs second. Default to review-only. Apply fixes only after explicit approval.1819For installed cc-thingz resource/version diagnostics, use `installation-doctor`20first. Continue here for broader configuration review or authorized changes.2122## Read first2324- `references/RUBRIC.md` for shared review dimensions and severity.25- `references/platforms/claude-code.md` for Claude Code surfaces.26- `references/platforms/codex.md` for Codex surfaces.27- `references/platforms/pi.md` for Pi surfaces.28- `references/apply-fixes.md` only when the user asks to fix or passes `--fix`.2930## Modes3132Review-only is the default for prompts such as "review my config", "audit33config", "check setup", or "what should I improve".3435Fix mode starts only when the user explicitly asks for changes or passes `--fix`.36Even in fix mode, ask before risky changes: permissions, sandbox policy, hooks,37MCP servers, model routing, deletes, moves, broad rewrites, or private config.3839## Scope4041Review these AI-agent configuration surfaces:4243- Instruction files: `AGENTS.md`, `CLAUDE.md`, command prompts, skill and agent bodies.44- Claude Code: `.claude/`, user/project/local settings, hooks, skills, agents, MCP, permissions.45- Codex: `.codex/`, `~/.codex/config.toml`, project config, profiles, sandbox, approvals, MCP, skills, subagents.46- Pi: `.pi/`, `~/.pi/agent/`, settings, packages, skills, extensions, prompts, themes, context files.47- Plugin/package manifests and source-to-generated export rules.48- chezmoi or dotfile copies only when deployment is part of the request.4950Do not review:5152- app runtime config53- git hook hygiene54- score-only instruction prose or prompt quality; use `reviewing-instructions`55- product docs56- source-code quality57- generated output as the source of truth5859## Workflow60611. Identify the requested platform, config root, and mode.622. If ambiguous, list detected config surfaces and ask which to audit.633. Inventory relevant files with paths, sizes, and source/generated status.644. Read current files before recommending changes.655. Use the platform reference and shared rubric to check expected structure, high-risk settings, invocation fit, and always-loaded context cost.666. When the audit touches skills, agents, prompts, or package manifests, inspect thin-router risk, weak pointers to must-read support files, and whether plugin grouping forces unrelated instructions into startup context.677. Use official docs or changelogs when syntax, feature availability, or deprecation status is uncertain.688. Use broad web research only for gaps or ecosystem comparisons; do not recommend changes from uncited blogs alone.699. Classify findings by impact and disruption.7010. In fix mode, apply only approved changes and verify with available validation commands.7172## Priorities7374Flag these first:7576- unsupported or stale config keys, tool names, hook events, or model names77- unsafe permissions, sandbox bypasses, broad MCP access, or secret exposure78- generated exports edited by hand instead of source files79- duplicate or overlapping skills, agents, hooks, prompts, or trigger descriptions80- model-invoked descriptions that do not earn their always-loaded cost81- thin-router skills or prompts with little independent capability82- weak pointers from entrypoints to must-read support files83- bloated startup context or plugin grouping that should be on demand84- hooks or extensions that hide errors, block safe work, or run risky commands85- missing validation for config that produces skills, agents, hooks, or packages8687## Output8889Use optional finding tags such as `routing/thin-router`,90`context/weak-pointer`, or `invocation/over-model-invoked` when they sharpen the91issue.9293```markdown94## Config Audit9596Scope: <platforms/files>97Mode: review-only | fix-approved98Sources: <local files and docs checked>99Confidence: high | medium | low100101### Summary102103- Files reviewed: N104- Generated files skipped: N105- Main risk: <one sentence>106107### Critical108109- `path:line` — <category[/subtype]>: <issue>. Evidence: <fact>. Fix: <action>.110111### Important112113- `path:line` — <category[/subtype]>: <issue>. Evidence: <fact>. Fix: <action>.114115### Suggested116117- `path:line` — <category[/subtype]>: <issue>. Evidence: <fact>. Fix: <action>.118119### Working Well120121- <config that should stay as-is>122123### Verification124125- <command run or recommended>126```127128Omit empty severity sections. If no findings are confirmed, say `No confirmed129findings.`130131## Failure handling132133- Ambiguous target: ask one scoped question before auditing.134- Missing official docs: use local evidence, lower confidence, and report the gap.135- Generated file target: report the source path and regeneration command instead of editing it.136- Secrets or private data: do not quote secret values; identify only the path and key name when needed.137- Validation failure after a fix: revert the change unless the user asks to keep it, then report the exact error.