企业官网建设流程全解析

1. 为什么你需要关心 SKILL.md 这个文件

如果你同时用 Claude Code 写后端、用 Codex 补前端，大概率遇到过这种糟心事：在 Claude Code 里调教好的一套代码审查流程，换到 Codex 就得重新用自然语言描述一遍，而且每次描述还不一样，输出质量忽高忽低。Agent Skills 和 SKILL.md 就是为了解决这个问题出现的——它本质上是一份写给 AI 看的「最佳实践手册」，用一个 Markdown 文件把任务流程、约束条件、输出格式固定下来，让不同 Agent 工具都能按同一套标准执行。

SKILL.md 能做什么？简单说，它把「你脑子里的 SOP」变成「Agent 能自动加载并执行的指令集」。适合谁？适合那些已经在用 Claude Code、Codex、Antigravity 等工具，并且希望把重复性任务（比如发票去重、代码规范检查、日志分析）固化下来的开发者。你不需要懂模型训练，甚至不需要精通编程，只要能把自己的工作流程写清楚，就能做出一个可复用的 Skill。

我实测下来，SKILL.md 的核心价值在于三点：第一，一次编写，多端通用正在成为现实；第二，创作门槛极低，一个文件夹加一个 Markdown 文件就能跑；第三，生态正在快速膨胀，早写早受益。但问题也来了——不同平台对 SKILL.md 的支持程度真的一样吗？触发逻辑、YAML 解析、输出格式会不会有差异？这篇文章会带你从零写一个 SKILL.md，然后在 Claude Code 和 Codex 两端分别加载、验证触发、对比输出，把「一次编写，全网通用」这件事真正跑通。

2. 写一个 SKILL.md 之前，先把 TaoToken 配好

在开始写 SKILL.md 之前，你需要一个能同时驱动 Claude Code 和 Codex 的 API 入口。我试过直接用官方 Key，但切换模型时经常要改环境变量，比较麻烦。后来换成 TaoToken 的统一接入方式，Base URL 和 Key 一套配置就能在多个工具间复用，省去了反复改配置的功夫。

TaoToken 的官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。你需要在控制台创建一个 API Key，然后根据你要用的工具选择对应的模型 ID。比如 Claude Code 通常用 claude-opus-4-5 或 claude-sonnet-4-5，Codex 则用 gpt-codex-5.2 这类模型标识。

这里要强调一点：SKILL.md 本身是纯文本文件，不依赖任何特定平台。但要让 Claude Code 和 Codex 都能加载它，你需要确保两个工具都指向同一个 API 入口，并且模型 ID 正确。否则会出现「Skill 写对了但 Agent 不触发」的情况，排查起来很浪费时间。

配置 TaoToken 的步骤不复杂：先注册账号，然后在控制台生成 API Key，接着在 Claude Code 的配置文件里填入 Base URL 和 Key，在 Codex 的 auth.json 里也填入同样的信息。具体路径和字段我会在下一节给出可复制的配置片段。这样做的目的是让两个工具共享同一套鉴权信息，减少环境差异带来的干扰。

3. 可复制的 SKILL.md 目录结构与字段配置

现在进入正题。一个标准的 SKILL.md 放在项目根目录的.agent/skills/<skill-folder>/SKILL.md路径下。比如你的项目叫 my-project，那么完整路径就是my-project/.agent/skills/my-skill/SKILL.md。如果你想做成全局 Skill，让所有项目都能用，可以放在~/.gemini/antigravity/skills/<skill-folder>/或者对应工具的全局技能目录里。

SKILL.md 的文件结构分为两部分：开头的 YAML frontmatter 和正文指令。YAML 部分必须包含name和description两个字段。name是技能的唯一标识，建议用英文小写加连字符；description要写清楚「这个技能在什么场景下触发、能做什么、什么时候不能用」，因为 Agent 会根据这段描述来判断是否加载该技能。

下面是一个可复制的 SKILL.md 示例，用于「发票去重」场景：

--- name: invoice-dedup description: 当用户上传多张发票截图并需要识别重复发票时触发。通过 OCR 提取交易号进行模糊匹配，输出重复分组。不适用于非发票类图片去重。 --- ## 怎么用 1. 对每张发票图片执行 OCR，提取全部文本内容。 2. 用正则表达式匹配交易号，交易号通常是 20-30 位连续数字。 3. 对提取到的交易号做模糊匹配，允许 1-2 位字符误差以处理 OCR 识别错误。 4. 将匹配到的重复发票分组输出，每组标注原始文件名和交易号。 5. 如果某张发票无法提取到交易号，单独列出并说明原因。 ## 输出格式 以 JSON 数组返回，每个元素包含 `group_id`、`files`、`transaction_ids` 三个字段。

对应的 Claude Code 配置片段（~/.claude/settings.json）：

{ "apiKey": "你的_TaoToken_API_Key", "baseUrl": "https://taotoken.net/api", "model": "claude-opus-4-5" }

对应的 Codex 配置片段（~/.codex/auth.json）：

{ "api_key": "你的_TaoToken_API_Key", "base_url": "https://taotoken.net/api", "model": "gpt-codex-5.2" }

