给 Agent.MD配置做一次大扫除：GPT-6 Astra 官方 Skills 与 AGENTS.md 改造实操指南
模型变强之后，仓库里那堆当年为了兜住弱模型写下的规则，正在反过来拖慢它。这份指南把 OpenAI Developers 的建议拆成四步可照做的改造：收窄 skill 描述、把 AGENTS.md 从强制通读改成按需索引、给安全环境明确放权、把完成标准写进任务 prompt——每步都附「改对后怎么确认」。
在过去很长一段时间里，为了让 Codex 等 coding agent 稳定输出符合预期的代码，开发者习惯在仓库里堆积大量引导规则：巨细靡遗的操作菜谱、修改前必须读完全部架构文档的死规定，以及每走一步都必须暂停确认的防御性指令。
随着底层模型升级到 GPT-6 Astra，这套曾经行之有效的配置反而成了负资产。旧配置从助力变成负担，核心原因在于模型能力的代际位移：Astra 的理解力、安全对齐与上下文感知大幅提升，过去那种「保姆式脚手架」不仅大量挤占上下文空间，还会引发规则冲突、误触无关流程，甚至让具备高度安全意识的模型陷入不必要的停滞。
这份指南将带你系统清理仓库中的历史配置。你可以直接对照自己的项目，从 skills、AGENTS.md、权限边界到任务 prompt，逐步完成改造。
为什么模型变强了，旧配置反而成了累赘？
在动手修改具体文件之前，需要先理解官方提出这一系列重构建议的核心原则：从保姆式约束转向自主判断与按需路由。
过去一年的典型配置存在三个在强模型下被放大的缺陷：
第一是上下文污染与截断风险。许多团队给项目配置了数十个 skills，每个 skill 都写了很长的描述。当技能总数过多时，Codex 会强行缩短展示给模型的描述摘要。模型看到的描述信息残缺不全，加上各描述词常有重叠，往往会导致误选无关技能；而一旦加载错误的大型技能文件，又会提早触发上下文压缩（compaction），挤掉真正有用的开发上下文。
第二是死板步骤对高阶推理的限制。老模型容易丢三落四，需要按部就班的菜谱（recipes）指导；但 Astra 对模糊语义与复杂业务逻辑的理解力远超以往，过于详尽的指令步骤不仅显得多余，反而限制了模型的解题空间。
第三是对齐特性导致的过度保守。Astra 是目前对齐程度最高、判断力更强的模型，在未确认操作安全前通常不会冒进。如果仓库的规则文件里依然残留着此前为了约束旧模型而写下的严厉警告（例如「未经批准不得执行任何操作」），Astra 会极度严格地执行它，导致其在完全安全的本地测试或常规修改中动不动就停下来请求确认。
理解了这些变化，改造思路就十分清晰：把入口做轻、把索取做细、把权限说透、把目标闭环。
第一步：瘦身与重构 skills
先弄清楚要改的是什么：skill 本质上就是存成 Markdown 文件的提示词，可以连同资源和脚本一起打包，最适合用来指导某一条具体工作流、或在使用某些特定应用时提供指引。
排查仓库内的技能定义文件。官方近期已经更新了 $skill-creator 的内置指引，核心要求就是给技能全面瘦身。
精简触发描述：skill 的名称与描述是常驻在模型上下文中的索引。描述必须尽可能短，且只明确规定在什么场景下才需要调用。切忌为了「防漏」而把关联模块的所有词汇都堆在描述里。
原文 Bad 写法（附中文对照）：
Create and validate Postgres schema migrations. Use when working with databases, queries, models, or persistence.
创建并校验 Postgres 数据库结构迁移。在处理数据库、查询、模型或持久化相关工作时使用。
原文 Good 写法（附中文对照）：
Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout.
创建并校验 Postgres 数据库结构迁移。在新增或修改一个 migration、或审查其上线时使用。
说明：Bad 写法把写查询、改模型、做持久化全当成了触发词，结果只要 Agent 触碰到数据库相关代码，就会错误地把整个 migration 技能调入上下文；Good 写法将范围精准锁定在「新增/修改 migration 或审查其上线」，只有在真正处理迁移时才会触发。
描述写得越长，模型看到的越少
你在 skill 里写的描述
斜纹那段 = 超出系统给描述留的那点预算
模型实际读到的描述
- 三条描述都停在「Use when…」刚开口的地方，真正划定边界的那半句全没了。
- 模型只能靠前半句猜，于是写个普通查询也可能把整个 migration 技能拉进上下文。
- 被误加载的技能继续吃 token，把还没用上的开发上下文提前挤进压缩。
所以官方的第一条建议不是「少写技能」，而是把描述压到一两句，且只说何时调用——短到不触发裁剪，边界才留得住。
践行渐进式披露（Progressive Disclosure）：阅读技能内容同样消耗上下文。对于包含多个流程的复杂技能，根文档应当只充当极简的「路由器（Router）」，指引模型按需去寻找二级文档或具体脚本，绝不能把所有操作步骤一股脑塞在根文件里。
精简操作菜谱与考虑多模型协作：删掉一步步保姆式的详尽指引，让 Astra 自由发挥理解力。但需要留意团队协作情况：如果仓库里还有其他协作者的 Agent 在运行 GPT-5.6 Sol 或 Luna 等旧模型，为老模型保留的强约束可能会过度束缚 Astra，更新公共技能时需权衡协作者的模型构成。
改对后的确认方式：检查 Codex 加载的 skills 列表，确认每条描述都能完整显示、未被引擎裁剪；在日常编写常规数据库查询或业务逻辑时，观察 Agent 不会再误触发并加载迁移技能。
第二步：重写 AGENTS.md 的文档索引
打开项目根目录下的 AGENTS.md。这个文件是 Agent 在仓库内工作时的全局常驻指引，必须逐条审查其中每一项要求的必要性。
从全局强制必读转为按需索取：旧配置最常见的做法是要求 Agent 在动手前通读一堆规范文档，这在修一个错别字或调整常量时属于极其严重的资源浪费。Astra 完全有能力自行判断当前任务需要查阅哪些背景。
原文 Bad 写法（附中文对照）：
Before every edit, read architecture.md, database.md, and deployment.md.
每次编辑前，先读完 architecture.md、database.md 和 deployment.md。
原文 Good 写法（附中文对照）：
Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.
涉及服务边界查 architecture.md，改表结构查 database.md，准备发布时查 deployment.md。
说明：Bad 写法要求在每次编辑前通读架构、数据库和部署三大文档，既严重烧 token，又极大拖慢响应速度；Good 写法将文档改为场景化索引，只在涉及服务边界、表结构调整或准备发布时才引导查阅对应文件。同时务必保证索引所指向的文档内容是最新维护的。
清理多余的测试督促：旧模型经常写完代码就交差，以往的 AGENTS.md 会强行要求「修改后必须执行测试并检查产出」。Astra 在这方面具备很强的自主性，会主动进行自测，继续保留这种督促会导致它发起不必要的重复测试。
改对后的确认方式：派发一个微小修改任务（例如修改某处的文档注释），观察交互日志，确认 Agent 直奔目标文件动手，不再盲目加载全套架构文档，也不再反复刷全量测试。
第三步：重设权限边界与本地测试授权
审查 AGENTS.md 及全局规则中关于「权限与审批」的条款，解除过时的安全束缚。
修正过激的防线语言：以前为防止旧模型擅自做主，开发者常写下「做任何改动前必须征求人工许可」等强硬指令。面对判断力更强的 Astra，这种防御性用语会导致它过于拘谨，在完全可以安全推进的环节反复暂停。应该清理掉那些因缺乏信任而设的无差别拦截。
给安全环境明确放权：Astra 工作很周全，但在判断推进步长时偏谨慎，需要适当给它继续前进的许可。对于本地测试这种没有任何生产破坏风险的安全场景，直接在 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.
本地测试使用一次性夹具且无法访问生产环境。运行测试，修复由本次修改引发的失败，并重新运行受影响的测试，无需在每一步都请求批准。
说明：这段配置清晰交代了两件事——本地测试无生产风险；明确要求模型自动跑测试、自查报错、修复代码并复测，中途不必每走一步都弹窗请示。
改对后的确认方式：发起一次会导致单元测试报错的代码修改，观察 Agent 能否自主完成「修改代码 -> 跑测试发现报错 -> 自行修补 -> 重新跑测试通过」的完整闭环，中途不再停下来等待批准。
第四步：调整任务 prompt，明确完成定义
除了静态的规则文件，日常下发任务时的 prompt 表达习惯也需要同步调整。
把完成标准（Definition of Done）前置：很多开发者习惯了 GPT-5.6 Sol 接到需求后单向跑很长链路的风格，转用 GPT-6 Astra 后可能会觉得它变保守了——往往写完第一版代码就停下来，等用户审阅后再继续。
如果你的任务本身就包含「把代码跑起来、检查实际输出、修复运行期错误」，就必须在发起任务的 prompt 里明确将它们定义为完成条件。不要预设「写完初稿停下来等我确认」，除非这个决策节点确实必须由人类来定夺；多余的中间停顿要求会把模型推向过早的终止状态。
若需要进行探索性尝试，不要只发一句含糊的「多试试不同方案」，明确告知期望探索的具体方向，以及探索到什么边界就可以收敛停下。
改对后的确认方式：提交需求后，Astra 不再只扔给你一段未验证的初版代码就原地待命，而是能够端到端完成部署或测试验证，并交付完整的检查结果。
快捷落地：让 GPT-6 Astra 自助审计仓库
改造现有的配置文件不需要你全程手动翻找。最快的方式是让 GPT-6 Astra 亲自来做一次合规体检。
仓库自查：勾出你中招的项，下面的审计 prompt 会跟着收窄
一条都不勾也能用——默认就是六项全查的完整版。勾选只是把范围缩小到你真正要改的地方。
请依据 GPT-6 Astra 的配置重构原则，审计本仓库的 skills、AGENTS.md 和常用任务 prompt。
重点检查以下几项：
1. 审查每一条 skill 描述：指出过长或触发条件过宽的，改写成一两句话、只说明「什么时候该调用」，不罗列能力。
2. 对流程复杂的 skill，提出「根文件只留极简路由、子文档与脚本分离、按需读取」的拆分方案。
3. 找出菜谱式的逐步指令，判断哪些可以交给你自行推理，哪些确有必要保留。
4. 移除 AGENTS.md 中无差别的强制通读要求，改成按职责标注的文档索引（什么情况查什么）。
5. 清理重复的测试督促；把无差别拦截收窄到真正的高危操作，并为隔离的本地测试补一段「自动运行、修复报错、复测无需逐步批准」的授权。
6. 为常用任务 prompt 补上完成定义（跑起来、检查输出、修复报错直到通过），并去掉多余的「写完先停下确认」。
请先输出问题清单：文件路径、现状原文、建议改写，三列对照。我确认之后你再实际动手改。这段 prompt 刻意要求它先出清单、后动手——审计的价值在于你能看见它准备改什么。清单过一遍，确认无误再让它合入，整套配置资产就算焕新完成。
给 Agent.MD 配置做一次大扫除
在过去很长一段时间里，为了让 Codex 等 coding agent 稳定输出符合预期的代码，开发者习惯在仓库里堆积大量引导规则：巨细靡遗的操作菜谱、修改前必须读完全部架构文档的死规定，以及每走一步都必须暂停确认的防御性指令。
随着底层模型升级到 GPT-6 Astra，这套曾经行之有效的配置反而成了负资产。旧配置从助力变成负担，核心原因在于模型能力的代际位移：Astra 的理解力、安全对齐与上下文感知大幅提升，过去那种「保姆式脚手架」不仅大量挤占上下文空间，还会引发规则冲突、误触无关流程，甚至让具备高度安全意识的模型陷入不必要的停滞。
核心范式转移：从保姆式约束转向自主判断与按需路由
面对理解力、安全对齐与上下文感知大幅跃升的 GPT-6 Astra，重构的本质是解开枷锁，将控制逻辑从全局刚性防线转向轻量分发与端到端闭环。
- 入口冗余：Skill 描述堆满关联词防漏，常驻上下文迅速膨胀
- 全局必读：每次修改强行通读架构与规范，极度消耗 token
- 步骤微操：巨细靡遗的菜谱（recipes），强制每步按部就班
- 无差别拦截：禁止擅自推进，任何改动均需人工确认
- 把入口做轻：技能描述极简聚焦，按需渐进式披露二级文档
- 把索取做细：按需索取场景索引，不再进行全量文档泛读
- 把权限说透：明确授予安全环境（本地测试）连续执行权限
- 把目标闭环：前置完成标准（DoD），端到端自查自愈交付
第一步：瘦身与重构 skills
排查仓库内的技能定义文件。官方近期已经更新了 $skill-creator 的内置指引，核心要求就是给技能全面瘦身。Skill 名称与描述是常驻在模型上下文中的索引，必须尽可能短，且只明确规定在什么场景下才需要调用，切忌堆砌关联词。
Create and validate Postgres schema migrations. Use when working with databases, queries, models, or persistence.
Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout.
同时践行渐进式披露（Progressive Disclosure）：对于包含多个流程的复杂技能，根文档应当只充当极简的「路由器（Router）」，指引模型按需去寻找二级文档或具体脚本，绝不能把所有操作步骤一股脑塞在根文件里。
团队协作注意：如果仓库内仍有协作者使用 GPT-5.6 Sol 或 Luna 等老模型，删减强约束前需权衡多模型共存需求，避免旧模型失控。
第二步：重写 AGENTS.md 的文档索引
打开项目根目录下的 AGENTS.md。旧配置最常见的做法是要求 Agent 在动手前通读一堆规范文档，这在修一个错别字或调整常量时属于极其严重的资源浪费。Astra 完全有能力自行判断当前任务需要查阅哪些背景，必须从全局强制必读转为按需索取。
清理多余的测试督促：Astra 在编码完成后会主动进行自测。过去在 AGENTS.md 中强行写的「修改后必须执行测试并检查产出」，如今会导致它反复刷全量测试，应当果断剔除。
第三与第四步：权限明确放权与完成标准前置
Astra 工作很周全，但在判断推进步长时偏谨慎，需要适当给它继续前进的许可。如果规则里残留「做任何改动前必须征求人工许可」，它会在常规安全测试中不断停滞。解决办法是给安全环境明确放权：
在日常下发任务时，还要把完成标准（Definition of Done）前置：Astra 接到指令后往往写完第一版初稿就会停下来等待审阅。若任务本身包含验证与排错，务必在 Prompt 中直接定义终态，明确探索收敛边界，驱动其自主完成「修改 → 跑测报错 → 自行修补 → 验证通过」闭环。
无需全程人工翻找，直接向 Astra 下发体检指令。核心是要求它「先出清单、后动手」，人类工程师审阅通过后再统一合入改造：
Rethinking skills and prompts for GPT-6 Astra | OpenAI Developers
Revisit skill descriptions, AGENTS.md, and task prompts to avoid bloated context.
Coding agents have come a long way, and best practices are changing fast. With more capable models, what used to require a lot of handholding and scaffolding no longer does.
If you’ve been using agents like Codex for your projects over the last year, you’ve likely accumulated a lot of instructions as you worked to steer the models toward good outcomes. With each release, it’s been worth revisiting those assumptions, but with GPT-6 Astra, it’s more important than ever.
These instructions can take many forms: skills, AGENTS.md, and your task prompts are all shaping how the model gets work done.
Better skills
These instructions can be in the form of skills, which are essentially prompts stored as Markdown files that can also be packaged with resources and bundled scripts. Generally, they are most useful for guidance around a specific workflow, or when using certain apps.
People now default to packaging a lot of skills into their projects, and each skill comes with a name and description that are loaded into the model’s context so it knows when to use them. But many descriptions are far too long, and when you add too many skills, Codex starts shortening their descriptions to fit. The model ends up seeing less of each description, making it harder to know which skill to pick.
What’s worse is that descriptions can often contradict each other or over-emphasize when skills should be used, leading the model to load instructions that don’t actually help the task.
A common workflow to create skills is to use the $skill-creator skill. We recently updated its guidance to help mitigate many of the failure modes we’ve seen in practice.
First, skill descriptions should be as short as possible while making it clear when the model should use them:
Be clear about when it applies
Here, the bad skill description can push the model to use it anytime it touches anything related to a database, rather than only when it has to handle a migration.
Second, one of the key markers of a useful skill is progressive disclosure. Reading a skill takes up context, bringing you closer to compaction and introducing guidance that may not apply to the task. For skills with multiple workflows, make the root document a minimal router that points to supporting docs and scripts. Give the model enough guidance to know where to look without forcing it to read things that don’t matter in the moment.
Third, many skills were written as elaborate itineraries or recipes. Models have gotten much better at understanding nuance and ambiguity, so overly specific guidance can now hinder results where it previously helped.
Repository skills also guide other contributors’ agents, which may use different models. Guidance that helps Sol or Luna may overconstrain GPT-6 Astra, so consider which models will use the instructions you leave behind.
Up-to-date AGENTS.md
Because AGENTS.md applies whenever the model works in your repository, you should frequently revisit each instruction and ask yourself whether it’s still needed.
Requiring a stack of docs or a full repo map before every edit is excessive for a typo fix. GPT-6 Astra can work out what it needs to read without being pushed to review the whole project before every change.
Read what the task needs
Prompting the model to read files before every edit is a great way to burn context and slow work down. Pointing to some docs can still be helpful, however, so long as it is contextual. Be sure to keep your docs updated too!
Previous models needed encouragement to run tests and check their work. GPT-6 Astra does that on its own, so the same instructions can lead to unnecessary testing.
GPT-6 Astra is thorough, but it can be more tentative about how far to take a task. Sometimes it needs a little push to keep going. You can use AGENTS.md to give it permission for a specific workflow you know is safe, such as a local test suite:
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.
Decision boundaries
Pay careful attention to how you describe boundaries. If a previous model did things on your behalf without permission, you may have added strong language to make it ask first. That can be useful, but GPT-6 Astra, as our most aligned model, has much better judgment and will not perform tasks unless it knows it is safe – so you should treat it as such.
If you stated boundaries previously because you wanted to prevent other models from going too far and you’re now switching to GPT-6 Astra, consider updating that language: Astra could take it too seriously and may stop work where you’d actually be happy for it to continue.
Persistence
If you’re used to GPT-5.6 Sol taking a request and 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 your review while there’s still work to do.
This is where it helps to define completion before starting. You might need to push Astra to continue until it’s fully done. If the task includes getting the implementation running, inspecting the result, and fixing what fails, make that part of the request. 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.
If you want it to keep exploring beyond a first pass, say what you want explored and where it should stop.
A new model is a good opportunity to clean your house, but you don’t need to review everything manually: ask GPT-6 Astra to do an audit based on what was discussed in this article, then go build something you wouldn’t have attempted before!