企业官网建设流程全解析

1. 为什么你的 Agent 总是“答非所问”：从一次真实的 Skill 失效说起

你有没有遇到过这种情况：明明给 Claude Code 或 OpenCode 写了一个看起来很完整的 Skill，结果它要么完全不触发，要么触发了却执行得乱七八糟。我试过在一个项目里定义了一个“生成数据库迁移脚本”的 Skill，描述写得很详细，但 Agent 就是不用它，反而自己临时拼了一段 SQL 出来，字段类型还写错了。

问题不在于模型不够聪明，而在于 Skill 的设计没有遵循 Agent 的发现机制。Agent Skill 本质上是一套“渐进式披露”系统：启动时只加载每个 Skill 的 name 和 description 元数据，只有当用户请求与某个 description 语义匹配时，才会加载完整的 SKILL.md 内容。这意味着你的 Skill 能不能被用上，80% 取决于那两行 YAML 前置信息写得好不好。

这篇内容聚焦 Agent Skill 从设计到落地的完整链路，以 OpenCode、Claude Code、Codex 等工具为应用场景，拆解技能定义、触发条件与执行边界。我会交付可复制的技能配置模板，以及通过 TaoToken 统一 Key 接入的具体步骤，最后给出本地验证技能是否被正确调用的可操作动作。适合正在使用编程 Agent 但觉得“它总是不按我的套路来”的开发者，也适合想把团队工作流封装成可复用能力的工程团队。

核心检索词先明确：Agent Skill 是什么？它是给编程 Agent 用的模块化能力包，包含一个 SKILL.md 主文件和可选的脚本、参考文档。能做什么？把重复性的领域知识、公司内部流程、特定工具链的操作步骤封装成 Agent 可发现、可按需加载的技能。适合谁？任何希望把“每次都要重新解释一遍”的工作流固化下来的开发者。

2. TaoToken 统一 Key 前置：一次配置，多端复用

在写 Skill 之前，先把接入层搞定。OpenCode、Claude Code、Codex 这些工具各自有自己的配置方式，如果每个都单独管理 Key 和 Base URL，切换起来很麻烦。TaoToken 提供统一 API 入口，你可以在一个地方拿到 Key，然后分别配置到不同工具里。

2.1 获取 API Key 与确认 Base URL

访问 TaoToken 控制台创建 API Key。地址是 https://taotoken.net/api-keys ，登录后点击创建新 Key，复制保存。注意 Key 只在创建时显示一次，丢了就得重新生成。

Base URL 统一使用 https://taotoken.net/api ，这个地址不加任何 UTM 参数，直接填到工具的配置里就行。模型 ID 根据你实际使用的模型来填，比如 claude-sonnet-4-20250514、gpt-4o、gemini-2.5-pro 等，具体以控制台模型列表为准。

2.2 Claude Code 的 settings.json 配置

Claude Code 的配置文件在 ~/.claude/settings.json。如果你之前没有这个文件，手动创建即可。写入以下内容：

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

保存后重启 Claude Code。你可以用/status命令查看当前生效的 Base URL 和模型，确认配置已加载。

2.3 Codex 的 auth.json 配置

Codex 的认证文件在 ~/.codex/auth.json。写入：

{ "OPENAI_API_KEY": "sk-你的TaoToken密钥", "OPENAI_BASE_URL": "https://taotoken.net/api" }

然后在 ~/.codex/config.toml 中指定模型：

model = "gpt-4o"

Codex 启动时会读取这两个文件。如果遇到 OAuth 相关报错，检查 auth.json 的 JSON 格式是否正确，特别是引号和逗号。

2.4 OpenCode 的配置文件

OpenCode 的配置在 ~/.config/opencode/config.json。写入：

