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_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_MODELclaude-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 和 KeyModel ID 从下拉框选或者手动输入。三件套缺一不可尤其是 Model ID 写错会直接报 404 或者 model not found。这里有个容易忽略的点Base URL 末尾不要加/v1或者/chat/completionsTaoToken 的网关会自动路由。我踩过的坑是手动拼了/v1/chat/completions结果路径重复导致 404。统一用https://taotoken.net/api就行。配置完成后先别急着写 Skill用一条最简单的请求验证通道是否通。可以用 curlcurl -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.pySKILL.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 会不会误用这个 Skillname 是否清晰到足以触发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下一次同类任务就少踩一批坑。