企业官网建设流程全解析

1. 从一次“Agent 不听话”说起：Skill 到底解决什么问题

你可能遇到过这种场景：同一个 Agent，昨天写技术文章结构清晰，今天同样的提示词却输出得乱七八糟；或者你反复强调“先分析根因再改代码”，它还是上来就补表面症状。问题不在模型本身，而在于你每次都在用 Prompt 做“一次性指挥”，没有把“这类任务该怎么做”沉淀下来。

Skill 就是干这个的。它是一套给 Agent 使用的可复用工作流说明书，通常是一个文件夹，里面至少有一个SKILL.md。Agent 启动时只看到 Skill 的名称、描述和路径；当你的请求命中它的适用场景，Agent 才会读取完整的SKILL.md并按里面的流程执行。它和 Prompt、MCP、Plugin 的分工可以这样对照：

所以 Skill 的本质不是“提示词增强”，而是流程产品化。它把你的经验、方法、检查标准和输出偏好，变成 Agent 可以重复执行的工作流。这篇面向刚接触 Agent Skill 的开发者，从零拆解目录结构、SKILL.md编写规范、在 Codex/Plugin 场景下的放置位置，并演示通过 TaoToken 统一 Key/API 通道完成一次 Skill 调用验证，确认结构真的生效。适合谁：正在用 Codex、Cline、Claude Code 等工具做 Agent 开发，想让输出稳定可复现的人。

2. TaoToken 前置准备：统一 Key 与 API 通道怎么配

在验证 Skill 之前，先把模型调用通道打通。TaoToken 提供统一的 Key 和 API 入口，你不需要在多个模型供应商之间来回切换配置。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api （这个地址不加 UTM 参数）。

先拿到 Key。打开控制台页面 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 区域创建一个新 Key。创建时给它起个能认出来的名字，比如skill-verify，方便后面排查是哪个 Key 在调用。复制出来的 Key 只显示一次，先存到本地环境变量里，别直接写进会提交到 Git 的文件。

# macOS / Linux：写入当前 shell 会话 export TAOTOKEN_API_KEY="sk-你的Key" # Windows PowerShell $env:TAOTOKEN_API_KEY="sk-你的Key"

如果你用的是 Claude Code 这类需要 Anthropic 兼容端点的工具，可以参考接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里的说明配置 Base URL。核心三件套永远是：Base URL、API Key、Model ID。缺一个都会在调用时报错，后面排障章节会逐个对照。

这里要强调一点：Skill 本身不负责模型调用，它只描述“怎么做”。真正把请求发出去的是你用的 Agent 工具或脚本。所以验证 Skill 是否生效，思路是——让 Agent 在读取SKILL.md后，通过 TaoToken 通道发起一次真实请求，看输出是否符合 Skill 里定义的流程和验收标准。

3. 可复制配置：SKILL.md 模板与目录树

先建目录。最小可用 Skill 只有一个文件，但实际项目里建议按需扩展。下面这棵目录树可以直接复制使用：

my-skill/ ├─ SKILL.md ├─ agents/ │ └─ openai.yaml ├─ scripts/ │ └─ validate.py ├─ references/ │ └─ checklist.md ├─ templates/ │ └─ report.md └─ examples/ └─ sample-output.md

不是每个目录都必须存在，原则是需要什么才放什么。SKILL.md是入口文件，必须存在；agents/openai.yaml是 Codex 可选元数据，可配置显示名、默认提示和隐式触发策略；scripts/放确定性脚本；references/放规范、术语表、检查清单；templates/放输出模板；examples/放输入输出示例。

SKILL.md顶部是 YAML front matter，下面才是正文。直接复制这个模板：

--- name: tech-article-writer description: Use when the user asks to write or rewrite a technical article in a fixed structure with code blocks, parameter tables, and a verification section. Do not use for casual chat or pure translation. --- # Tech Article Writer ## When to use - 用户要求按固定结构写技术文章 - 需要包含可复制代码、参数对照表、排障章节 ## Steps 1. 读取 references/checklist.md 确认结构要求 2. 按 templates/report.md 生成骨架 3. 填充代码块并标注语言 4. 运行 scripts/validate.py 检查标题层级 5. 输出前对照验收标准自检 ## Acceptance criteria - 每个 H2 正文不少于 800 字 - 代码块必须标注语言 - 包含至少一个参数对照表

name要短、稳定、可被引用；description要直接，因为 Agent 靠它判断是否触发。写得太空比如description: Help with writing.，Agent 根本不知道什么时候该用。触发条件里最好同时写清适用边界和不适用场景，减少误触发。

如果你在 Codex 里用，agents/openai.yaml可以这样写：

display_name: Tech Article Writer icon: doc default_prompt: 按固定结构写一篇技术文章 implicit_invocation: true tools: - shell - file_read

