Rethinking Skills and AGENTS.md for GPT-6 Astra: A Practical Guide

OpenAI's Codex developer experience team just told its own users to stop over-engineering their prompts. On September 5, 2026, Eric Provencher — who works on Codex DX and is also known for building repoprompt — published "Rethinking skills and prompts for GPT-6 Astra", a practitioner's field guide to the instructions that quietly stopped working the moment GPT-6 Astra shipped on September 3, 2026.

His core claim: if you've been running coding agents for the last year, your Skills, AGENTS.md files, and task prompts have accumulated bloat — handholding that a weaker model needed and a stronger one does not. "With each release, it's been worth revisiting those assumptions," Provencher writes, "but with GPT-6 Astra, that's more important than ever." That's not a minor tuning note. It's a call to re-audit every piece of standing instruction you've written for an agent, because the model reading it changed underneath you.

This guide turns his post into four checklists you can run today: Skill files, AGENTS.md, decision boundaries, and completion criteria. Each one gets a before/after example you can copy directly into your repo, and a note on how the same idea maps onto Claude Code's equivalents — CLAUDE.md, Agent Skills, and subagent prompts.

TL;DR — What changed and what to do about it

1. Skill files: shorter descriptions, not more skills

Provencher's first target is the most common failure mode: downloading too many skills into a project. "Many people default to downloading a lot of skills into their projects — that's a mistake," he writes.

Here's the mechanism. A Skill file is a markdown prompt, sometimes bundled with scripts, that guides a specific workflow. But the model doesn't read every skill's full body up front — it reads each skill's name and description so it knows when to reach for the rest. That's progressive disclosure: the root document should be a minimal router, not a dumped-in manual.

The problem compounds with scale. Once you've installed enough skills, Codex starts shortening descriptions to fit context — meaning the model sees less of each one, making selection harder rather than easier. Worse, overlapping or "pick me" descriptions cause the model to load instructions that don't actually help the current task. A description that says a skill is for "anything related to a database" gets triggered on unrelated work; a description scoped to "database schema migrations specifically" doesn't.

Codex's own $skill-creator skill was recently updated to push back on this pattern, per Provencher, with three concrete fixes:

1. Descriptions should be as short as possible while making clear when to use them. Scope to the specific trigger, not the general category.
2. Progressive disclosure is the marker of a useful skill. The root file should point to supporting docs/scripts, not contain everything — reading a skill costs context and moves the conversation closer to compaction.
3. Overly specific, itinerary-style guidance can now hinder results. Models have gotten better at handling nuance and ambiguity; step-by-step recipes that used to help can now constrain a model that would have found a better path on its own.

There's a fourth wrinkle specific to team repos: skills also guide other contributors' agents, which may run different models. Guidance tuned for one model can overconstrain another. If your repo's skills get used by teammates running GPT-5.6 Sol, Claude, and GPT-6 Astra side by side, write for the least-scaffolding-needed case and let more capable models skip what they don't need.

Before / after: a skill description

# BAD — vague trigger, "pick me" energy, invites misuse
---
name: database-helper
description: >
  Use this skill whenever you're working with databases, schemas, queries,
  migrations, ORMs, or anything data-related in this project. Covers
  connection setup, query optimization, index tuning, and more.
---

# GOOD — scoped to one specific trigger, nothing else
---
name: db-migration
description: >
  Use when writing or reviewing a database schema migration file in this
  repo (not for general queries or ORM usage).
---

The bad version fires on any database-adjacent task and, stacked next to a few other verbose skills, gets truncated by Codex until the model can barely tell what it's for. The good version fires exactly once, for exactly the task it names.

This is the same discipline explainx.ai has covered for Agent Skills generally and for building your own SKILL.md files — the anatomy doesn't change model to model, but the tolerance for bloat inside it does.

2. AGENTS.md: revisit every standing instruction

AGENTS.md applies on every task in the repo, which makes its bloat the most expensive kind — you pay for it on the typo fix and the multi-file refactor alike. Provencher's instruction is blunt: "revisit each instruction and ask whether the task still needs it."

Three specific patterns he flags as now-obsolete:

• Requiring a full repo map or doc stack before every edit. Reasonable scaffolding for a weaker model, excessive for a one-line typo fix. "GPT-6 Astra can work out what it needs without being pushed to review the whole project every time."
• Forcing file reads before every edit. This burns context and slows work. Pointing to docs contextually — "read docs/auth.md before touching auth code" — is still useful; a blanket "read these five files before any change" rule is not.
• Encouraging the model to run tests and check its own work. Previous models needed this nudge. GPT-6 Astra does it unprompted, so the same instruction now just adds unnecessary testing overhead on tasks that don't need it.

The AGENTS.md permission-grant pattern is the piece worth adopting wholesale. Instead of restricting the model with defensive rules, grant explicit permission for a specific, known-safe workflow:

Before / after: an AGENTS.md instruction

<!-- BAD — blanket rule written for a weaker, more literal-minded model -->
Before making any change, read the full architecture doc, the API reference,
and the testing guide. After every change, run the full test suite and wait
for explicit approval before continuing to the next step.

<!-- GOOD — a scoped permission grant for a known-safe workflow -->
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.

The bad version forces a full-suite run and an approval pause on every change, including changes that don't touch tests at all. The good version names the exact workflow (local tests, disposable fixtures, no prod access), grants blanket permission within that boundary, and removes the per-step approval loop — freeing the model to actually finish the task instead of pinging back after each command.

