← Back to Blog

September 13, 2026 · By JayyRedd

Your Codex Setup Is Holding GPT-6 Astra Back: The Cleanup Checklist

📺 Watch the full breakdown: this page is its sourced companion. · 📄 The source: Rethinking skills and prompts for GPT-6 Astra, OpenAI Developers, so you can check me on any of it. · 🧭 New to Astra? Start with GPT-6 Astra on Plus.

If you've been using Codex for a while, you've got a pile of skills, an AGENTS.md file, and saved task prompts full of "always do this first" lines. Those lines helped older models. According to OpenAI, on GPT-6 Astra they can quietly hold the work back.

That isn't my hot take. On September 11, 2026, OpenAI Developers published Rethinking skills and prompts for GPT-6 Astra by Eric Provencher, who works on the Codex developer experience. Their tweet boils it down to one audit and three rules:

  • Audit your skills, AGENTS.md, and task prompts.
  • Rule 1: make skill triggers specific.
  • Rule 2: load guidance only when it's relevant.
  • Rule 3: define what done looks like.

People noticed. As of September 13, OpenAI's post had more bookmarks (18.3K) than likes (11.3K). Eric's original version on X, posted a week earlier on September 4, had the same pattern. People are saving it to go fix their setup.

This page is the long form of the video. Direct quotes are OpenAI's. Anything marked my take is mine.

First, a disclosure

The presenter in the video version is my digital avatar, not me on camera. The research, the script and the opinions are mine. This is commentary on OpenAI's published guidance; I'm not affiliated with OpenAI.

The core idea

Astra already knows what to read and when to test. What it needs from you is fewer rules and a clear finish line.

OpenAI's own model guidance puts it plainly: Astra "can be more sensitive to instructions contained in skills and other files, such as AGENTS.md," and OpenAI "strongly recommend[s] auditing" them. So a leftover line isn't just wasted context. It can change what the model decides to do.

Rule 1: Make skill triggers specific

A skill is a folder with a SKILL.md file, with a name and description at the top, plus optional scripts and reference docs.

Here's the part most people miss. Codex doesn't read every skill up front. It shows the model a list of names and descriptions so it can pick one. That list has a budget. Per the Codex docs, it uses at most 2% of the model's context window, or 8,000 characters when the window is unknown.

Install too many skills with long descriptions and Codex starts shortening the descriptions to fit. Keep going and the docs say it may drop some skills from the list entirely. At that point the model is choosing between skills it can barely see.

The second problem is descriptions that claim too much. OpenAI's post says they "over-emphasize when skills should be used." Eric's original post on X called it too much "pick me" energy.

OpenAI's example:

Skill description
❌ 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 bad one fires any time the model touches a database. The good one fires when there's actually a migration.

How to write the description:

  1. Answer two questions: what is this, and when should I pick it.
  2. Front-load the trigger words. The Codex docs say to put the key use case first "so a host can still match the skill if descriptions are shortened."
  3. For a skill you only want when you ask for it, the skill metadata supports allow_implicit_invocation: false. It then runs only when you call it by name and stops competing with everything else.

Rule 2: Load guidance only when it's relevant

Every skill the model reads costs context. OpenAI says reading a skill brings you "closer to compaction" and can introduce guidance that doesn't apply to the task.

Make the root file a router, not a manual

If one skill covers several workflows, OpenAI's advice is to "make the root document a minimal router that points to supporting docs and scripts." Something like this (my illustration, not OpenAI's):

# postgres-workflows
- Adding or changing a migration → read references/migrations.md
- Preparing a rollout → run scripts/rollout.sh

Give Astra enough to know where to look, without forcing it to read everything first.

Stop writing recipes

A lot of skills read like itineraries: step one, run exactly this; step two, exactly that. That used to help. OpenAI says models have gotten much better with nuance and ambiguity, so overly specific guidance "can now hinder results where it previously helped."

Skills in a shared repo also get used by other people's agents, on other models. OpenAI's point: guidance that helps Sol or Luna may over-constrain Astra. Write for the models that will actually read the file.

AGENTS.md runs on every task

AGENTS.md matters even more, because it applies every time the model works in your repo.

A detail from the Codex AGENTS.md docs: Codex combines your AGENTS.md files from the repo root down to the folder you're working in, and stops adding files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default. My take: a bloated root file can use up that budget before your more specific files ever load.

OpenAI's example:

AGENTS.md line
❌ Bad Before every edit, read architecture.md, database.md, and deployment.md.
✅ Good Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.

