1. 从「写 Prompt」到「造 Skill」：Agentic 软件工程到底在解决什么问题

如果你最近在折腾 Claude Code、Codex CLI 或者带工具调用的 Agent，大概率会遇到一个很具体的困境：模型本身很强，但每次开新会话，它都像失忆一样，你得重新解释项目结构、代码规范、提交习惯、测试怎么跑。写 Prompt 写到怀疑人生，本质上是因为你把「流程知识」塞进了对话里，而对话是会过期的。

Agentic 软件工程的核心转变，就是把「怎么做事」从对话里搬出来，变成 Agent 能反复加载的结构化资产。这个资产就是 Skill。它不是一段更长的 Prompt，而是一个文件夹加一份 SKILL.md，里面写清楚：什么时候用这个技能、按什么顺序执行、哪些坑不能踩、哪些步骤可以直接调脚本。模型先读 name 和 description 判断要不要加载，需要时才读正文，再需要时才读细节文件——这就是渐进式披露（Progressive Disclosure）。

这套方法适合谁？适合那些用 AI 反复做同类事情的人：CRUD 接口生成、前端组件迁移、测试用例补全、数据库变更脚本。不太适合一次性脚本或者完全无结构的探索。判断标准很简单：如果你发现自己在三次不同的会话里说了三遍同样的规则，那这条规则就该变成 Skill。

而要让 Skill 真正跑起来，Agent 必须能访问文件系统、代码仓库和命令行。光在聊天框里问「帮我写个函数」不叫工程级开发。所以你需要一个能执行代码的 Agent 环境，以及一个稳定的模型调用通道。下面我会用 TaoToken 作为统一 Key 和 API 通道，把多工具接入、Skill 目录结构、配置片段和一次完整工作流跑通全部串起来，你可以直接照着复现。

2. TaoToken 统一 Key 前置准备：Base URL、API Key 与模型 ID 三件套

在开始写 Skill 之前，先把通道打通。TaoToken 的作用是给你一个统一的 API 入口，这样 Claude Code、Codex CLI、Cline 这些工具不用各自维护一套鉴权逻辑，换模型也不用改代码。你需要准备三样东西：Base URL、API Key、Model ID。

Base URL 统一用https://taotoken.net/api，注意这个地址不带任何查询参数。API Key 在控制台的 API Keys 页面生成，格式通常是一串以sk-开头的字符串。Model ID 取决于你要调用的模型，比如claude-sonnet-4-20250514或者gpt-4o这类标识，具体以文档里的模型列表为准。

我试过把这套配置同时接到 Claude Code 和 Cline 上，关键点是三个工具都认「Base URL + Key + Model ID」这个组合，只是配置文件位置和字段名不同。下面先给一个通用的环境变量写法，适合大多数 CLI 工具：

export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_API_KEY="sk-你的实际Key" export TAOTOKEN_MODEL="claude-sonnet-4-20250514"

如果你用的是 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 用的是ANTHROPIC_前缀，这是它内部的约定，不要写成TAOTOKEN_。如果你用的是 Codex CLI，它读的是~/.codex/auth.json，格式又不一样：