This is the direct equivalent of what explainx.ai has written about CLAUDE.md as persistent memory and the three-layer CLAUDE.md vs SKILL.md vs MCP stack: CLAUDE.md is exactly as global as AGENTS.md, which means it deserves the same "does this still earn its place" audit every time you upgrade to a newer Claude model.

3. Decision boundaries: your "ask first" rules may be stopping the model too early

This is the section most teams will get wrong by defaulting to caution. Provencher's warning: "pay careful attention to how you describe boundaries."

If an older model acted without permission and you responded by adding strong "ask first" language, that instinct made sense at the time — and it can still be useful as a hard safety rail. But GPT-6 Astra "has much better judgment and should be treated as such — it takes your boundaries seriously and may stop work where you'd actually be happy for it to continue."

In other words: strict boundaries written to correct a less capable model's mistakes don't just fail to help a more capable model — they actively cost you throughput, because the model respects the boundary and halts exactly where you'd have preferred it kept going.

The fix isn't removing boundaries. It's re-scoping them to what actually still needs a human in the loop — production deploys, destructive migrations, external API calls with billing consequences — and lifting the ones that were compensating for a weaker model's poor judgment on low-stakes decisions.

This is the same shift Andrew Ng has been describing on the human side of the equation. His AI Engineering Skills Map names "using coding agents" and "shaping the build" as two of the four skills every developer needs in 2026 — and both are fundamentally about setting the right boundary once rather than approving every step. As models get more capable, the job shifts from micromanaging execution to defining scope and completion criteria up front, then getting out of the way.

4. Persistence and completion criteria: define "done" before you start

The last area is the one most likely to surprise teams coming from GPT-5.6 Sol. Provencher: "if you're used to GPT-5.6 Sol continuing for long stretches, GPT-6 Astra can feel more tentative about when to stop — it may reach a first implementation and come back for review while there's still work to do."

That's not a regression in capability — it's a different default stopping point. Sol erred toward continuing; Astra errs toward pausing for review. If your prompts implicitly relied on the model "just finishing," they now need to say what finishing means.

Provencher's guidance: "Define completion before starting: if the task includes getting the implementation running, inspecting the result, and fixing what fails, make that explicit as part of the request, or a requirement to stop for review after the first implementation will pull the model toward an earlier stopping point. If you want it to keep exploring beyond a first pass, say what to explore and where to stop."

Before / after: a task prompt

BAD — vague completion, relies on the model's judgment for "done"
Fix the failing checkout tests.

GOOD — explicit completion criteria, explicit stopping point
Fix the failing checkout tests. Completion means: the change is made, the
affected test file runs green locally, and any newly-broken tests elsewhere
in the suite are fixed too. Stop and report back once all of that is true —
do not stop after the first passing test if others are still red.

The bad prompt lets GPT-6 Astra's default tentativeness decide when "fixed" means fixed — which, per Provencher, is often earlier than you'd like. The good prompt states the actual finish line, so the model has no reason to pause before reaching it.

This is the same territory explainx.ai covers under loop engineering: a loop needs an explicit stop condition or it either runs forever or stops too soon. Completion criteria in a single task prompt are the same idea scaled down to one turn instead of a scheduled run.

How this maps onto Claude Code

Provencher is writing for Codex and GPT-6 Astra specifically, but the pattern he's describing — a new, more capable model needs less scaffolding, not more — isn't OpenAI-specific. It's the same discipline explainx.ai has documented for the Claude Code equivalents:

The practical takeaway is the same regardless of which harness or model you're running: every model upgrade — Astra, Fable 5.1, the next Claude release — is a prompt to re-read your standing instructions and ask, one at a time, whether the model in front of you still needs them. Provencher's closing line makes the point directly: "a new model is a good opportunity to clean house — audit your skills/AGENTS.md/prompts based on this, then go build something you wouldn't have attempted before."

The audit checklist

Run this against your own repo before your next GPT-6 Astra or Claude session:

• Skills: Are any descriptions doing more than naming the specific trigger? Shorten them.
• Skills: Is the root SKILL.md a router, or does it dump the whole workflow inline? Split it.
• Skills: Do you have overlapping skills that could both fire on the same task? Consolidate or narrow.
• AGENTS.md / CLAUDE.md: Does it force a doc read or repo map before every edit, regardless of task size? Remove the blanket rule.
• AGENTS.md / CLAUDE.md: Does it still nudge the model to run tests it now runs unprompted? Delete the nudge.
• AGENTS.md / CLAUDE.md: Do you grant explicit permission for at least one known-safe, repeatable workflow (tests, linting, local builds)?
• Decision boundaries: Are any "ask first" rules there because an older model misbehaved, not because the action is actually high-stakes?
• Task prompts: Does every multi-step prompt state what "done" means, including whether the model should run and inspect its own output?

None of this requires new tooling — it's a read-through of files you already have, with one honest question per line: does the model I'm running today still need this?

Provencher's post and the Codex $skill-creator update it references reflect guidance current as of September 5, 2026. Skill and AGENTS.md conventions continue to evolve alongside model releases — revisit this checklist with your next model upgrade rather than treating it as a one-time fix.

Related reading

• GPT-6 Astra launch: every benchmark, price, and rollout detail
• What are Agent Skills? A complete guide
• Agent markdown files: the complete guide
• CLAUDE.md vs SKILL.md vs MCP: the modern agent stack
• What is CLAUDE.md? Persistent memory in Claude Code
• Andrew Ng's AI Engineering Skills Map: the 4 skills that matter
• Loop engineering for coding agents: the Claude Code guide
• HarnessDev: can LLMs build and evolve their own agent harness?