implicit_invocation: true表示允许 Agent 在没被点名时也自动触发。如果你发现误触发太多，就把它改成false，只在你明确点名时使用。

4. 验证请求：通过 TaoToken 跑通一次 Skill 调用

配置写好了，得验证它真的生效。这里用一个最小脚本，模拟 Agent 读取SKILL.md后通过 TaoToken 发起请求。先确认环境变量已设置，然后执行：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [ {"role": "system", "content": "你已加载 Skill: tech-article-writer，请按 SKILL.md 中的 Steps 和 Acceptance criteria 执行。"}, {"role": "user", "content": "写一篇关于 Skill 目录结构的技术文章。"} ] }'

成功时你会拿到一个 JSON 响应，choices[0].message.content里是模型输出。判断 Skill 是否生效，不看它“写了文章”，而看它是否遵守了SKILL.md里的约束：有没有先读references/checklist.md、有没有按templates/report.md的骨架、代码块有没有标语言、有没有跑scripts/validate.py。

如果你用的是 Claude Code，配置方式略有不同。在项目根目录创建.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

保存后重启 Claude Code，它会读取这个配置并通过 TaoToken 通道发起请求。此时把 Skill 放进对应目录，再让它执行一个命中场景的任务，观察输出是否符合SKILL.md的验收标准。

想快速验证模型通道本身是否通，可以先用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条消息，确认 Key 和 Base URL 没问题，再回到 Skill 验证。这样能把“通道问题”和“Skill 结构问题”分开排查。

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

验证过程中最容易撞上几类报错，逐个对照。

401 Unauthorized：Key 没传对或已失效。检查Authorization头是不是Bearer sk-xxx格式，中间有没有多余空格；检查环境变量是否在当前 shell 会话里生效，echo $TAOTOKEN_API_KEY看有没有值。如果 Key 是在别的终端创建的，确认复制完整，没有截断。

local proxy failed / connection refused：通常是 Base URL 写错或本地网络配置问题。确认用的是https://taotoken.net/api，不要多加/v1之外的路径，也不要用带 UTM 的地址做 API 调用。如果你在settings.json里把ANTHROPIC_BASE_URL写成了官网首页地址，就会连不上。

reading 'choices' of undefined：响应体里没有choices字段，说明请求根本没走到模型。常见原因是请求体 JSON 格式错误，比如少了逗号、引号没闭合；或者model字段填了一个不存在的 Model ID。先用最小请求体测试，确认能拿到正常响应再往上加内容。

OAuth / authentication 相关报错：如果你用的是 Codex 或 Claude Code 的登录态，同时又配了 API Key，可能两套认证打架。检查auth.json或settings.json里是不是同时存在 OAuth token 和 API Key。保留一套即可，用 TaoToken 统一 Key 时，把 OAuth 相关字段清掉。

Skill 没触发：不是报错但很常见。先看description是不是写得太泛，把关键触发词前置；再看implicit_invocation是不是设成了false；最后确认 Skill 放对了目录——Codex 仓库级是.agents/skills/，个人级是$HOME/.agents/skills/，放错位置 Agent 扫不到。

排障时建议按“通道→认证→请求体→Skill 结构”的顺序查，别一上来就改SKILL.md。多数问题出在前三步。

6. 把 Skill 用起来：放置位置与长期维护

Skill 放哪里，决定了它的作用范围。Codex 支持多个层级：仓库级放在当前项目的.agents/skills/，适合团队共享，Codex 会从当前工作目录向上扫描直到仓库根目录；个人级放在$HOME/.agents/skills/，Windows 上通常是C:\Users\你的用户名\.agents\skills\，适合你个人长期使用的写作风格、图片风格、工作流。

如果你要把一个或多个 Skill 分发给别人，或者把 Skill 和 MCP 配置、图标一起打包，就做成 Plugin。Plugin 的目录结构是：

my-plugin/ ├─ .codex-plugin/ │ └─ plugin.json └─ skills/ └─ my-skill/ └─ SKILL.md

Skill 是工作流本身，Plugin 是安装和分发单位。其他 Agent 工具的扫描目录不一定和 Codex 相同，如果某个工具兼容SKILL.md结构，它通常会要求你把每个 Skill 作为独立文件夹放进指定技能目录。不要默认把 Codex 的路径直接搬过去，具体位置以该工具当前文档为准。

长期维护上，我试过把每次踩坑的检查项补进references/checklist.md，比改SKILL.md正文更安全，因为正文改动可能影响触发判断。另外，scripts/里的校验脚本值得单独写测试，Skill 越常用，确定性逻辑越应该脚本化，减少 Agent 每次重新实现带来的波动。

如果你打算长期做编码类 Agent 任务，可以了解 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，把 Skill 和统一 Key 通道结合起来用。需要管理多个 Key 或查看调用情况时，回到 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 操作即可。