{ "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "sk-你的实际Key", "model": "gpt-4o" }

Cline 这类 VS Code 插件通常在设置界面里填 Base URL 和 Key，Model ID 从下拉框选或者手动输入。三件套缺一不可，尤其是 Model ID 写错会直接报 404 或者 model not found。

这里有个容易忽略的点：Base URL 末尾不要加/v1或者/chat/completions，TaoToken 的网关会自动路由。我踩过的坑是手动拼了/v1/chat/completions，结果路径重复导致 404。统一用https://taotoken.net/api就行。

配置完成后，先别急着写 Skill，用一条最简单的请求验证通道是否通。可以用 curl：

curl -s 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": "user", "content": "回复 OK 两个字母"}], "max_tokens": 16 }'

如果返回的 JSON 里有choices数组且内容包含 OK，说明通道正常。如果返回 401，检查 Key 是否复制完整；如果返回 model not found，检查 Model ID 拼写。这一步过了，再往下做 Skill 才有意义。

3. 可复制的 Skill 目录结构与 settings 配置片段

Skill 的本质是一个文件夹，里面至少有一个 SKILL.md。但要让 Agent 真正按流程执行，光有说明文档不够，还需要 plan 模板、checklist 和可执行脚本。下面是我实际在用的目录结构，你可以直接复制：

skills/ ├── api-crud/ │ ├── SKILL.md │ ├── plan.md │ ├── checklist.md │ └── scripts/ │ ├── gen_route.py │ └── gen_test.py ├── frontend-migrate/ │ ├── SKILL.md │ ├── plan.md │ └── checklist.md └── db-migration/ ├── SKILL.md └── scripts/ └── diff_schema.py

SKILL.md 的头部必须包含 name 和 description，这是 Agent 决定是否加载的依据。description 要写得足够具体，让模型能区分相似技能。比如：

--- name: api-crud description: 当需要为已有数据模型生成 RESTful CRUD 接口时使用，包含路由、参数校验、单元测试和 OpenAPI 注释。不适用于 GraphQL 或纯前端组件。 --- ## 执行流程 1. 读取 models/ 目录下目标模型的定义文件 2. 运行 scripts/gen_route.py 生成路由骨架 3. 按 checklist.md 逐项校验参数校验、错误码、分页 4. 运行 scripts/gen_test.py 生成测试用例 5. 执行 pytest 确认全部通过后再提交

注意 description 里明确写了「不适用于 GraphQL 或纯前端组件」，这是为了防止模型误加载。渐进式披露的关键就在这里：元信息只告诉模型「这个技能是干嘛的」，正文才写具体步骤，细节文件按需读取。

接下来是 settings 配置。如果你用 Claude Code，除了前面说的~/.claude/settings.json，还可以在项目根目录放一个.claude/settings.json覆盖全局配置。项目级配置适合把 Skill 目录和模型参数绑定在一起：

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

如果你用 Cline 的 MCP 模式，配置写在cline_mcp_settings.json里，Base URL 和 Key 填在 provider 字段：

{ "mcpServers": { "taotoken-agent": { "command": "npx", "args": ["-y", "@taotoken/agent-bridge"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的实际Key", "TAOTOKEN_MODEL": "claude-sonnet-4-20250514" } } } }

Codex CLI 的 auth.json 前面已经给过，这里再强调一次：三个工具都认 Base URL、Key、Model ID 三件套，只是字段名不同。把这三件套写对，通道就通了。Skill 目录结构加上 settings 配置，构成了 Agentic 工作流的基础设施。下一步是让 Agent 真正跑起来。

4. 完整工作流跑通：从评估失败点到验证请求成功

现在把 Skill 和通道串起来，跑一次完整工作流。我以一个「为 User 模型生成 CRUD 接口」的任务为例，走一遍 Agent-first 的六步流程。

Step 0 是准备执行环境。确认你的 Agent 能访问文件系统、代码仓库和命令行。Claude Code 和 Codex CLI 默认都支持，Cline 需要开启终端执行权限。

Step 1 是评估优先。不要一上来就让 Agent 写功能，先给它一个代表性任务，观察它在哪里反复出错。比如让它「为 User 模型生成一个 GET /users 接口」，看它是否漏掉分页、是否忘记参数校验、是否把错误码写错。这些失败点就是 Skill 的设计起点。

Step 2 是把流程固化成 Skill。把刚才观察到的失败点写进 SKILL.md 和 checklist.md。比如发现它总是忘记分页，就在 checklist 里加一条「确认 limit 和 offset 参数存在且默认值合理」。

Step 3 是渐进式披露。SKILL.md 正文只写核心流程，细节放到 plan.md 和 checklist.md，脚本放到 scripts/ 目录。Agent 先读 description 判断要不要加载，加载后读正文，执行到某一步再读细节文件。

Step 4 是让代码替代 token。排序、解析、提取、转换这类确定性操作，写成 Python 脚本让 Agent 调用，而不是让模型用自然语言硬算。比如gen_route.py负责生成路由骨架，模型只负责判断何时调用、如何组合结果。

Step 5 是为机器设计工程结构。问自己：Agent 会不会误用这个 Skill？name 是否清晰到足以触发？description 是否能区分相似 Skill？比如api-crud和db-migration的 description 必须明确区分，否则模型可能加载错。

Step 6 是与 Agent 一起迭代。任务成功后让它总结成功路径写回 Skill，任务失败后让它反思失败原因修正 Skill。Skill 是活文档，不是一次性配置。

现在跑一次验证请求。假设 Skill 目录已经就位，配置也写好了，在 Claude Code 里输入：

使用 api-crud skill，为 models/user.py 生成完整的 CRUD 接口，包括路由、参数校验和测试。

Agent 会先读skills/api-crud/SKILL.md的 description，判断需要加载，然后读正文，按流程执行：读取模型定义、运行gen_route.py、按 checklist 校验、运行gen_test.py、执行 pytest。如果全部通过，你会看到类似这样的输出：

[skill] api-crud loaded [exec] python skills/api-crud/scripts/gen_route.py models/user.py [exec] python skills/api-crud/scripts/gen_test.py models/user.py [test] pytest tests/test_user_api.py [test] 12 passed in 1.34s [done] CRUD endpoints generated and verified

如果中途失败，比如 pytest 报错，Agent 会根据 checklist 逐项排查，而不是直接宣布完成。这就是 Skill 驱动和纯 Prompt 驱动的区别：流程被固化，失败有据可查。

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

即使配置写对了，实际跑的时候还是会遇到各种报错。下面是我遇到过的几类典型问题，对照着排查。

401 Unauthorized 是最常见的。原因通常是 API Key 没复制完整、Key 过期、或者 Base URL 写错导致请求发到了错误的网关。排查步骤：先用 curl 直接请求https://taotoken.net/api/v1/chat/completions，确认 Key 本身有效；再检查 settings.json 里的ANTHROPIC_API_KEY或OPENAI_API_KEY字段名是否正确；最后确认 Base URL 没有多余路径。

local proxy failed 通常出现在 Cline 或某些 VS Code 插件里。原因是插件尝试走本地代理，但代理没启动或者端口冲突。解决办法是在插件设置里关闭「使用本地代理」选项，直接填 Base URL。如果必须用代理，确认代理进程在运行且端口没被占用。

reading choices 报错一般长这样：Cannot read properties of undefined (reading 'choices')。这说明请求返回的 JSON 结构里没有choices字段，通常是网关返回了错误信息但被工具当成正常响应解析。排查方法：用 curl 看原始返回，如果返回的是{"error": {"message": "..."}}，说明请求本身有问题，可能是 Model ID 写错或者请求体格式不对。

OAuth 相关报错出现在 Claude Code 首次登录时。如果你已经配了ANTHROPIC_API_KEY，就不需要走 OAuth 流程。如果工具仍然提示 OAuth，检查是否有旧的凭据缓存，删掉~/.claude/下的凭据文件重新配置。注意不要同时配 OAuth 和 API Key，会冲突。

还有一个隐蔽的坑：Model ID 大小写敏感。claude-sonnet-4-20250514和Claude-Sonnet-4-20250514在某些网关下会被当成不同模型。统一用小写。

排查顺序建议：先 curl 验证通道，再检查配置文件字段名，最后看工具日志。大部分问题出在 Base URL 和 Key 上，Skill 本身的问题反而少。

6. 把 Skill 变成工程资产：统一 Key 下的长期协作方式

走到这里，你已经有了一个能跑通的 Agentic 工作流：TaoToken 提供统一 Key 和 API 通道，Skill 目录提供结构化流程，settings 配置把两者绑在一起。但真正让这套东西产生复利的是迭代。

每次 Agent 成功完成一个复杂任务，让它把成功路径写回 SKILL.md。比如它发现先跑gen_route.py再跑gen_test.py的顺序比反过来更稳定，就把这个顺序固化进正文。每次失败，让它反思失败原因并修正 checklist，而不是骂模型。这样 Skill 会越来越厚，但加载时仍然是按需的，不会拖垮上下文。

从项目管理角度看，重心从「任务拆分给人」变成了「管理 AI 的工作方式」。你需要关注的是：如何防止它过早宣布完成、如何避免上下文漂移、如何让它在多次会话中保持一致理解。Skill、plan、checklist、脚本，本质上都是在为 AI 建立一种可持续工作的认知环境。

如果你想把模型对话、Coding Plan 和 API Keys 管理串起来，可以从这几个入口进：模型对话用来快速验证模型行为，Coding Plan 适合长期编码和 Agent 任务，API Keys 用来生成和管理你的统一 Key。接入文档里有各工具的详细配置说明。把这套工作流跑顺之后，你会发现效率提升不是线性的，而是经验复利式的——每沉淀一个 Skill，下一次同类任务就少踩一批坑。