OpenAI 刚放出 GPT-6 的消息我第一反应不是去抢跑分截图而是打开终端盘点了一轮 Skill 和 AGENTS.md。原因很简单模型越强Agent 能接的任务越长喂给它的“上下文资产”就越值钱。以前你可以在系统提示词里塞一段话蒙混过关到了 GPT-6 这代Skill 和 AGENTS.md 已经不是锦上添花的配置而是 Agent 能否稳定工作的地基。如果你过去半年用 Codex、Claude Code 或各类 Agent 框架攒了一堆 Skill 和项目说明文件现在不收拾等 GPT-6 真正铺开时你会被自己的历史包袱拖死。这篇文章不聊概念、不画大饼我只讲怎么给你的 Skill 目录和 AGENTS.md 做一次彻底的“大扫除”先盘点再删改最后建立一套可持续维护的机制。适合两类人看一类是把 Agent 当工具用的开发者另一类是开始给团队搭建 Agent 工作流的负责人。1. 为什么 GPT-6 让 Skill 和 AGENTS.md 变成必答题1.1 从“一条提示词通吃”到“一组 Skill 分工”先说清楚 Skill 和 AGENTS.md 到底是什么。简单说Skill 是一个“可复用的任务能力包”它通常包含一份说明文档最常见的是 SKILL.md、必要的脚本、参考文件和示例输出。Agent 会根据当前任务描述从你安装的 Skill 列表里挑出最匹配的那个像调用函数一样把它“加载”进来执行。AGENTS.md 则是项目级的 Agent 说明文件相当于给 AI 同事看的“新员工入职手册”。它写清楚这个项目怎么跑、怎么测试、目录结构是什么、有哪些绝对不能碰的红线。和 README 不一样AGENTS.md 的读者不是人是 Agent。过去我们写提示词是“一条 prompt 打天下”。但 GPT-6 这代模型的任务长度和执行链条明显变长如果仍然把所有规则堆在一个提示词里你会面临几个问题上下文爆炸、指令自相矛盾、模型抓不住重点。Skill 的价值就是把大而全的提示词拆成按需加载的模块需要时再调用不需要时不占空间。这比让模型每次都在几千行指令里做“全文检索”靠谱得多。1.2 为什么“现在”要大扫除很多人问GPT-6 还没正式开放急什么我的观点是清理工作要在新模型“上线前”做而不是“上线后”做。原因有三第一模型能力升级后旧 Skill 里的很多“补偿性提示”会变成噪音。举个例子过去模型不会自动输出结构化 JSON你可能写了一个“JSON 格式化 Skill”里面全是“必须输出合法 JSON”之类的强调。到了 GPT-6原生能力已经很强这类 Skill 不仅没用还会浪费上下文窗口。不删掉它可能干扰新模型对任务的理解。第二Skill 之间会互相污染。你装的 Skill 越多Agent 在选择时就越容易挑错。尤其是那些 description 写得很模糊的 Skill比如“帮助用户解决问题”模型根本不知道什么时候该用。Skill 数量一旦超过几十个光是“选择性加载”这个动作就会拖慢响应。第三AGENTS.md 和 Skill 往往承载着“上一个时代的经验”。你以前为了规避某个模型的 bug 写下的绕行方案可能在新模型上完全失效甚至变成反效果。大扫除的本质是把“针对旧模型的补丁”剥掉留下“跨模型通用的任务知识”。2. 大扫除前先盘点你的 Agent 家底2.1 用命令把全部 Skill 和 AGENTS.md 翻出来直接靠记忆盘点一定不准。我见过太多人的 Skill 目录里躺着三份功能重复的“代码审查”规则其中两份已经半年没更新。正确的做法是先扫描一遍文件系统让数据告诉你真相。如果你用的是 Codex可以直接用命令行工具查codex skills list ls -la ~/.codex/skills如果你用的是 Claude Code、Cursor 或者其他 Agent 框架就按各自的配置目录找find ~ -name SKILL.md -not -path */node_modules/* 2/dev/null find . -name AGENTS.md -not -path */node_modules/* 2/dev/null find . -name CLAUDE.md -not -path */node_modules/* 2/dev/null扫描结果通常会让你吓一跳。我自己上次清理时发现某个项目根目录下同时存在 AGENTS.md、CLAUDE.md 和一份被改名成 AGENTS_old.md 的过期文件。Agent 加载规则时会优先读取哪个不同框架的处理方式不一样这种重复文件就是最大的不确定性来源。扫描完之后建议把结果整理成一张表。不要凭感觉判断“这个 Skill 好像用过”要去翻历史记录、终端日志、聊天记录看它最近 90 天到底被调用过几次。Skill 名称用途最近更新时间调用频率是否可测试结论数学建模赛题拆解与论文初稿3 个月前高可保留并重构安全审计扫描依赖与端口扫描6 个月前低难删除JSON 整理输出格式化8 个月前中可合并进基础规则代码审查拉取 diff 后提意见1 个月前高可保留并更新这张表就是你的“Agent 资产清单”。没有清单后面所有删改都是拍脑袋。2.2 给每个项目做一次 AGENTS.md 健康体检Skill 盘点完还要逐个项目检查 AGENTS.md。最理想的状态是每个需要 Agent 参与的仓库有且仅有一份权威规则文件文件长度控制在 100 行以内里面的每一条规则都能被验证。检查时重点看三个问题这份 AGENTS.md 是否还准确里面有没有和当前工具链冲突的命令有没有因为某个临时问题留下的“补丁式条款”我见过有人在 AGENTS.md 里写着“不要使用 npm install请用 pnpm”但项目的 package-lock.json 已经删除实际上 npm 才是正确选择。这种过期指令会让 Agent 反复犯同一个错误。体检完把“问题清单”记录下来下一步就知道哪些文件要改、哪些整份删除。3. 扫描完成后哪些 Skill 该删、该改、该合并3.1 删除的四个标准很多人的问题不是 Skill 太少而是太多。删的时候可以按下面四个标准做判断只要命中一条就考虑进回收站。第一和模型原生能力重复。比如“写得更正式一点”“不要使用 emoji”“输出 Markdown”这类 Skill本质上是在给老模型打补丁。新模型基本不需要这种指令式约束除非你有严格的格式规范否则删。第二只包含宏观口号、没有可执行步骤。有些 Skill 内容通篇是“请给用户提供高质量回答”“请确保代码安全”但没有任何检查清单、示例或脚本。这种 Skill 没有信息增量模型加载了也不知道具体做什么。第三依赖已废弃的工具或接口。比如某 Skill 里写死了调用某个旧版命令行工具而该工具已经被团队弃用。这种 Skill 不仅无效还可能导致 Agent 执行一个不存在的命令直接报错。第四只解决过一次问题。很多人的 Skill 是为了某个一次性任务现写的比如“给上季度 PPT 润色”。任务结束后它就再没被用过。这类 Skill 应该封存到 archived 目录而不是留在主目录里继续污染索引。3.2 合并与改名的原则保留的 Skill 同样需要整理重点是“合并同类项”和“统一命名”。合并的逻辑和代码重构一样把职责相同的任务合并成一个 Skill由一份文档统一管理。比如你可能有“前端代码审查”“后端代码审查”“安全代码审查”三个 Skill如果它们的内容 60% 重复就应该合并成一个code-reviewSkill再把前端、后端、安全相关的检查项作为不同章节或子脚本放进去。这样 Agent 不会在“该加载哪个 Skill”这件事上纠结。命名方面我推荐用领域-动作-对象的结构全部小写、用中划线连接。比如math-modeling-report、security-audit-scan、dependency-update-check。这种命名一眼能看出用途而且方便脚本做分类统计。description 字段是更重要的部分因为大多数 Agent 框架是按 description 做语义匹配的不是按文件名。description 要写清楚“什么场景下用”“不用于什么场景”。比如description: 当用户提供数学建模赛题或需要建模思路时使用负责赛题拆解、假设分析、模型选择与论文初稿生成。不用于纯统计图表绘制。这样的 description 能显著降低 Agent 选错 Skill 的概率。3.3 给 Skill 标上维护状态清理过程中我建议你在每个 SKILL.md 的 frontmatter 里加三个字段status、owner、last_verified。status可以是active、deprecated、archivedowner填写负责人的 GitHub 账号last_verified记录最后一次验证通过的日期。这看起来是形式主义但实际作用很大。三个月后你再看一眼这个文件如果last_verified已经超过半年并且调用日志里没有新记录你就有理由把它降级或删除。Skill 和代码一样不维护就会腐烂。4. AGENTS.md 重构实操4.1 AGENTS.md 该写什么、不该写什么AGENTS.md 的定位是“规则文件”不是“文档百科”。它应该像法律条文一样简单而不是像教科书一样详细。我常用的模板大概是这样的# AGENTS.md ## 项目目标 - 本仓库是一个数据采集服务提供 REST API。 - 核心指标是采集成功率与数据延迟不要在重构时牺牲稳定性。 ## 常用命令 - 安装依赖npm ci - 运行单元测试npm run test:unit - 运行 Lintnpm run lint - 启动本地服务npm run dev ## 目录结构 - src/api接口层路由定义 - src/services业务逻辑 - src/utils通用工具禁止引入业务依赖 ## Agent 规则 - 任何代码改动都必须先跑 npm run test:unit。 - 不要修改 package-lock.json除非依赖有明确变更。 - 不要新增全局环境变量配置如需新增参数请通过 config 文件。 - 提 PR 前必须补全变更范围内的测试用例。这份文件的核心特征是“每一条都可执行、可验证”。Agent 能明确知道先做什么、什么不能做。比如“不要修改 package-lock.json”这种负面清单比“请小心处理依赖文件”有效得多。4.2 重构 AGENTS.md 时的三个常见错误不要写成 README。很多人把 AGENTS.md 当 README 写开头大段介绍项目背景、技术选型的来龙去脉Agent 读到最后发现没有一条可执行的指令。项目背景可以放 READMEAGENTS.md 只放“行为准则”。不要和 Skill 规则冲突。假设某个 Skill 里写“代码审查通过后可以直接 merge”但 AGENTS.md 里写“所有 merge 必须由人工执行”Agent 就会陷入两难。我的原则是 AGENTS.md 优先它相当于宪法Skill 是操作手册不能超越宪法。如果发现冲突要么改 Skill要么改 AGENTS.md绝不能两个都留。不要放“一次性指令”。比如“今天先别跑测试我要赶着上线”这种临时决策写完就失效了。AGENTS.md 里只放稳定、长期的规则临时任务请直接写在当前对话的上下文里。重构完 AGENTS.md建议在文件末尾加一个“最近更新记录”表格记录修改人、日期、原因。这不是给 Agent 看的是给团队里的其他人类看的。5. Skill 打包与版本化从原生文件夹到共享仓库5.1 SKILL.md 的标准结构当你的 Skill 数量超过 5 个就应该用统一模板来管理。我的标准结构分三部分frontmatter、正文、附件。frontmatter 用 YAML至少要包含name、description、version。我习惯加上license和tags。正文部分用 Markdown写清楚“什么时候用”“执行步骤”“输出格式”“注意事项”。附件包括脚本、参考文档、测试用例。下面是一个简化的数学建模 Skill 的骨架--- name: math-modeling-report description: 用于数学建模赛题拆解与论文初稿生成。当用户提供赛题文本或询问建模思路时使用。 version: 2.3.0 license: MIT tags: [math, modeling, report] --- # Math Modeling Report ## 使用场景 - 用户提供一道建模赛题需要拆解问题和建立模型。 - 用户已有模型结果需要论文初稿。 ## 执行步骤 1. 阅读赛题提取目标、约束条件、数据可用性。 2. 拆解为“问题定义 - 假设 - 模型 - 算法 - 验证”五段结构。 3. 列出至少两种候选模型对比后给出推荐。 4. 输出 Markdown 格式的赛题分析与建模过程初稿。 ## 输出格式 - 标题层级H2 以下 - 必须包含问题重述、基本假设、符号说明、模型构建、求解思路 ## 注意事项 - 不虚构数据数据缺失时明确说明。 - 不在初稿中给出最终结论性语言建议用“初步认为”作修饰。这个模板的核心是“让模型在加载 Skill 后不需要再做大量理解”直接照步骤执行即可。5.2 用 Git 管理 Skill目录即包Skill 本质上是文件集合应该像代码一样纳入版本控制。我建议把 Skill 放在专用仓库中目录结构如下skills/ math-modeling-report/ SKILL.md references/ common-models.md scripts/ preprocess_data.py fixtures/ sample-problem.md expected-output.md tests/ test_skill.py security-audit-scan/ SKILL.md scripts/ scan_deps.py ... AGENTS.md每个 Skill 一个文件夹文件夹名和 SKILL.md 里的name保持一致。这样不管是手动复制到本机还是通过包管理器安装都不会出现“文件拿到了但配置对不上”的问题。5.3 给 Skill 加自动化检查既然进了 Git 仓库就可以在 CI 里跑检查。最简单的检查是验证每个 SKILL.md 的 frontmatter 是否完整、name是否唯一、description是否足够长。我写过一段很简单的 Python 脚本用 PyYAML 解析所有 SKILL.md 的 frontmatter再检查必填字段。import os from pathlib import Path import yaml skills_dir Path(skills) errors [] for f in sorted(skills_dir.glob(*/SKILL.md)): content f.read_text(encodingutf-8) parts content.split(---) if len(parts) 3: errors.append(f{f}: frontmatter missing) continue meta yaml.safe_load(parts[1]) for field in (name, description, version): if not meta.get(field): errors.append(f{f}: missing {field}) if errors: print(\n.join(errors)) raise SystemExit(1) print(All skills are valid.)这段代码可以在 GitHub Actions 或 GitLab CI 里每次 push 时运行。它不能保证 Skill 质量但至少能阻止明显残缺的 Skill 被提交。6. 常见问题与排查技巧实录6.1 模型“看不到”我的 Skill这是最常见的求助帖。排查思路按照“定位 - 描述 - 冲突”三步走。先确认 Skill 是否在 Agent 能扫描到的目录里。Codex 通常只扫描特定目录不能想当然地把文件放在项目根目录就算“装好”。再用codex skills list看有没有出现在列表里。如果列表里有但模型就是不用问题大概率出在description上。比如你写的 description 是“数学建模”这个关键词太泛模型不知道是在说“解题”还是“论文写作”。改成上面那种带触发条件的写法会好很多。还有一种可能是其他 Skill 的 description 里有相似关键词造成语义混淆这时需要用更明确的边界词区分。6.2 AGENTS.md 写了但 Agent 不遵守先检查 AGENTS.md 是否放在仓库根目录文件名是否完全正确。框架对文件名的解析通常区分大小写agents.md和AGENTS.md可能是两个不同的文件。再看文件长度。如果 AGENTS.md 超过 200 行Agent 很可能会“读到后面忘前面”或者被大量无关信息分散注意力。把文件砍到 100 行以内并且把最重要、最不能违反的规则放到文件的“Agent 规则”一节会有明显改善。最后检查内容自相矛盾。一份 AGENTS.md 里如果出现“所有改动必须跑测试”和“小改动可以跳过测试”模型就会无所适从。规则要绝对尽量不要用“通常”“一般”“尽量”这类模糊词。6.3 Codex 安装回报错怎么办很多人装 Codex 时遇到npm install -g openai/codex报错问题大多出在 Node 版本或 npm 权限上。先用node -v确认版本Codex 要求 Node 18 以上再用npm config get prefix看看全局安装路径是否在你的用户目录下。如果 prefix 指向系统目录建议配上用户级全局目录不要用 sudo 硬装。换到 nvm 管理的 Node LTS 版本后这类安装报错基本能解决。6.4 关于 GPT-6 跑分、破解数学题这些热搜最近圈子里讨论最多的是 GPT-6 的跑分和“一天破解五道数学难题”。作为工程人员我的态度是评测口径必须区分清楚。有的跑分是在特定数据集上、带人工辅助条件的结果有的是框架自动评测的结果两者没有可比性。与其盯着别人的跑分数字不如用自己的历史任务集跑一遍回归。Skill 和 AGENTS.md 清理完毕后正好可以做一次基准测试同一批任务清理前和清理后各跑一轮对比成功率、输出质量和耗时。7. 清理后的日常维护机制7.1 每个季度做一次 Skill“体检”清理不是一次性的。模型迭代、项目变更、团队分工调整都会让 Skill 和 AGENTS.md 快速失真。我建议每个季度固定安排一次“Agent 资产体检”检查六个问题检查项通过条件调用频率近 90 天有实际调用记录输出质量最近输出未被大范围修改描述匹配description 与实际使用场景一致依赖状态引用的工具、API、脚本仍可用自动化测试Skill 的验收测试能通过规则一致性与 AGENTS.md、其他 Skill 无冲突六项里有四项以上不通过就进入“待处理”状态。要么花时间重构要么直接归档。7.2 把大扫除本身做成一个 Skill最后分享一个我觉得挺有用的做法把“Agent 资产体检”本身定义成一个 Skill。内容就是运行扫描命令、读取调用日志、生成体检报告、列出待清理项。这样到了季度末你只需要对 Agent 说一句“帮我做一次 Skill 大扫除”它就能自动把家底翻出来列成表格你只需要做最终的删改决策。大扫除过后我最大的体会是“文件变少但可控性变强了”。同样一个数学建模任务清理前模型经常在三个相近 Skill 之间犹豫输出格式飘忽不定清理后只剩一个职责明确的 Skill十次运行有九次是稳定的。GPT-6 这样的新模型对语境敏感度只会更高你的资产越干净新模型的上限就越高。别等到发布会开完再临时抱佛脚现在就把 Skill 和 AGENTS.md 当一个正经代码仓库来维护后面会省下大量的调试时间。