尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

薄 Harness,厚 Skills:用 Markdown 把 AI 编程智能体武装到牙齿

薄 Harness,厚 Skills:用 Markdown 把 AI 编程智能体武装到牙齿 1. 为什么你的 Claude Code 越用越“笨”从薄 Harness 厚 Skills 说起很多人第一次用 Claude Code 这类 AI 编程智能体时都会经历一个相似的曲线前几天觉得惊艳一周后开始觉得它“变笨了”。你让它改一个鉴权逻辑它顺手把无关的日志格式也改了你让它按团队规范写单测它每次给的风格都不一样你明明在项目里已经有一套成熟的发布流程它却总要从零开始猜。问题往往不在模型。同一个模型在两个人手里产出效率能差出十倍差距来自包裹模型的那层“外壳”也就是 Harness基座。薄 Harness 厚 Skills 的核心主张很朴素基座只负责跑模型、读写文件、管理上下文、执行安全策略这四件事越薄越好而领域知识、流程规范、工具调用约定全部沉淀成可复用的 Markdown 技能文件Skills。这样你不改一行框架代码就能让智能体学会一项新技能。这套思路特别适合两类人一是个人开发者想让自己的 Claude Code 记住项目里的各种“潜规则”二是团队想把代码规范、评审流程、发布检查清单变成智能体能自动执行的资产。下面我会给你一套可以直接抄的 Skills 目录结构、Markdown 技能描述规范以及用真实任务验证技能是否生效的检查步骤。全程围绕 Claude Code 和 Markdown 展开跟着做就能跑通。2. 前置准备TaoToken 接入 Claude Code 的薄基座配置在写 Skills 之前得先让 Claude Code 能稳定跑起来。我实测下来用 TaoToken 做接入层比较省心它的 API 兼容 Anthropic 官方格式Claude Code 不用改任何代码就能对接。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。先说清楚一个概念这里的“薄基座”指的就是 Claude Code 本身加上接入配置。你不需要魔改 Claude Code 的源码只需要把 Base URL、API Key、Model ID 这三件套配对剩下的交给 Skills。第一步去控制台创建一个 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面点新建复制那串以 sk- 开头的密钥。注意这个 Key 只显示一次建议先存到密码管理器里。第二步配置 Claude Code 的环境变量。Claude Code 读取的是 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 这两个变量。在 macOS 或 Linux 上你可以直接写进 shell 配置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的密钥Windows PowerShell 用户这样写$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_AUTH_TOKENsk-你的密钥如果你用的是 Claude Code 的 settings.json 配置文件也可以写成 JSON 片段路径通常在~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }这里的 Model ID 要写全Claude Code 对模型名比较敏感写错会直接报 model not found。常用的有 claude-sonnet-4-5-20250929 和 claude-opus-4-1-20250805按你的套餐选。第三步验证基座是否通了。在终端里跑一句最简单的请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 64, messages: [{role: user, content: 只回复两个字通了}] }如果返回的 JSON 里 content 字段有“通了”说明基座没问题。这一步很关键因为后面 Skills 加载失败时你要能区分是基座问题还是技能文件问题。基座保持轻薄就是让它只干这四件事别把业务逻辑塞进来。3. 可复制的 Skills 目录结构与 Markdown 技能描述规范现在进入正题。Claude Code 的技能发现机制是它会扫描项目根目录下的.claude/skills/目录每个技能是一个子目录里面必须有一个SKILL.md。这个文件的开头是 YAML frontmatter用来告诉模型“这个技能是干什么的、什么时候该用”。先给你一套可以直接复制的目录结构模板your-project/ ├── .claude/ │ ├── settings.json │ └── skills/ │ ├── api-review/ │ │ └── SKILL.md │ ├── db-migration/ │ │ ├── SKILL.md │ │ └── references/ │ │ └── naming-convention.md │ └── release-check/ │ ├── SKILL.md │ └── scripts/ │ └── check_env.sh ├── src/ └── CLAUDE.md注意技能目录名用小写加连字符别用下划线或空格Claude Code 的解析器对路径比较严格。每个技能目录里除了 SKILL.md还可以放 references参考文档和 scripts脚本SKILL.md 里用相对路径引用它们。接下来是 Markdown 技能描述规范。SKILL.md 的 frontmatter 至少要有 name 和 description 两个字段。description 是解析器的核心模型靠它来判断“用户这句话该不该触发这个技能”。写 description 的诀窍是把触发场景写具体别写“用于代码审查”这种空话要写“当用户要求审查 API 接口的鉴权、参数校验、错误码时使用”。给你一个完整的 api-review 技能示例--- name: api-review description: 当用户要求审查 REST API 接口的鉴权逻辑、参数校验、错误码规范、分页设计时使用。适用于新增接口或修改现有接口后的自查。 --- # API 接口审查技能 ## 审查步骤 1. 读取目标接口的路由定义文件确认 HTTP 方法和路径命名符合 kebab-case。 2. 检查鉴权中间件是否挂载未挂载的接口必须标记为高危。 3. 检查请求参数是否有 schema 校验缺失的列出字段名。 4. 检查错误码是否使用项目统一枚举禁止裸写数字。 5. 检查分页参数是否统一为 page 和 page_size默认值分别为 1 和 20。 ## 输出格式 按以下结构输出每条给出文件路径和行号 - 高危必须修复 - 建议可选优化 - 通过符合规范 ## 参考 命名规范见 references/naming-convention.md。这个文件就是“厚 Skills”的典型它把团队里口口相传的审查标准变成了模型每次都能执行的流程。你不需要改 Claude Code 一行代码它读到 description 后在你提到“审查接口”时就会自动加载。再给你一个带脚本的技能演示工具调用约定怎么沉淀。release-check 技能的 SKILL.md--- name: release-check description: 当用户准备发布新版本、执行 release 流程、检查发布前环境时使用。 --- # 发布前检查技能 ## 步骤 1. 运行 scripts/check_env.sh确认环境变量齐全。 2. 检查 CHANGELOG.md 是否有当前版本的条目。 3. 检查 package.json 的 version 字段是否与 tag 一致。 4. 运行测试套件任一失败则中止发布。 ## 约定 - 版本号遵循 semver。 - 发布分支必须是 release/*。 - 禁止在周五下午发布。看到没连“禁止周五下午发布”这种团队默契都能写进去。这就是 Markdown 作为技能描述语言的好处它用模型原生能理解的自然语言描述过程、判断和上下文比僵硬的配置文件灵活得多。4. 验证技能加载与生效用真实任务跑一遍检查步骤写完技能文件不代表就生效了得验证。我踩过的坑是技能写好了但 description 太模糊模型根本没触发白忙一场。下面给你一套检查步骤用真实任务验证。第一步确认技能被扫描到。在项目根目录启动 Claude Code输入/skills命令部分版本是/help里能看到技能列表。如果列表里没有你的技能先检查目录层级必须是.claude/skills/技能名/SKILL.md少一层都不行。第二步用触发语句测试。针对 api-review 技能你输入“帮我审查一下 src/routes/user.ts 里的接口”。观察 Claude Code 的响应里有没有提到“鉴权中间件”“错误码枚举”这些只有技能里才有的关键词。如果它只是泛泛地说“代码看起来不错”说明技能没加载。第三步检查 frontmatter 格式。YAML 对缩进敏感---必须是文件第一行name 和 description 不能有 tab。你可以用这个命令快速校验python3 -c import yaml, sys with open(.claude/skills/api-review/SKILL.md) as f: content f.read() fm content.split(---)[1] data yaml.safe_load(fm) print(name:, data.get(name)) print(description:, data.get(description)[:50]) 如果报 YAML 解析错误多半是冒号后面没加空格或者 description 里用了未转义的特殊字符。第四步验证脚本类技能。对 release-check 技能你输入“准备发布 1.2.0 版本”。模型应该会去读 scripts/check_env.sh 并尝试执行。如果它说“找不到脚本”检查 SKILL.md 里的相对路径是不是相对于技能目录而不是项目根目录。第五步看上下文占用。技能加载后你可以用/context命令查看当前上下文里加载了哪些文件。一个健康的技能应该只加载 SKILL.md 本身references 里的文档按需加载。如果发现整个 references 目录都被塞进来了说明你的 SKILL.md 里写了“读取 references 下所有文件”这种指令要改成按需引用。实测下来这套检查流程能覆盖 90% 的技能不生效问题。剩下的 10% 通常是模型版本差异换个 Model ID 再试。5. 常见报错排查401、local proxy failed、reading choices、OAuth技能跑不起来很多时候不是技能本身的问题而是基座配置出了岔子。下面按真实报错逐个排查。401 Unauthorized。这个最常见说明 API Key 没配对。先确认ANTHROPIC_AUTH_TOKEN的值是不是完整的 sk- 开头字符串有没有多余空格。然后确认 Base URL 是https://taotoken.net/api注意结尾没有斜杠。如果你用的是 settings.json检查 JSON 有没有语法错误可以用python3 -m json.tool ~/.claude/settings.json验证。还有一种情况是 Key 被禁用或额度耗尽去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 看一眼状态。local proxy failed。这个报错通常出现在你本地配了代理但代理没启动或端口不对。Claude Code 会读取HTTPS_PROXY环境变量。如果你不需要代理直接unset HTTPS_PROXY和unset HTTP_PROXY。如果确实需要确认代理地址和端口正确并且代理本身能访问外网。注意这里说的是本地开发环境的网络配置跟任何违规工具无关。reading choices 报错。完整报错一般是error reading choices: unexpected end of JSON input。这多半是模型返回的流式响应被截断了。原因可能是 max_tokens 设得太小或者网络不稳定。把 max_tokens 调到 4096 以上再试。如果还不行检查你的请求体里 messages 数组是不是空的。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式要确保没有残留的 OAuth token。删掉~/.claude/下的 credentials 缓存文件重启 Claude Code。如果报错里提到invalid_grant说明 OAuth token 过期了但你根本不需要它直接清掉即可。排查顺序建议是先 curl 测基座再/skills看技能列表最后用触发语句测技能。这样能快速定位是接入层、技能发现层还是技能内容层的问题。三件套 Base URL、Key、Model ID 任何一项写错都会在前面几步暴露出来。6. 把 Skills 用起来从个人工作流到团队协作的落地建议技能文件写多了会面临一个新问题怎么管理。我的建议是分三层。个人层放~/.claude/skills/放你个人的编码习惯比如“我习惯用 early return”。项目层放项目根目录的.claude/skills/放这个项目特有的规范跟着 git 走。团队层可以单独建一个 skills 仓库用 git submodule 挂到各个项目里统一更新。写技能时记住一个原则一个技能只干一件事。别写“万能技能”那会让 description 变得模糊模型反而不知道什么时候该用。宁可写十个精准的小技能也别写一个包罗万象的大技能。另外技能是可以迭代的。每次你发现模型在某个任务上表现不好别急着改 prompt先想想是不是缺一个技能。把这次的处理过程写成 SKILL.md下次它就自动会了。这就是“会学习的系统”的雏形技能文件在一次次实践中被重写系统在没人改代码的情况下变强。如果你还没开始用 Claude Code可以先从模型对话页面体验一下 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 感受一下模型的能力边界。等你决定把它接入日常编码再按上面的步骤配好基座然后从第一个技能文件开始写。长期做编码和 Agent 任务的话Coding Plan 会更划算地址在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置问题可以先翻一遍。最后给你一个可以直接开始的行动打开你最近一次让 Claude Code 反复修改的任务把你在 review 时反复强调的那几条规则写成第一个 SKILL.md。就从这个文件开始你的薄 Harness 厚 Skills 体系就算落地了。
返回列表