1. 为什么你的 Claude Code 需要 Agent Skills如果你已经在用 Claude Code 写代码大概率经历过这样的循环每次开新会话都要把团队代码规范、目录约定、提交信息格式重新贴一遍换个项目提示词又得改一版同事问你「怎么让 Claude 按我们的方式写测试」你只能把那段两百行的 prompt 复制过去。提示词本身没有版本管理也没法被自动触发时间一长就变成一堆散落在聊天记录里的碎片。Agent Skills 想解决的就是这件事。它把「行为规范 专业知识 使用时机的组合」固化成一个文件夹核心是一个SKILL.md文件用 Markdown 写清楚这个技能做什么、什么时候用、具体规则是什么。Claude Code 启动时会先读取所有技能的元数据name和description判断当前任务是否相关相关才加载SKILL.md正文正文里引用的脚本、示例、参考文档只在真正需要时才读。这套机制叫渐进式披露好处是技能可以写得很细但不会一上来就把上下文窗口塞满。它适合谁适合那些已经把 Claude Code 当日常工具、手里攒了一堆重复提示词、想让团队共享同一套 AI 行为规范的开发者。你不需要会写插件只要会写 Markdown就能搭出一个可复用、可 Git 管理、可跨项目迁移的技能骨架。下面我从目录结构开始一步步把SKILL.md和settings.json配好最后用一次真实调用验证它到底有没有被加载。2. TaoToken 前置把模型接入准备好Claude Code 要跑起来得先有一个能调通的模型入口。我这边习惯用 TaoToken 做统一接入它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式Claude Code 直接改环境变量就能接上。官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后在控制台生成 API Key 即可。拿到 Key 之后在终端里配置两个环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY把 base url 指向 TaoToken 的 API 地址Key 填你生成的那串export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你不想每次开终端都 export可以写进~/.zshrc或~/.bashrc。Windows 下用 PowerShell 的话是$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api写法不同但思路一样。注意ANTHROPIC_BASE_URL后面不要带/v1Claude Code 会自己拼路径。多带一层容易出现 404这是我自己踩过的坑。Key 的管理入口在控制台的 API Keys 页面建议给 Claude Code 单独建一个 Key方便按项目区分用量。如果你还没生成可以去https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有不同客户端的配置示例遇到字段对不上可以对照查。环境变量配好后先跑一次claude确认能正常对话再往下做技能配置。如果这一步就报鉴权错误后面技能加载的问题会被掩盖排查起来更麻烦。3. 可复制配置SKILL.md 骨架与 settings.json3.1 技能目录放哪里Claude Code 的技能有两个位置个人全局技能放在~/.claude/skills/项目专用技能放在项目根目录的.claude/skills/。团队协作场景我建议用项目级跟着 Git 走谁拉下来都能用。个人常用的小工具放全局跨项目复用。每个技能是一个独立文件夹文件夹名就是技能标识里面必须有一个SKILL.md。最小结构长这样.claude/ └── skills/ └── python-naming-standard/ └── SKILL.md如果技能需要附带脚本或参考文档就在同级加scripts/、examples/、references/目录然后在SKILL.md正文里用相对路径引用。这样核心规则保持在SKILL.md里大块资料拆出去按需加载。3.2 SKILL.md 的元信息骨架SKILL.md开头是一段 YAML 元信息用三个短横线包起来然后是 Markdown 正文。元信息里name和description最关键description直接决定 Claude 会不会自动触发这个技能所以要写清楚「做什么」和「什么时候用」。--- name: python-naming-standard description: 当用户要求编写、重构或审查 Python 代码时使用确保内部辅助函数遵循 _internal_ 前缀规范。 --- ## 指令 1. 所有内部辅助函数必须以 _internal_ 前缀命名。 2. 发现不符合规则的代码时主动提出修改建议。 3. 提交前检查命名规范是否被违反。 ## 示例 - 正确def _internal_calculate_risk(): - 错误def _calculate_risk(): ## 参考 详细命名约定见 ./references/naming.mdname只支持小写字母、数字和短横线最长 64 字符。description建议控制在 1024 字符以内写得太泛会导致误触发写得太窄又可能该触发时不触发。我的经验是把触发场景写具体比如「当用户要求编写、重构或审查 Python 代码时」比单写「Python 规范」命中率高很多。除了这两个字段还有几个可选字段值得了解。allowed-tools可以声明技能激活时允许无授权使用的工具disable-model-invocation设为true时禁止自动触发只能手动/name调用user-invocable设为false则从斜杠菜单隐藏作为后台增强能力。这些按需加初期不用全上。3.3 settings.json 里启用技能技能文件放好后还要在 Claude Code 的配置里确认技能目录被扫描。项目级配置在.claude/settings.json个人级在~/.claude/settings.json。一个启用技能的配置片段如下{ skills: { enabled: true, paths: [ .claude/skills, ~/.claude/skills ] } }enabled打开技能系统paths列出扫描目录。如果你只用一个位置保留对应那条即可。改完配置重启 Claude Code它会在启动时重新读取技能元数据。提示settings.json是标准 JSON不能写注释。多写一行//会导致整个配置解析失败技能静默不加载这个坑很隐蔽。3.4 用动态变量让技能更灵活SKILL.md正文里可以插入动态变量调用时自动替换。常用的有$ARGUMENTS全部参数、$ARGUMENTS[0]按索引取、$0第一个参数的简写、${CLAUDE_SESSION_ID}当前会话 ID。比如做一个会话日志技能--- name: session-logger description: 记录当前会话活动到日志文件。 --- 请将以下内容写入日志文件 logs/${CLAUDE_SESSION_ID}.log $ARGUMENTS调用/session-logger 用户登录成功它会生成一个带会话 ID 的日志文件内容就是传入的参数。这种写法适合把重复的日志、提交、检查动作沉淀成技能。4. 验证请求一次真实调用看加载是否生效配置写完得验证技能真的被加载了。我用的办法是造一个必然触发技能的任务然后看输出是否符合技能规则。先确认目录结构mkdir -p claude-test/.claude/skills/python-naming-standard cd claude-test把上面那段SKILL.md写进.claude/skills/python-naming-standard/SKILL.md然后在项目根目录启动claude进入交互后输入任务帮我写一个计算用户折扣的函数如果技能加载成功Claude 生成的函数名会带_internal_前缀比如def _internal_get_discount(user_score): if user_score 90: return 0.8 elif user_score 70: return 0.9 return 1.0如果生成的是def get_discount(...)说明技能没被触发。这时候先别急着改SKILL.md按下面顺序排查。另一种验证方式是手动调用。如果技能没有设disable-model-invocation可以在对话里输入/python-naming-standard看斜杠菜单里有没有这个技能。菜单里能出现说明元数据被正确读取菜单里没有问题出在目录或配置层。还可以让 Claude 自述当前可用技能。输入「列出你当前加载的所有技能」它会根据系统提示里的元数据回答。这个方法能快速确认技能是否进入了发现层。5. 本篇常见错排查技能不生效原因基本集中在几个地方。下面按我实际遇到的频率排。目录层级不对。最常见的是把SKILL.md直接放在.claude/skills/下而不是放在技能子文件夹里。正确路径是.claude/skills/技能名/SKILL.md中间必须有一层文件夹。少了这层Claude Code 扫描不到。YAML 元信息格式错误。三个短横线必须独占一行name和description的冒号后面要有空格。用中文冒号、漏掉结尾的---、缩进用了 Tab都会导致元信息解析失败。解析失败时技能不会报错只是静默不加载所以写完最好用 YAML 校验工具过一遍。description 写得太泛或太窄。写「帮助写代码」会到处误触发写「处理 2024 版财务 PDF 表单第三页」又几乎不会命中。判断标准是把 description 读给一个不了解你项目的人听他能不能判断出什么时候该用。settings.json 解析失败。多一个逗号、多一行注释整个文件就废了。改完用python -m json.tool .claude/settings.json验证一下能打印出格式化结果才算合法。环境变量没生效。ANTHROPIC_BASE_URL或ANTHROPIC_API_KEY没配好Claude Code 根本连不上模型技能自然无从加载。先在终端echo $ANTHROPIC_BASE_URL确认值正确再启动claude。技能名不符合规范。name里出现大写字母、下划线、空格都会导致技能被跳过。只用小写字母、数字、短横线最长 64 字符。改了技能没重启。技能元数据在 Claude Code 启动时加载运行中改SKILL.md不会热更新。改完退出重进一次。排查时有个通用思路先确认技能出现在斜杠菜单里发现层通过再确认自动触发时输出符合规则加载层通过最后确认引用的脚本或参考文档能被读到资源层通过。三层分开定位比一股脑改文件高效得多。6. 把技能用起来从骨架到团队资产技能骨架搭好之后真正让它产生价值的是持续沉淀。我的做法是每次发现自己在重复某段提示词就停下来问一句这段东西是不是该变成一个技能如果是就新建一个文件夹把规则写进SKILL.md把大块资料拆到references/把可执行逻辑放到scripts/。团队场景下项目级技能跟着仓库走Code Review 时顺便审SKILL.md的变更规范就自然沉淀下来了。新同事拉下代码Claude Code 自动按团队规范工作不需要额外培训。这比维护一份没人看的 Wiki 有效得多。如果你想把技能用在长期编码或 Agent 工作流上可以了解下 Coding Plan它更适合高频、长会话的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。想先在对话里验证模型对技能的理解用模型对话入口更轻量https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite。接入过程中遇到字段或鉴权问题直接查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。技能不是一次写完就完事的它更像代码需要迭代。先从一个最小的SKILL.md开始跑通一次调用再慢慢加规则、加资源、加脚本。等你手里攒了五六个技能会发现 Claude Code 的行为越来越像团队里那个熟悉规范的老手而不是每次都要从头解释的新人。
Claude Code 系列教程之 Agent Skills：用 SKILL.md 与 Markdown 搭建可复用技能骨架
1. 为什么你的 Claude Code 需要 Agent Skills如果你已经在用 Claude Code 写代码大概率经历过这样的循环每次开新会话都要把团队代码规范、目录约定、提交信息格式重新贴一遍换个项目提示词又得改一版同事问你「怎么让 Claude 按我们的方式写测试」你只能把那段两百行的 prompt 复制过去。提示词本身没有版本管理也没法被自动触发时间一长就变成一堆散落在聊天记录里的碎片。Agent Skills 想解决的就是这件事。它把「行为规范 专业知识 使用时机的组合」固化成一个文件夹核心是一个SKILL.md文件用 Markdown 写清楚这个技能做什么、什么时候用、具体规则是什么。Claude Code 启动时会先读取所有技能的元数据name和description判断当前任务是否相关相关才加载SKILL.md正文正文里引用的脚本、示例、参考文档只在真正需要时才读。这套机制叫渐进式披露好处是技能可以写得很细但不会一上来就把上下文窗口塞满。它适合谁适合那些已经把 Claude Code 当日常工具、手里攒了一堆重复提示词、想让团队共享同一套 AI 行为规范的开发者。你不需要会写插件只要会写 Markdown就能搭出一个可复用、可 Git 管理、可跨项目迁移的技能骨架。下面我从目录结构开始一步步把SKILL.md和settings.json配好最后用一次真实调用验证它到底有没有被加载。2. TaoToken 前置把模型接入准备好Claude Code 要跑起来得先有一个能调通的模型入口。我这边习惯用 TaoToken 做统一接入它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式Claude Code 直接改环境变量就能接上。官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后在控制台生成 API Key 即可。拿到 Key 之后在终端里配置两个环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY把 base url 指向 TaoToken 的 API 地址Key 填你生成的那串export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你不想每次开终端都 export可以写进~/.zshrc或~/.bashrc。Windows 下用 PowerShell 的话是$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api写法不同但思路一样。注意ANTHROPIC_BASE_URL后面不要带/v1Claude Code 会自己拼路径。多带一层容易出现 404这是我自己踩过的坑。Key 的管理入口在控制台的 API Keys 页面建议给 Claude Code 单独建一个 Key方便按项目区分用量。如果你还没生成可以去https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有不同客户端的配置示例遇到字段对不上可以对照查。环境变量配好后先跑一次claude确认能正常对话再往下做技能配置。如果这一步就报鉴权错误后面技能加载的问题会被掩盖排查起来更麻烦。3. 可复制配置SKILL.md 骨架与 settings.json3.1 技能目录放哪里Claude Code 的技能有两个位置个人全局技能放在~/.claude/skills/项目专用技能放在项目根目录的.claude/skills/。团队协作场景我建议用项目级跟着 Git 走谁拉下来都能用。个人常用的小工具放全局跨项目复用。每个技能是一个独立文件夹文件夹名就是技能标识里面必须有一个SKILL.md。最小结构长这样.claude/ └── skills/ └── python-naming-standard/ └── SKILL.md如果技能需要附带脚本或参考文档就在同级加scripts/、examples/、references/目录然后在SKILL.md正文里用相对路径引用。这样核心规则保持在SKILL.md里大块资料拆出去按需加载。3.2 SKILL.md 的元信息骨架SKILL.md开头是一段 YAML 元信息用三个短横线包起来然后是 Markdown 正文。元信息里name和description最关键description直接决定 Claude 会不会自动触发这个技能所以要写清楚「做什么」和「什么时候用」。--- name: python-naming-standard description: 当用户要求编写、重构或审查 Python 代码时使用确保内部辅助函数遵循 _internal_ 前缀规范。 --- ## 指令 1. 所有内部辅助函数必须以 _internal_ 前缀命名。 2. 发现不符合规则的代码时主动提出修改建议。 3. 提交前检查命名规范是否被违反。 ## 示例 - 正确def _internal_calculate_risk(): - 错误def _calculate_risk(): ## 参考 详细命名约定见 ./references/naming.mdname只支持小写字母、数字和短横线最长 64 字符。description建议控制在 1024 字符以内写得太泛会导致误触发写得太窄又可能该触发时不触发。我的经验是把触发场景写具体比如「当用户要求编写、重构或审查 Python 代码时」比单写「Python 规范」命中率高很多。除了这两个字段还有几个可选字段值得了解。allowed-tools可以声明技能激活时允许无授权使用的工具disable-model-invocation设为true时禁止自动触发只能手动/name调用user-invocable设为false则从斜杠菜单隐藏作为后台增强能力。这些按需加初期不用全上。3.3 settings.json 里启用技能技能文件放好后还要在 Claude Code 的配置里确认技能目录被扫描。项目级配置在.claude/settings.json个人级在~/.claude/settings.json。一个启用技能的配置片段如下{ skills: { enabled: true, paths: [ .claude/skills, ~/.claude/skills ] } }enabled打开技能系统paths列出扫描目录。如果你只用一个位置保留对应那条即可。改完配置重启 Claude Code它会在启动时重新读取技能元数据。提示settings.json是标准 JSON不能写注释。多写一行//会导致整个配置解析失败技能静默不加载这个坑很隐蔽。3.4 用动态变量让技能更灵活SKILL.md正文里可以插入动态变量调用时自动替换。常用的有$ARGUMENTS全部参数、$ARGUMENTS[0]按索引取、$0第一个参数的简写、${CLAUDE_SESSION_ID}当前会话 ID。比如做一个会话日志技能--- name: session-logger description: 记录当前会话活动到日志文件。 --- 请将以下内容写入日志文件 logs/${CLAUDE_SESSION_ID}.log $ARGUMENTS调用/session-logger 用户登录成功它会生成一个带会话 ID 的日志文件内容就是传入的参数。这种写法适合把重复的日志、提交、检查动作沉淀成技能。4. 验证请求一次真实调用看加载是否生效配置写完得验证技能真的被加载了。我用的办法是造一个必然触发技能的任务然后看输出是否符合技能规则。先确认目录结构mkdir -p claude-test/.claude/skills/python-naming-standard cd claude-test把上面那段SKILL.md写进.claude/skills/python-naming-standard/SKILL.md然后在项目根目录启动claude进入交互后输入任务帮我写一个计算用户折扣的函数如果技能加载成功Claude 生成的函数名会带_internal_前缀比如def _internal_get_discount(user_score): if user_score 90: return 0.8 elif user_score 70: return 0.9 return 1.0如果生成的是def get_discount(...)说明技能没被触发。这时候先别急着改SKILL.md按下面顺序排查。另一种验证方式是手动调用。如果技能没有设disable-model-invocation可以在对话里输入/python-naming-standard看斜杠菜单里有没有这个技能。菜单里能出现说明元数据被正确读取菜单里没有问题出在目录或配置层。还可以让 Claude 自述当前可用技能。输入「列出你当前加载的所有技能」它会根据系统提示里的元数据回答。这个方法能快速确认技能是否进入了发现层。5. 本篇常见错排查技能不生效原因基本集中在几个地方。下面按我实际遇到的频率排。目录层级不对。最常见的是把SKILL.md直接放在.claude/skills/下而不是放在技能子文件夹里。正确路径是.claude/skills/技能名/SKILL.md中间必须有一层文件夹。少了这层Claude Code 扫描不到。YAML 元信息格式错误。三个短横线必须独占一行name和description的冒号后面要有空格。用中文冒号、漏掉结尾的---、缩进用了 Tab都会导致元信息解析失败。解析失败时技能不会报错只是静默不加载所以写完最好用 YAML 校验工具过一遍。description 写得太泛或太窄。写「帮助写代码」会到处误触发写「处理 2024 版财务 PDF 表单第三页」又几乎不会命中。判断标准是把 description 读给一个不了解你项目的人听他能不能判断出什么时候该用。settings.json 解析失败。多一个逗号、多一行注释整个文件就废了。改完用python -m json.tool .claude/settings.json验证一下能打印出格式化结果才算合法。环境变量没生效。ANTHROPIC_BASE_URL或ANTHROPIC_API_KEY没配好Claude Code 根本连不上模型技能自然无从加载。先在终端echo $ANTHROPIC_BASE_URL确认值正确再启动claude。技能名不符合规范。name里出现大写字母、下划线、空格都会导致技能被跳过。只用小写字母、数字、短横线最长 64 字符。改了技能没重启。技能元数据在 Claude Code 启动时加载运行中改SKILL.md不会热更新。改完退出重进一次。排查时有个通用思路先确认技能出现在斜杠菜单里发现层通过再确认自动触发时输出符合规则加载层通过最后确认引用的脚本或参考文档能被读到资源层通过。三层分开定位比一股脑改文件高效得多。6. 把技能用起来从骨架到团队资产技能骨架搭好之后真正让它产生价值的是持续沉淀。我的做法是每次发现自己在重复某段提示词就停下来问一句这段东西是不是该变成一个技能如果是就新建一个文件夹把规则写进SKILL.md把大块资料拆到references/把可执行逻辑放到scripts/。团队场景下项目级技能跟着仓库走Code Review 时顺便审SKILL.md的变更规范就自然沉淀下来了。新同事拉下代码Claude Code 自动按团队规范工作不需要额外培训。这比维护一份没人看的 Wiki 有效得多。如果你想把技能用在长期编码或 Agent 工作流上可以了解下 Coding Plan它更适合高频、长会话的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。想先在对话里验证模型对技能的理解用模型对话入口更轻量https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite。接入过程中遇到字段或鉴权问题直接查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。技能不是一次写完就完事的它更像代码需要迭代。先从一个最小的SKILL.md开始跑通一次调用再慢慢加规则、加资源、加脚本。等你手里攒了五六个技能会发现 Claude Code 的行为越来越像团队里那个熟悉规范的老手而不是每次都要从头解释的新人。
