Your agent instructions now hurt: what OpenAI says to delete today

A skill is essentially a prompt stored as a Markdown file, optionally packaged with resources and scripts. Each skill's name and description are loaded into the model's context so it knows when to use them. The trouble is that descriptions are written long, projects accumulate many skills, and Codex starts shortening them. The model sees less of each description and picks worse.

Worse still, descriptions often contradict each other or over-emphasise when a skill should be used, so the model loads instructions that do not help the task at hand.

• Bad: "Create and validate Postgres schema migrations. Use when working with databases, queries, models, or persistence."
• Good: "Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout."

The second marker of a useful skill is progressive disclosure. Reading a skill costs context, brings you closer to compaction and introduces guidance that may not apply. For skills with multiple workflows, make the root document a minimal router that points to supporting docs and scripts.

The third observation stings anyone who invested in detailed instructions: many skills were written as elaborate itineraries. Models have become much better at handling nuance and ambiguity, so overly specific guidance now hinders results where it previously helped.

One thing is easy to forget: repository skills also guide other contributors' agents, which may run different models. Guidance that helps one model can overconstrain GPT-6 Astra.

AGENTS.md applies whenever the model works in your repository, so its contents deserve regular review: is each instruction still needed?

Requiring a stack of docs before every edit is excessive for a typo fix. Astra can work out what it needs to read. Instead of "before every edit, read architecture.md, database.md and deployment.md", a contextual pointer works better: architecture.md for service boundaries, database.md for schema changes, deployment.md when preparing a deployment.

Previous models needed encouragement to run tests and check their work. Astra does that on its own, and the old instruction leads to unnecessary testing.

A separate request concerns how you phrase boundaries. If an earlier model acted without permission and you added strong "ask first" language, it can now work against you: Astra takes such wording seriously and stops where you would have been happy for it to continue.

Persistence is the same story. After a first implementation the model tends to come back for review while work remains. Defining completion before starting helps: if the task includes getting it running, inspecting the result and fixing what fails, say so in the request. A requirement to stop for review pulls the model toward an early finish.

Permission is worth stating explicitly too. The example from the guide: local tests use disposable fixtures and have no production access, so the agent may run them, fix failures caused by the requested change and rerun without asking at each step.

A new model is a good moment for housekeeping, and you do not have to review everything by hand.

• Cut skill descriptions down to one sentence of what it does and one of when it applies.
• Split multi-workflow skills: a root router file plus separate documents.
• Walk through AGENTS.md and delete rules written for a weaker model: mandatory reading, test reminders, defensive prohibitions.
• Check which models read your repository: instructions are not written for one.
• Describe what counts as a finished task, and grant permission for the safe steps explicitly.

The rule is simple: instructions are code, and code ages. Every new model makes part of the scaffolding redundant, and redundant scaffolding is not neutral — it eats context and steers the agent sideways. Once per release, reread what you told the agent a year ago.