注意：Base URL、API Key、Model ID 这三件套必须同时正确，缺一不可。如果你用的是 Cline 或 CC Switch 这类工具，配置逻辑类似，都是把这三个字段填对。

4. 在 Claude Code 与 Codex 中加载并验证同一个 Skill

配置写好后，接下来验证 Skill 是否能在两端正确加载和触发。先确认目录结构：在项目根目录下执行ls -la .agent/skills/invoice-dedup/，应该能看到SKILL.md文件。如果没有这个目录，手动创建即可。

在 Claude Code 中，启动对话后输入「用 invoice-dedup 技能帮我处理这批发票截图」，观察它是否自动加载了 SKILL.md。你可以通过查看对话开头的系统提示或工具调用来确认。如果触发成功，Claude Code 会按照 SKILL.md 里的步骤执行 OCR、正则提取、模糊匹配，最后输出 JSON 格式的重复分组。

在 Codex 中，操作类似。启动 Codex 会话后，输入同样的指令。Codex 会扫描可用技能列表，根据description字段判断是否匹配当前任务。如果匹配，它会加载 SKILL.md 并执行。你可以用cat命令查看 Codex 是否在临时目录生成了技能缓存文件，或者直接观察输出是否符合 SKILL.md 定义的 JSON 格式。

验证输出一致性的方法：准备三张发票截图，其中两张交易号相同（模拟重复），一张不同。分别在 Claude Code 和 Codex 中运行同一个 Skill，对比两端返回的 JSON 数组。理想情况下，group_id、files、transaction_ids三个字段的结构应该一致，重复分组的逻辑也应该相同。如果出现差异，优先检查模型 ID 是否写错，或者 SKILL.md 的description是否足够明确。

实测下来，在基础链路上——技能识别、YAML 解析、JSON 输出、文件落盘——Claude Code 和 Codex 的表现已经非常接近。这意味着你写一次 SKILL.md，确实可以在两端复用，不需要为每个平台单独维护一套指令。

5. 常见报错与排查：401、local proxy failed、reading choices

即使配置正确，实际使用中还是会遇到一些报错。下面列出几个我踩过的坑和对应的排查方法。

401 Unauthorized：最常见的原因是 API Key 填错或过期。检查settings.json和auth.json里的 Key 是否与 TaoToken 控制台生成的一致。注意不要有多余空格或换行。如果 Key 正确，检查 Base URL 是否写成了https://taotoken.net/api，而不是带 UTM 参数的完整链接。

local proxy failed：这个报错通常出现在 Claude Code 启动时，说明本地代理配置有问题。如果你没有使用任何代理工具，检查环境变量HTTP_PROXY和HTTPS_PROXY是否被意外设置。如果有，清除它们再重启 Claude Code。另外，确认 TaoToken 的 API 地址是直连可访问的，不需要额外网络配置。

reading choices 报错：这个错误一般出现在 Codex 解析模型返回结果时，提示无法读取choices字段。原因可能是模型 ID 写错了，比如把gpt-codex-5.2写成了gpt-5.2。检查auth.json里的model字段，确保与 TaoToken 文档中列出的模型标识完全一致。如果模型 ID 正确，尝试降低请求频率，避免触发限流。

OAuth 相关报错：如果你在 Claude Code 中看到 OAuth 认证失败的提示，说明工具尝试用 OAuth 方式登录而不是 API Key。检查settings.json中是否同时存在apiKey和 OAuth 相关字段，删除 OAuth 字段，只保留 API Key 配置。Codex 同理，确保auth.json中只有api_key字段，没有多余的oauth_token。

排查时建议按顺序检查：Base URL → API Key → Model ID → 网络环境。这四个环节任意一个出错都会导致 Skill 无法正常加载或执行。如果确认配置无误但问题依旧，可以到 TaoToken 的接入文档页面查看最新的配置示例，或者直接在模型对话页面测试 API 连通性。

6. 把 Skill 用起来：从验证到长期编码

验证完 SKILL.md 在 Claude Code 和 Codex 两端的表现后，你可以开始把它用到日常开发中。比如把代码审查规范写成 Skill，每次提交 PR 前让 Agent 自动检查命名风格、注释覆盖率、异常处理逻辑；或者把日志分析流程固化下来，遇到线上问题时一键触发。

如果你需要长期跑编码任务或 Agent 工作流，可以考虑使用 Coding Plan，它提供了更稳定的调用额度和更低的延迟。对于只需要验证模型输出或临时测试 Skill 的场景，模型对话页面就足够了。而如果你要管理多个 API Key 或查看调用量，控制台和 API Keys 页面是必经之路。

回到最初的问题：一次编写，全网通用，到底能不能做到？我的实测结论是：在基础标准上，Claude Code、Codex、Antigravity 等工具已经高度一致，SKILL.md 的目录结构、YAML 字段、触发逻辑基本互通。但不同平台对复杂指令的解析深度仍有细微差异，比如某些平台对模糊匹配的支持更好，某些平台对文件落盘更稳定。所以「通用」是成立的，但「完全一致」还需要你在具体场景中做少量适配。

最务实的做法是：先把核心流程写成 SKILL.md，在两端各跑一遍，记录差异点，然后针对差异调整description或补充正文指令。这样你既享受了跨平台复用的便利，又不会被平台差异坑到。