1. 为什么你的 TypeScript Agent 总在同一个坑里翻车
如果你用 Claude Code 或 Codex 写过 TypeScript，大概率遇到过这四种情况：Agent 上来就写代码，写完发现方向完全不对；解释一个类型体操用了三百字，你只想让它说“这个泛型收窄了”；测试跑不通它就开始瞎改，改到最后连原来的功能都挂了；三个月后回头看，utils目录里塞了四十个文件，每个都互相 import。
这不是模型不够聪明，而是缺少工程纪律的约束。Matt Pocock 的 Skills 仓库之所以被 6 万开发者订阅，核心在于它把《程序员修炼之道》《领域驱动设计》《软件设计哲学》里的原则，翻译成了 Agent 能执行的斜杠命令。它不接管你的流程，而是给你一套可组合的小工具，让你在 TypeScript 项目里逐步建立反馈循环。
我试过把这套 Skills 接到自己的 monorepo 里，配合 TaoToken 的统一 API 通道做验证，发现 Agent 的行为改善是肉眼可见的。下面我会拆解四大顽疾对应的 Skills 配置思路，给出可复制的目录结构和配置片段，并逐项验证 Agent 行为的变化。
先明确适用人群：如果你用 Claude Code、Codex 或 Cline 写 TypeScript，且希望 Agent 产出可维护的代码而不是一次性脚本，这套方法直接可用。如果你只是偶尔让 AI 补个函数，那可以先收藏，等遇到“Agent 写的代码不敢合”的时候再回来。
核心检索词先摆出来：Matt Pocock 的 AI 编程 Skills 仓库，是一套面向 TypeScript 工程的 Agent 行为约束集合，能解决对齐缺失、术语啰嗦、反馈缺失、架构腐化四类问题。它适合所有用 AI 写 TypeScript 的开发者，尤其是那些已经感受到“AI 加速了熵增”的团队。
2. 四大顽疾对应的 Skills 配置思路与目录结构
Matt 把 Skills 分成两类：User-invoked 是你手动敲斜杠命令触发的，负责编排流程；Model-invoked 是 Agent 自己判断调用的，负责执行具体纪律。关键规则是 User-invoked 可以调用 Model-invoked，但 User-invoked 之间不能互相调用，避免编排混乱。
四大顽疾的对应关系很清晰。对齐缺失用/grill-me和/grill-with-docs，让 Agent 先追问再动手；术语啰嗦用CONTEXT.md建立共享语言，一个词替代二十个词；代码跑不通用/tdd和/diagnosing-bugs，红绿重构加调试循环；项目泥球化用/improve-codebase-architecture和/to-prd，定期扫描深化机会。
安装命令只有一行：
npx skills@latest add mattpocock/skills安装器会问你装哪些 Skills、装到哪个 Agent。这里务必勾选/setup-matt-pocock-skills，它是初始化配置的入口。装完后在 Agent 里运行：
/setup-matt-pocock-skills它会问你三个问题：用什么 Issue Tracker（GitHub、Linear 还是本地文件）、triage 时用什么标签、文档保存在哪里。回答完，所有 Engineering Skills 就能正常用了。
目录结构上，Skills 默认装在 Agent 的配置目录下。以 Claude Code 为例，路径是~/.claude/skills/，每个 Skill 一个文件夹，里面是SKILL.md和可选的脚本。你的项目里需要额外维护两个文件：CONTEXT.md放领域术语表，docs/adr/放架构决策记录。这两个文件是/grill-with-docs自动更新的目标。
配置片段方面，如果你用 Cline 的 MCP 模式接入，需要在cline_mcp_settings.json里声明 Skills 的路径。但更推荐直接用 Claude Code 的原生 Skills 支持，省去 MCP 的转发层。下面是一个最小化的settings.json片段，放在项目根目录的.claude/下：
{ "skills": { "directory": ".claude/skills", "autoInvoke": ["tdd", "diagnosing-bugs", "code-review", "domain-modeling"], "userInvoke": ["grill-me", "grill-with-docs", "to-prd", "to-issues", "triage", "improve-codebase-architecture"] }, "context": { "domainGlossary": "CONTEXT.md", "adrDirectory": "docs/adr" } }这个片段的作用是告诉 Agent：哪些 Skill 可以自动触发，哪些必须等你手动敲。autoInvoke里的四个都是 Model-invoked，Agent 在写代码或审查时会自己调用；userInvoke里的六个需要你主动输入斜杠命令。
如果你用 Codex，配置写在auth.json同级的config.toml里。三件套必须写全：Base URL、Key、Model ID。Base URL 填https://taotoken.net/api，Key 从 TaoToken 控制台生成，Model ID 按你实际用的模型填。这样 Codex 的请求会走统一通道，Skills 的调用日志也能在 TaoToken 的 console 里看到。
3. 可复制的 Skills 配置片段与 TaoToken 接入
这一节给出完整的配置片段，你可以直接复制到项目里。先解决 TaoToken 的接入，因为所有 Agent 请求都要经过这个通道，配置错了后面全白搭。
TaoToken 的 API 地址是https://taotoken.net/api，注意不要加 UTM 参数，那是给网页链接用的。Key 在控制台的 API Keys 页面生成，生成后复制到环境变量里，不要硬编码在配置文件里。推荐的做法是在项目根目录建一个.env.local：
TAOTOKEN_API_KEY=sk-你的实际key TAOTOKEN_BASE_URL=https://taotoken.net/api然后在 Claude Code 的settings.json里引用环境变量：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "${TAOTOKEN_API_KEY}" }, "skills": { "directory": ".claude/skills", "autoInvoke": ["tdd", "diagnosing-bugs", "code-review", "domain-modeling"], "userInvoke": ["grill-me", "grill-with-docs", "to-prd", "to-issues", "triage", "improve-codebase-architecture"] } }如果你用 Codex，config.toml这样写：
[model] provider = "taotoken" model_id = "claude-sonnet-4-20250514" base_url = "https://taotoken.net/api" [auth] api_key_env = "TAOTOKEN_API_KEY"Cline 的 MCP 配置稍微不同，需要在cline_mcp_settings.json里声明：
{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_API_KEY": "${env:TAOTOKEN_API_KEY}", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } } } }三件套写全了：Base URL 是https://taotoken.net/api，Key 走环境变量，Model ID 按你实际用的填。这样配置的好处是，Skills 的每次调用都会经过 TaoToken，你可以在 console 里看到 token 消耗和调用链路，方便排查是哪个 Skill 在烧钱。
接下来是CONTEXT.md的初始模板。这个文件是共享语言的核心，/grill-with-docs会自动更新它。初始内容可以很简单：
# 领域术语表 ## 核心概念 - **Materialization Cascade**：课程中某个 lesson 被标记为 real 后，触发文件系统写入和依赖更新的连锁过程。 - **Deep Module**：接口简单但功能丰富的模块，对外暴露少量方法，内部处理复杂逻辑。 - **Vertical Slice**：从 UI 到数据库的完整功能切片，可独立认领和交付。 ## 命名约定 - 变量和函数用 camelCase，类型和接口用 PascalCase。 - 文件名用 kebab-case，测试文件加 `.test.ts` 后缀。 - 避免使用 `data`、`info`、`manager` 这类泛化词。这个文件建好后，Agent 在解释代码时会优先用术语表里的词。比如它不会说“当课程里的某个课时被设置为真实状态时，会触发一系列文件系统操作”，而是直接说“Materialization Cascade 有问题”。一个词替代二十个词，token 消耗直接降下来。
ADR 目录也要建好，路径是docs/adr/。每个 ADR 一个文件，命名格式是0001-use-deep-modules.md。/grill-with-docs在追问过程中如果发现架构决策，会自动往这里写。你不需要手动维护，但要知道它在哪，方便 review。
4. 逐项验证 Agent 行为改善的操作步骤
配置好之后，怎么验证 Agent 真的变乖了？我按四大顽疾逐项给操作步骤和预期结果。
第一项验证对齐缺失。找一个你正准备让 Agent 写的新功能，比如“给课程模块加一个进度追踪”。不要直接说“帮我写”，而是先敲：
/grill-with-docs 我要给课程模块加进度追踪，你先追问我一轮Agent 会开始追问：进度是按 lesson 还是按 section 算？完成状态存在哪？要不要支持离线？追问过程中它会更新CONTEXT.md，把“进度追踪”相关的术语定下来。你回答完所有问题后，再让它动手。对比一下：以前你直接说需求，Agent 写出来的东西大概率要返工；现在先追问，返工率明显下降。
第二项验证术语啰嗦。打开CONTEXT.md，确认里面已经有至少五个核心术语。然后随便问 Agent 一个代码问题，比如“这个函数为什么报类型错误”。观察它的回答里有没有用术语表里的词。如果它说“Materialization Cascade 的类型收窄有问题”，说明共享语言生效了；如果它还在用二十个词解释一个概念，检查CONTEXT.md的路径是否配对了。
第三项验证反馈循环。让 Agent 用/tdd写一个新函数：
/tdd 给 Materialization Cascade 加一个防抖函数，先写失败的测试Agent 会先写测试文件，运行测试确认失败（红），然后写实现让测试通过（绿），最后重构。你可以在终端里看到测试从 fail 到 pass 的过程。如果它跳过测试直接写实现，说明autoInvoke里没加tdd，回去检查配置。
第四项验证架构腐化。运行：
/improve-codebase-architectureAgent 会扫描代码库，找出“深化机会”，生成一个 HTML 报告。报告里会列出哪些模块接口太浅、哪些依赖关系太乱。你选一个改进项，让它执行。Matt 建议每隔几天跑一次，我实测下来，每周跑一次就能把泥球化速度压住。
验证请求是否走通 TaoToken，可以在 console 里看调用日志。每次 Skills 触发都会有一条记录，包含 Skill 名称、token 消耗、耗时。如果发现某个 Skill 消耗异常高，比如/grill-with-docs一次烧了 50k token，检查一下是不是CONTEXT.md太大或者追问轮次太多。
成功结果的标准是：Agent 在写代码前会主动追问，解释代码时用术语表，写实现前先写测试，定期提醒你跑架构扫描。这四条都做到，说明 Skills 配置生效了。
5. 本篇常见报错排查
配置过程中最容易遇到四类报错，我逐个给排查路径。
第一类：401 Unauthorized。报错信息通常是{"error":{"type":"authentication_error","message":"invalid api key"}}。原因是你 TaoToken 的 Key 没配对，或者环境变量没加载。排查步骤：先在终端里echo $TAOTOKEN_API_KEY，确认输出的是sk-开头的完整 key；然后检查settings.json里的${TAOTOKEN_API_KEY}有没有写错，Claude Code 支持环境变量插值，但 Codex 的config.toml要用api_key_env字段而不是直接写 key。如果还报 401，去 TaoToken 控制台的 API Keys 页面确认 key 没过期、没被禁用。
第二类：local proxy failed。报错信息是Error: connect ECONNREFUSED 127.0.0.1:xxxx。这是本地代理配置冲突，常见于你之前配过其他工具的代理，环境变量里残留了HTTP_PROXY或HTTPS_PROXY。排查步骤：env | grep -i proxy看有没有残留，有的话unset HTTP_PROXY HTTPS_PROXY清掉。然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api而不是http://localhost:xxxx。TaoToken 是直连通道，不需要本地代理转发。
第三类：reading choices 报错。报错信息是TypeError: Cannot read properties of undefined (reading 'choices')。这是响应格式不匹配，通常发生在你用 OpenAI 兼容模式调 Claude 模型时。排查步骤：确认 Model ID 填对了，Claude 系列要用claude-sonnet-4-20250514这种格式，不要填gpt-4。然后检查 Base URL 末尾有没有多余的斜杠，https://taotoken.net/api后面不要加/v1，TaoToken 的通道会自动路由。
第四类：OAuth 相关报错。报错信息是OAuth token expired或refresh token failed。如果你用 Claude Code 的原生登录而不是 API Key，会遇到这个。排查步骤：Skills 仓库推荐用 API Key 模式，不要用 OAuth。在settings.json里删掉oauth相关字段，改用ANTHROPIC_API_KEY。如果你之前登录过，运行claude logout清掉缓存的 token，然后重新用 API Key 配置。
还有一个隐蔽的坑：Skills 装完后/setup-matt-pocock-skills跑不起来。检查~/.claude/skills/目录下有没有setup-matt-pocock-skills文件夹，没有的话重新跑npx skills@latest add mattpocock/skills，安装时勾选它。如果文件夹在但命令不识别，重启一下 Agent 进程，Skills 的注册需要重新加载。
6. 把工程纪律变成可执行命令
Matt Pocock 这套 Skills 最值钱的地方，不是它提供了多少个斜杠命令，而是它把“先追问、建术语、红绿重构、每天投资设计”这四句话，变成了 Agent 能执行的具体动作。你不需要记住所有 Skill 的名字，只需要在遇到对应场景时知道该敲哪个命令。
配合 TaoToken 的统一通道，你可以把 Claude Code、Codex、Cline 都接到同一个 Key 上，Skills 的调用日志集中在一个 console 里看。这样排查问题的时候不用来回切换工具，token 消耗也一目了然。
如果你只想先试一个 Skill，我建议从/grill-with-docs开始。找一个你正准备让 Agent 写的新功能，先让它追问一轮，感受一下“对齐之后再动手”的差别。等你习惯了这种节奏，再把/tdd和/improve-codebase-architecture加进来。
长期用 AI 写 TypeScript 的话，Coding Plan 比按量付费更划算，适合每天都有 Agent 调用需求的场景。配置入口在 TaoToken 的 console 里，选好套餐后把 Key 换到settings.json里就行。
最后留一个实用技巧：把CONTEXT.md加到 git 的 pre-commit hook 里，每次提交前检查术语表有没有更新。如果 Agent 在对话里定义了新术语但没写进CONTEXT.md，hook 会提醒你补上。这样共享语言不会随着对话结束而丢失，下次开新会话时 Agent 还能接着用。