{ "provider": { "taotoken": { "baseURL": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥" } }, "model": "taotoken/claude-sonnet-4-20250514" }

OpenCode 的 Skill 目录在 ~/.config/opencode/skill/，项目级 Skill 放在 .opencode/skill/。配置完成后运行opencode --version确认工具正常，再用opencode models查看可用模型列表。

三件套检查清单：Base URL 填 https://taotoken.net/api ，Key 填 sk- 开头的字符串，Model ID 填控制台里显示的完整模型名。三者缺一不可，少一个就会报 401 或 model not found。

3. 可复制的 Skill 配置模板：从 YAML 到执行脚本

这一节给出一个完整的 Skill 模板，你可以直接复制修改。以“生成数据库迁移脚本”为例，展示 SKILL.md 的结构、YAML 前置信息的写法、以及如何引用外部脚本。

3.1 目录结构

generating-db-migrations/ ├── SKILL.md ├── reference/ │ └── type-mapping.md └── scripts/ └── validate_migration.py

保持一层深：SKILL.md 直接链接到 reference/ 和 scripts/ 下的文件，不要出现 SKILL.md → a.md → b.md → c.md 这种多跳导航。

3.2 SKILL.md 完整内容

--- name: generating-db-migrations description: 根据模型定义变更生成数据库迁移脚本，支持 PostgreSQL 和 MySQL。当用户提到迁移、migration、schema change、alter table 或需要修改数据库结构时使用。 --- ## 生成数据库迁移脚本 ### 快速开始 1. 读取当前模型定义文件（通常是 models.py 或 schema.prisma） 2. 对比目标状态，识别新增/修改/删除的字段 3. 生成对应的 ALTER TABLE 语句 4. 运行验证脚本检查语法 ### 字段类型映射 PostgreSQL 和 MySQL 的类型映射差异见 [reference/type-mapping.md](reference/type-mapping.md)。 ### 验证 生成后运行： ```bash python scripts/validate_migration.py --file migration.sql

脚本会检查语法错误和潜在的数据丢失风险。

### 3.3 YAML 前置信息的写法要点 name 字段：最多 64 字符，只用小写字母、数字、连字符。用动名词形式，比如 generating-db-migrations、analyzing-logs、testing-api-endpoints。不要用 helper、utils 这种含糊词。 description 字段：最多 1024 字符，必须同时说明“做什么”和“何时用”。第三人称写法，因为这段文字会被直接注入系统提示。好的写法是：“根据模型定义变更生成数据库迁移脚本，支持 PostgreSQL 和 MySQL。当用户提到迁移、migration、schema change、alter table 或需要修改数据库结构时使用。”差的写法是：“帮助处理数据库相关任务”——太模糊，Agent 无法判断何时触发。 ### 3.4 执行边界与触发条件 在 SKILL.md 正文中明确写出“不做什么”。比如：“本 Skill 只生成迁移脚本，不执行迁移。执行操作需要用户手动确认。”这样可以防止 Agent 越权操作。 触发条件写在 description 里，执行边界写在正文里。两者配合，Agent 才知道什么时候用、用到什么程度。 ### 3.5 引用脚本的注意事项 scripts/ 下的脚本应该是可独立运行的，不依赖 Agent 的上下文。用标准输入输出或命令行参数传递数据。脚本头部加 shebang 和简短注释，方便 Agent 理解用途。 ## 4. 验证 Skill 是否被正确调用：本地测试的四个动作 写完 Skill 不代表就能用。你需要验证 Agent 是否真的发现了它、是否在正确的时机加载了它、是否按预期执行了。以下四个动作按顺序做一遍。 ### 4.1 检查元数据是否被加载 在 Claude Code 中运行 `/skills` 命令（如果版本支持），或者直接问 Agent：“列出你当前可用的所有 Skill。”Agent 会返回它扫描到的 Skill 列表。如果你的 Skill 不在列表里，说明目录位置不对或 YAML 格式有误。 常见问题：YAML 前置信息缺少开头的 `---` 或结尾的 `---`，导致解析失败。或者 name 字段包含了大写字母或下划线，不符合命名规范。 ### 4.2 触发测试：用自然语言请求 不要直接说“使用 generating-db-migrations Skill”，而是用自然语言描述任务：“我需要给 users 表加一个 last_login 字段，帮我生成迁移脚本。”观察 Agent 是否自动加载了你的 Skill。 如果 Agent 没有触发，检查 description 里是否包含了用户可能用的关键词。比如用户说“加字段”，你的 description 里只写了“migration”，就可能匹配不上。把同义词都列进去：迁移、migration、schema change、alter table、加字段、改表结构。 ### 4.3 检查执行路径 Agent 触发 Skill 后，观察它是否按照 SKILL.md 里的步骤执行。比如是否先读取了模型定义文件，是否引用了 type-mapping.md，是否运行了验证脚本。 如果 Agent 跳过了某些步骤，可能是 SKILL.md 里的指令不够明确。把“读取当前模型定义文件”改成“必须首先读取 models.py 或 schema.prisma，确认当前字段列表”，用“必须”来强调关键步骤。 ### 4.4 验证输出结果 最后检查生成的迁移脚本是否正确。运行验证脚本： ```bash python scripts/validate_migration.py --file migration.sql

如果脚本报错，根据错误信息调整 SKILL.md 中的指令。比如类型映射写错了，就更新 reference/type-mapping.md。

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

这一节对照真实报错，给出排查路径。如果你在接入或使用 Skill 过程中遇到以下错误，按对应步骤检查。

5.1 401 Unauthorized

报错信息：401 Unauthorized或invalid api key。

排查步骤：检查 TaoToken Key 是否复制完整，sk- 开头后面有没有多余空格。检查 Base URL 是否填了 https://taotoken.net/api ，不要加尾部斜杠。检查 settings.json 或 auth.json 的 JSON 格式是否正确，用python -m json.tool settings.json验证。

如果 Key 确认无误但仍然 401，去控制台确认 Key 是否被禁用或额度是否用完。

5.2 local proxy failed

报错信息：local proxy failed或connection refused。

这个错误通常出现在 Claude Code 或 Codex 尝试连接本地代理时。检查你的配置里是否误填了 localhost 或 127.0.0.1 的地址。Base URL 必须是 https://taotoken.net/api ，不要填本地地址。

如果之前配置过其他代理工具，检查环境变量里是否有 HTTP_PROXY 或 HTTPS_PROXY 指向了不可用的地址。用env | grep -i proxy查看，如果有，用unset HTTP_PROXY HTTPS_PROXY清除。

5.3 reading choices 报错

报错信息：error reading choices或invalid response format。

这通常是模型 ID 填错了。检查 config.toml 或 settings.json 中的模型名是否与控制台模型列表一致。比如 claude-sonnet-4-20250514 不要写成 claude-sonnet-4 或 claude-4-sonnet。

如果模型名正确但仍然报错，可能是该模型在当前 Key 的权限范围内不可用。换一个模型试试，比如换成 gpt-4o 或 gemini-2.5-pro。

5.4 OAuth 相关报错

报错信息：OAuth token expired或authentication failed。

Codex 的 auth.json 如果同时存在 OAuth 字段和 API Key 字段，可能会冲突。确保 auth.json 里只保留 OPENAI_API_KEY 和 OPENAI_BASE_URL，删除其他认证相关字段。

如果 Claude Code 报 OAuth 错误，检查 settings.json 里是否同时配置了 ANTHROPIC_API_KEY 和 OAuth 相关字段。只保留 API Key 方式即可。

5.5 Skill 不触发

报错信息：无报错，但 Agent 不使用 Skill。

检查 Skill 目录位置：个人 Skill 在 ~/.claude/skills/ 或 ~/.codex/skills 或 ~/.config/opencode/skill/。项目 Skill 在 .claude/skills/ 或 .codex/skills/ 或 .opencode/skill/。目录名必须是 skills 或 skill，不要写成 skillz 或 Skills。

检查 SKILL.md 文件名是否全大写。必须是 SKILL.md，不是 skill.md 或 Skill.md。

检查 YAML 前置信息是否以---开头和结尾。缺少任何一个都会导致解析失败。

6. 把 Skill 用起来：从单次测试到长期编码工作流

Skill 写好了，验证也通过了，接下来是怎么在日常工作中持续使用。如果你只是偶尔用一次，直接在对话里描述任务就行。但如果你发现自己每周都要重复同样的操作，那就值得把它固化下来。

对于长期编码和 Agent 工作流，建议使用 Coding Plan 来管理多个 Skill 的加载和切换。地址是 https://taotoken.net/coding-plan ，你可以在那里看到不同套餐的调用额度和模型权限。

如果你需要验证某个模型是否适合你的 Skill 场景，可以用模型对话功能快速测试。地址是 https://taotoken.net/chat ，选好模型后直接输入触发语句，观察响应是否符合预期。

接入文档在 https://taotoken.net/doc ，里面有各工具的详细配置说明和最新模型列表。API Keys 管理在 https://taotoken.net/api-keys ，随时可以创建新 Key 或禁用旧 Key。

Claude Code 的专属接入指南在 https://taotoken.net/ClaudeCodeAnthropic ，如果你主要用 Claude Code 跑 Skill，建议先看那份文档。

最后说一个实用技巧：把项目级 Skill 提交到 git，团队成员拉取后自动生效。这样新同事入职时，不需要口头传授“我们团队是怎么做数据库迁移的”，Agent 会按照 Skill 里的步骤执行。Skill 的本质是把隐性知识显性化，让 Agent 成为团队工作流的执行者，而不是每次都要重新解释的局外人。