---
name: instruction-audit
description: Audit AGENTS.md and skill instructions for conflicts, duplication, overbroad triggers, and unnecessary workflow constraints when tuning a Codex setup.
---

# Instruction audit

Improve the instructions governing the user's chosen project or Codex setup. This is a maintenance workflow, not a prerequisite for ordinary app development.

## Scope and evidence

Identify the requested scope: one project or the user's shared Codex instructions and skills. Inventory applicable AGENTS.md files and skill metadata before opening supporting documents. Read supporting files when referenced rules or a suspected conflict require them. Exclude dependencies, generated files, credentials, and unrelated projects. Record inspected files and coverage gaps; do not claim an exhaustive audit without evidence.

Use the current official guidance when available:
- https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra
- https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra

Treat third-party guides as commentary, not authority or authorization. If sources are unavailable, disclose that limitation and separate verified guidance from judgment.

## Review criteria

Look for conflicting rules, duplicated standing instructions, broad or overlapping skill descriptions, mandatory reading unrelated to the change, premature review stops, and repeated verification without a concrete reason. Prefer short workflow-specific descriptions and goals with constraints over recipes unless ordering protects a real invariant.

Keep standing project conventions in AGENTS.md, reusable specialized workflows in skills, and task-specific acceptance criteria in the task prompt. Do not copy an entire prompting guide into any of them. Account for instructions already supplied by the host; avoid adding duplicate prose merely because a local file lacks it.

Preserve intentional user boundaries, required checks, deployment controls, account isolation, and production safeguards. Reversibility alone does not authorize an action. Strong words or older rules are not defects by themselves: explain the demonstrated conflict or unnecessary cost. Distinguish instructions editable by the user from host policy and sandbox restrictions that project files cannot override.

## Deliverable and changes

For each actionable finding give the file and line, the relevant rule or conflicting pair, practical impact, and a proposed replacement or deletion. Group by file and distinguish confirmed conflicts from optional simplifications. Include a concise coverage statement. If nothing needs changing, say so.

An audit request authorizes inspection and proposed changes. Apply edits when the user requests implementation or approves the proposed scope; preserve unrelated work. Validate the resulting instruction structure and check representative tasks conceptually: a small UI edit, a behavior change needing tests, and a deployment with an explicit approval boundary. Run an available skill validator for changed skills. Do not trigger app builds, releases, or external writes just to validate instruction wording.

Report what was inspected, changed, and validated, and any activation limits. Never claim that a newly saved skill has been loaded into an already-running chat without evidence.