---
name: agent-config-maintenance
description: Refactor Codex configuration files and Agent Skills by splitting concerns, deduplicating instructions, and reorganizing guidance across AGENTS.md, project docs, and skills. Use when asked to clean up AGENTS.md, move instructions into skill bundles, or standardize agent setup rules.
---

# Agent Config Maintenance

## Scope

- Target files: `AGENTS.md`, project-doc sections, `skills/*/SKILL.md`, and any references under `skills/*/references/`.
- Focus on separation of concerns: global agent rules vs task-specific workflows.

## Workflow

1. Inventory instructions
   - Use `rg` to find duplicate or conflicting rules across AGENTS, project docs, and skills.
   - Note which rules are global constraints vs task-specific procedures.
2. Decide the split
   - Keep only global, always-on constraints in `AGENTS.md`.
   - Move task-specific procedures into the relevant skill `SKILL.md` or `references/`.
   - Remove duplicated bullets after moving.
3. Update skill metadata
   - Fill `SKILL.md` frontmatter with `name` and a trigger-ready `description`.
   - Keep the description explicit about when to use the skill.
4. Write the skill body
   - Use imperative form.
   - Keep core workflow in `SKILL.md`.
   - Move large checklists or detailed examples into `references/` and link them.
5. Validate consistency
   - Ensure AGENTS and skills do not contradict each other.
   - Verify naming conventions (lowercase + hyphen).
   - Confirm only necessary files exist; avoid extra docs.

## Quality gates

- Keep `SKILL.md` under 500 lines.
- Avoid duplication between `SKILL.md` and any reference files.
- If adding scripts, run them once to validate behavior.