1. 为什么你的 AI 写 TypeScript 总像实习生我最近在重构一个中型前端项目让 AI 帮我写一个泛型工具函数。结果它给我返回了any满天飞的代码类型断言乱用连readonly修饰符都懒得加。那一刻我意识到AI 不是不会写 TypeScript而是不知道你们团队的 TypeScript 规范长什么样。这就是 mattpocock/skills 这个仓库火起来的根本原因。它把资深工程师脑子里那些默认规则——比如优先用type而不是interface、避免any改用unknown配合类型守卫、用as const收窄字面量类型——全部写成了 AI 能直接读取的 SKILL.md 文件。你不需要每次对话都重复一遍请遵循最佳实践AI 会在需要时自动加载对应的技能文件。这个仓库目前约 129K Star作者 Matt Pocock 是 TypeScript 核心贡献者仓库里每个技能文件夹都遵循文件夹 SKILL.md的极简格式。SKILL.md 里通常包含四个部分何时使用、指令步骤、反模式、示例。其中反模式部分往往比正面规则更重要因为它明确告诉 AI不要做什么。适合谁用三类人最该关注一是团队里负责代码规范的 Tech Lead可以把规范固化成 Skill 让全员 AI 助手统一执行二是独立开发者想让 AI 按自己的习惯产出代码三是正在学 TypeScript 的人通过阅读 SKILL.md 反向学习资深工程师的思维模式。但这里有个现实问题SKILL.md 加载后AI 每次执行任务都要调用模型 API。如果你用多个 AI 工具Claude Code、Cursor、Codex CLI每个工具都要单独配置 Key 和通道管理起来很麻烦。我试过在三个工具里分别填 Key结果改一次配置要改三处。所以这篇会重点讲怎么用 TaoToken 统一 Key 打通整个 SKILL.md 工作流让你只维护一份配置。2. TaoToken 统一 Key 与 API 通道配置TaoToken 在这里扮演的角色是统一的模型接入层。你不需要在每个 AI 工具里分别填不同的 Key而是用同一个 Key 通过同一个 API 地址访问模型。这样当你在 Claude Code 里加载了 SKILL.md切换到 Cursor 时不需要重新配置直接复用同一套凭证。先明确三个核心参数后面所有配置都围绕它们展开参数值说明Base URLhttps://taotoken.net/api所有请求的统一入口API Key在控制台创建格式类似sk-xxxx只显示一次Model ID按需选择如claude-sonnet-4-20250514等获取 Key 的步骤访问控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole登录后在 API Keys 页面点击创建。创建时建议给 Key 起个有意义的名字比如skills-workflow-dev方便后续区分不同用途。Key 只在创建时完整显示一次务必立即复制保存。注意不要把 Key 硬编码在会提交到 Git 的文件里。推荐用环境变量或本地配置文件并在.gitignore中排除。如果你用的是 Claude Code它读取的是~/.claude/settings.json或项目级的.claude/settings.json。配置片段如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Codex CLI它读取~/.codex/auth.json配置格式不同{ OPENAI_API_KEY: sk-你的Key, OPENAI_BASE_URL: https://taotoken.net/api }如果你用的是 Cline 或 Roo Code 这类 VS Code 插件在设置面板里选择 OpenAI Compatible 提供商然后填入 Base URL 和 KeyModel ID 手动输入即可。这里有个关键点SKILL.md 的加载和 API 通道是两件独立的事。SKILL.md 决定 AI怎么想API 通道决定 AI用哪个模型想。TaoToken 解决的是后者让你不用为每个工具单独申请 Key。配置完成后你可以用一条 curl 命令验证通道是否通畅curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }如果返回包含OK的 JSON说明通道正常。如果返回 401检查 Key 是否复制完整如果返回local proxy failed检查 Base URL 是否写成了https://taotoken.net/api而不是其他路径。3. 克隆 skills 仓库并加载 SKILL.md 的完整配置现在进入实操环节。目标是把 mattpocock/skills 仓库克隆到本地让 AI 工具能读取其中的 SKILL.md并完成一次 TypeScript 示例任务的验证。第一步克隆仓库。推荐用 Git Submodule 方式这样你的项目可以跟踪 skills 仓库的版本cd your-project git submodule add https://github.com/mattpocock/skills.git .skills/mattpocock git submodule update --init --recursive如果你只是想快速试用直接 clone 到临时目录也行git clone https://github.com/mattpocock/skills.git /tmp/mattpocock-skills ls /tmp/mattpocock-skills你会看到类似这样的目录结构mattpocock-skills/ ├── tdd/ │ └── SKILL.md ├── typescript/ │ └── SKILL.md ├── debug-mode/ │ └── SKILL.md ├── code-review/ │ └── SKILL.md └── skill-anatomy/ └── SKILL.md第二步把需要的 Skill 复制到项目里。假设你只关心 TypeScript 和 TDD 两个技能mkdir -p .skills cp -r /tmp/mattpocock-skills/typescript .skills/ cp -r /tmp/mattpocock-skills/tdd .skills/第三步配置 AI 工具读取.skills目录。不同工具的加载方式不同Claude Code 会自动扫描项目根目录及子目录下的SKILL.md文件。你只需要在项目根目录创建.claude/settings.json确保工作目录包含.skills文件夹即可。如果没自动加载可以在对话开头说一句请读取 .skills/typescript/SKILL.md 并遵循其中的规范。Cursor 需要在.cursorrules或项目设置中显式引用。你可以在.cursorrules里写请参考 .skills/typescript/SKILL.md 中的 TypeScript 编码规范。 请参考 .skills/tdd/SKILL.md 中的测试驱动开发流程。Codex CLI 通过AGENTS.md文件加载上下文。在项目根目录创建AGENTS.md内容如下## Skills - TypeScript 规范读取 .skills/typescript/SKILL.md - TDD 流程读取 .skills/tdd/SKILL.md第四步验证 SKILL.md 是否被正确读取。这里用一个具体的 TypeScript 任务来测试。在项目里创建一个测试文件src/type-test.ts内容留空然后向 AI 发起请求请根据 .skills/typescript/SKILL.md 的规范实现一个函数 接收一个对象数组返回按指定 key 分组的结果。 要求类型安全不使用 any。如果 SKILL.md 被正确加载AI 返回的代码应该体现以下特征使用type而非interface、泛型约束清晰、返回类型显式标注、没有any。如果 AI 返回的代码里出现了any或as any说明 SKILL.md 没有被读取需要检查路径配置。第五步验证 TDD Skill。让 AI 执行一个完整的 TDD 循环请根据 .skills/tdd/SKILL.md 的流程为上面的分组函数编写测试。 先写失败的测试再实现代码让测试通过。正确的输出应该包含先给出测试文件此时运行会失败然后给出实现代码最后说明如何运行测试验证。如果 AI 直接给了实现代码而没有先写测试说明 TDD Skill 没生效。4. 验证请求与成功结果对照配置完成后你需要一套可复现的验证动作来确认整条链路通畅。我整理了一个三步验证法每步都有明确的成功标志。验证一API 通道连通性用 curl 直接请求 TaoToken 的 API 端点curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 50, messages: [{role: user, content: 只回复通道正常}] } | head -c 200成功标志返回 JSON 中包含通道正常字样。如果返回{error:{type:authentication_error...}}说明 Key 无效如果返回local proxy failed说明 Base URL 配置有误。验证二SKILL.md 被读取在项目里创建一个最小测试。先确认.skills/typescript/SKILL.md存在cat .skills/typescript/SKILL.md | head -20你应该能看到类似这样的内容# TypeScript Skill ## When to use 当用户要求编写或重构 TypeScript 代码时。 ## Instructions 1. 优先使用 type 而非 interface 2. 避免 any使用 unknown 配合类型守卫 3. 显式标注函数返回类型 ...然后向 AI 发起请求要求它复述 SKILL.md 中的规则。如果 AI 能准确说出优先使用 type 而非 interface说明文件被读取。验证三端到端任务执行这是最关键的验证。给 AI 一个完整的 TypeScript 任务观察输出是否符合 SKILL.md 规范。我用的测试任务是实现一个groupBy函数// 期望 AI 产出的代码风格 type GroupByResultT, K extends keyof T Recordstring, T[]; function groupByT, K extends keyof T( items: T[], key: K ): GroupByResultT, K { return items.reduceGroupByResultT, K((acc, item) { const groupKey String(item[key]); if (!acc[groupKey]) { acc[groupKey] []; } acc[groupKey].push(item); return acc; }, {}); }成功标志AI 返回的代码中函数有显式返回类型标注、泛型约束使用了extends keyof T、没有出现any、使用了type定义类型别名。如果 AI 返回了function groupBy(items: any[], key: string): any说明 SKILL.md 完全没生效。提示如果验证三失败但验证二成功说明 SKILL.md 被读取了但 AI 没有遵循。这时候需要检查 SKILL.md 中的反模式部分是否足够明确。Matt Pocock 的原始文件里反模式写得很具体比如不要使用 any即使是临时占位也不行。5. 常见报错排查401、local proxy failed、reading choices这一节整理我在配置过程中实际踩过的坑每个报错都给出原因和修复方法。报错一401 authentication_error完整报错信息{ error: { type: authentication_error, message: invalid x-api-key } }原因Key 无效或未正确传递。三种可能Key 复制时漏了字符、环境变量名写错、请求头字段名不对。排查步骤先用echo $ANTHROPIC_API_KEY确认环境变量已设置。然后检查请求头Anthropic 格式用x-api-keyOpenAI 兼容格式用Authorization: Bearer sk-xxx。如果你在 Claude Code 里配置确认settings.json中的ANTHROPIC_API_KEY字段名拼写正确。报错二local proxy failed完整报错信息Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:8080原因Base URL 配置错误工具试图连接本地代理而不是 TaoToken 的地址。常见于从其他配置迁移时残留了旧的 Base URL。排查步骤检查所有配置文件中的 Base URL 字段。Claude Code 检查ANTHROPIC_BASE_URLCodex 检查OPENAI_BASE_URLCline 检查设置面板中的 Base URL。正确值应该是https://taotoken.net/api注意不要多加/v1后缀部分工具会自动拼接。报错三reading choices of undefined完整报错信息TypeError: Cannot read properties of undefined (reading choices)原因API 返回格式与工具预期不匹配。通常是因为工具用的是 OpenAI 格式但请求发到了 Anthropic 格式的端点或者反过来。排查步骤确认你的工具使用哪种 API 格式。Claude Code 用 Anthropic 格式/v1/messagesCline/Codex 用 OpenAI 格式/v1/chat/completions。TaoToken 的 Base URL 是https://taotoken.net/api工具会自动拼接对应的路径。如果工具支持手动指定格式确保选择正确。报错四OAuth token expired完整报错信息OAuth token has expired. Please re-authenticate.原因某些工具如 Claude Code默认使用 OAuth 登录但配置了 API Key 后仍尝试 OAuth 流程。排查步骤在 Claude Code 中运行claude logout清除 OAuth 状态然后确认settings.json中只配置了ANTHROPIC_API_KEY而没有 OAuth 相关字段。如果问题依旧检查是否有全局的~/.claude.json覆盖了项目配置。报错五SKILL.md not found完整报错信息Warning: SKILL.md not found in .skills/typescript/原因文件路径不对或文件名大小写不匹配。Linux 系统区分大小写SKILL.md和skill.md是不同的文件。排查步骤用find . -name SKILL.md确认文件实际位置。如果文件在.skills/mattpocock/typescript/SKILL.md那你的引用路径也要对应调整。建议在项目根目录统一用.skills/作为技能目录避免多层嵌套。6. 让 SKILL.md 工作流真正跑起来配置和排障都完成后最后一步是让这套工作流融入日常开发。我的做法是在项目根目录放一个AGENTS.md把所有 Skill 的加载规则写清楚这样无论用哪个 AI 工具只要它读取AGENTS.md就能找到对应的 SKILL.md。AGENTS.md的内容可以这样写# AI Agent 配置 ## 技能加载 - TypeScript 编码规范读取 .skills/typescript/SKILL.md - 测试驱动开发流程读取 .skills/tdd/SKILL.md - 代码审查清单读取 .skills/code-review/SKILL.md ## API 通道 - Base URL: https://taotoken.net/api - 模型: claude-sonnet-4-20250514 - Key 通过环境变量 ANTHROPIC_API_KEY 注入这样配置的好处是团队新成员克隆项目后只需要设置一次环境变量所有 AI 工具都能自动读取同一套 Skill 和同一套 API 通道。不需要每个人单独申请 Key也不需要手动同步 SKILL.md 文件。如果你需要长期在多个项目间切换建议把 Skill 仓库作为 Git Submodule 统一管理每个项目引用同一个 submodule 地址。更新 Skill 时只需要在 submodule 里 pull 最新版本所有项目同步生效。对于需要频繁调用模型进行代码生成和审查的场景Coding Plan 提供了更稳定的调用额度https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan。如果你只是想先验证模型对话效果可以直接在模型对话页面测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocAPI Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys。最后分享一个实用技巧SKILL.md 不是写一次就完事的。每次 AI 没有遵循规范时把那段对话记录下来回头修改 SKILL.md 中对应的指令或反模式。Matt Pocock 的仓库之所以质量高就是因为每个 Skill 都经过了大量实际使用的迭代。你的项目规范也一样让它随着使用不断进化。