Think about the bad version on a typo fix: a full tour of your docs to change one letter. OpenAI calls reading files before every edit "a great way to burn context and slow work down." Pointing to docs is still good. Do it in context, and keep the docs updated.

Tests

Older models needed a nudge to run tests. OpenAI says Astra does that on its own, so the old "always run the tests" line can lead to unnecessary testing. The model guidance adds that on smaller tasks this "can result in broader tests than the task requires."

The one line worth adding

Here's the one place OpenAI suggests adding language. Astra can be tentative, so you can give it permission to keep going on a workflow you know is safe. OpenAI's example for AGENTS.md:

The local tests use disposable fixtures and have no production access. Run them, fix failures caused by the requested change, and rerun affected tests without asking for approval at each step.

That isn't another rule. It takes the handbrake off on a road you already know is safe.

Boundaries: keep red lines, rethink blanket "ask first"

If an older model ever did something without asking, you probably added strong language: ask first, do not proceed. OpenAI calls Astra its most aligned model, one that "will not perform tasks unless it knows it is safe," and warns it "could take it too seriously and may stop work where you'd actually be happy for it to continue."

So reread your boundaries.

Keep the real red lines. OpenAI's model guidance says approval should be the final step before things like deploying a change, writing to an external application, merging a PR, or publishing a site, and autonomy should stop at anything "clearly destructive or irreversible." My take: add anything that touches payments or secrets.

Rethink the blanket version. The same guidance says "you don't need user permission for reversible tasks, read-only actions, reviews or fixes," and recommends prompting the model "to ask for approval only after preparing a concrete, reviewable result."

Rule 3: Define what done looks like

If you're coming from GPT-5.6 Sol, which would take a request and run with it for a long time, OpenAI says Astra "can feel more tentative about when to stop." It may reach a first implementation and come back for your review while there's still work to do.

There are two reasons:

  1. It's built to check in. The model guidance says Astra is "more likely to ask the user a question when additional input could materially change the result."
  2. Your prompt may be teaching it to stop. OpenAI: "A requirement to stop for review after the first implementation will pull the model toward an earlier stopping point, so check whether that's a decision you actually need to make."

The fix is to define done before the work starts. OpenAI's version: if the task includes getting the implementation running, inspecting the result, and fixing what fails, make that part of the request.

My additions, as examples:

  • The failing test is green.
  • Anything this change broke is fixed.
  • Don't hand it back after the first compile.

If you want it to explore past version one, OpenAI says to say what you want explored and where it should stop. Say nothing, and you tend to get politely half-finished work.

The audit: let Astra do it

You don't have to comb through every file by hand. OpenAI's closing advice is to ask Astra to audit your setup against the article.

Here's the audit prompt I'd paste. This one is mine, built from the rules above:

Audit my Codex setup for GPT-6 Astra. Read every SKILL.md, every AGENTS.md,
and my saved task prompts. Report first — don't edit anything yet.

Flag:
1. Skill descriptions that are longer than needed, bury the trigger words,
   or would fire on unrelated work.
2. Multi-workflow skills whose root SKILL.md is a manual instead of a router.
3. Step-by-step recipes that could be one principle.
4. AGENTS.md lines that force reading docs or running tests on every task.
5. "Ask first" / "do not proceed" language that isn't protecting a real red line
   (deploys, external writes, merges, publishing, destructive actions,
   payments, secrets).
6. Any instruction to stop for review after a first implementation.

For each finding: file path, the exact line, and a shorter replacement or a
deletion.

And pair it with this line from OpenAI's model guidance, so Astra tells you exactly which old rule is slowing it down:

If a skill causes you to ask for permission or confirmation, pause, leave requested work unfinished, or diverge from the user's intent, name and link to the exact SKILL.md file you read, quote the relevant instruction, and briefly explain how it applies.

Your old rules start reporting themselves.

If you're tired of rebuilding your setup every time a new model drops, I get it. But look at what this cleanup mostly is: deleting.

The checklist

  1. Specific skill triggers, with the trigger words first.
  2. The main skill file is a router, not a manual.
  3. Principles, not recipes.
  4. Point to docs in context in AGENTS.md, not a mandatory reading list.
  5. Keep real red lines, and define done before the work starts.

Sources

Engagement figures were checked on September 13, 2026 and will have moved since.

Want to work through this with other people building with AI? That's what the AI Creators Roundtable is for: a community of creators and solo business owners trading real workflows, prompts, and wins.