1. 为什么你的 Claude Code 总在重复“教”同一件事如果你刚开始用 Claude Code 写代码大概率经历过这样的循环第一次让它按团队规范生成接口文档你得把格式要求、命名规则、注释风格全说一遍第二次换个模块又得重新贴一遍同样的提示词。三次之后你的聊天记录里全是复制粘贴的痕迹而 Claude 每次都在“重新学习”你已经讲过无数遍的东西。Agent Skills 要解决的就是这个问题。它把“怎么做一个任务”的流程、规范、脚本打包成一个文件夹Claude Code 在需要时自动发现并加载不用你每次重复解释。你可以把它理解成给 Claude 装了一本可插拔的“操作手册”——需要做代码审查时翻开审查手册需要写技术文档时翻开写作手册手册本身是持久化的不会因为对话结束就消失。这篇文章面向刚接触大模型技能复用的开发者重点讲清楚三件事SKILL.md 的目录结构和字段骨架长什么样、一份可复制的技能配置怎么写、以及在 Claude Code 里加载和验证技能生效的完整动作。全程按“能跟着做”的标准来不堆概念。2. 前置准备TaoToken 接入与 Claude Code 环境在写 SKILL.md 之前得先让 Claude Code 能正常跑起来。Claude Code 本身是一个命令行工具它需要连接到一个兼容 Anthropic 接口的模型服务。这里我用 TaoToken 来做接入原因是它的接口格式和 Anthropic 官方一致配置成本低适合做技能加载这类需要反复调试的场景。你需要先拿到一个 API Key。打开 TaoToken 的 API Keys 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建一个新的 Key复制出来备用。注意这个 Key 只在创建时显示一次丢了就得重新生成。拿到 Key 之后设置环境变量。Claude Code 默认读取ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL两个变量你可以直接在终端里导出export ANTHROPIC_API_KEY你的TaoToken_API_Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api如果你用的是 Windows PowerShell换成$env:ANTHROPIC_API_KEY你的TaoToken_API_Key $env:ANTHROPIC_BASE_URLhttps://taotoken.net/api设置完之后运行claude命令进入交互界面随便问一句“你好”确认模型能正常响应。这一步通了后面的技能加载才有意义。如果这里就报 401 或连接超时先检查 Key 有没有复制完整、Base URL 有没有多写斜杠。注意环境变量只在当前终端会话有效。如果你希望持久化可以把 export 写进~/.bashrc或~/.zshrcWindows 则用系统环境变量面板添加。3. SKILL.md 目录结构与字段骨架Agent Skills 的核心是一个文件夹Claude Code 会扫描特定目录下的所有技能。默认的技能目录是~/.config/claude-code/skills/每个子文件夹代表一个技能。一个完整的技能目录结构如下my-skill/ ├── SKILL.md # 核心指令文档必需 ├── scripts/ # 可执行脚本可选 │ ├── process.py │ └── validate.sh ├── reference/ # 参考文档可选 │ └── api-docs.md └── assets/ # 模板和示例可选 ├── templates/ └── examples/SKILL.md 本身是 Markdown 文件开头必须有一段 YAML frontmatter用三个短横线包裹。字段骨架只有两个是必需的--- name: your-skill-name description: 一句话说明这个技能做什么、什么时候用 ---name是技能的唯一标识调用时用$name引用。description最关键——Claude Code 在启动时只加载所有技能的 name 和 description大约 50 tokens当你的任务描述和某个 description 语义匹配时才会加载完整的 SKILL.md 内容。所以 description 要写得具体包含触发关键词。frontmatter 之后是正文用 Markdown 写清楚使用时机、工作流程、检查清单。我建议按这个顺序组织--- name: api-doc-writer description: 根据代码自动生成符合团队规范的 API 文档当用户提到生成接口文档写 API 说明时使用 --- # API 文档生成专家 ## 使用时机 - 用户上传了包含路由定义的代码文件 - 用户明确要求生成 API 文档 - 用户询问接口的参数和返回值说明 ## 工作流程 1. 扫描代码中的路由装饰器提取路径、方法、参数 2. 读取函数 docstring 和类型注解 3. 按团队模板生成 Markdown 文档 4. 检查是否遗漏错误码说明 ## 输出规范 - 每个接口包含路径、方法、参数表、返回示例、错误码 - 参数表用 Markdown 表格列名称、类型、必填、说明 - 代码块标注语言为 json 或 bash ## 检查清单 - [ ] 所有路径参数都有说明 - [ ] 返回示例是合法 JSON - [ ] 错误码覆盖 400/401/404/500这个骨架的好处是Claude 加载后能立刻知道“什么时候用、按什么步骤做、输出成什么样”不需要你再在对话里补充。4. 可复制配置写一个代码审查技能下面这份配置可以直接复制到~/.config/claude-code/skills/code-reviewer/SKILL.md用来做 Python 代码的规范审查。我选这个场景是因为它足够典型——审查规则固定、重复频率高、输出格式统一正好适合用技能固化。mkdir -p ~/.config/claude-code/skills/code-reviewer然后创建 SKILL.md--- name: code-reviewer description: Python 代码规范审查检查命名、注释、异常处理和类型注解当用户要求审查代码检查规范时使用 --- # Python 代码审查专家 ## 使用时机 - 用户提交了一段 Python 代码要求审查 - 用户询问代码是否符合 PEP 8 规范 - 用户要求检查类型注解完整性 ## 审查维度 ### 1. 命名规范 - 变量和函数用 snake_case - 类名用 PascalCase - 常量用 UPPER_SNAKE_CASE - 私有方法以单下划线开头 ### 2. 注释与文档 - 公共函数必须有 docstring - docstring 包含参数、返回、异常说明 - 复杂逻辑行内注释说明为什么而非做什么 ### 3. 异常处理 - 禁止裸 except - 捕获具体异常类型 - 异常信息包含上下文 ### 4. 类型注解 - 函数参数和返回值必须有类型注解 - 使用 typing 模块的 Optional、List、Dict ## 输出格式 按严重程度分三档输出 **严重**会导致运行时错误的问题 **警告**不符合规范但不影响运行 **建议**可读性优化 每个问题给出行号、问题描述、修改建议、修改后代码 ## 示例 输入 python def getData(id): try: return db.query(id) except: return None输出严重- 第 4 行裸 except 会捕获所有异常包括 KeyboardInterrupt 建议改为def get_data(user_id: int) - Optional[User]: try: return db.query(user_id) except DatabaseError as e: logger.error(f查询用户失败: {e}) return None这份配置里description 包含了“审查代码”“检查规范”两个触发词Claude Code 在你说“帮我审查这段代码”时就会自动激活它。正文里的审查维度和输出格式是固定的不需要每次重复。 ## 5. 加载、调用与验证技能生效 技能文件写好后Claude Code 不会自动热加载。你需要重启一次 claude 命令让它在启动时扫描技能目录。重启后在交互界面里输入 /skills应该能看到 code-reviewer 出现在列表里状态是 enabled。 如果没看到先检查三件事目录路径是不是 ~/.config/claude-code/skills/、SKILL.md 的 frontmatter 有没有语法错误比如冒号后面没空格、文件名是不是严格叫 SKILL.md大小写敏感。 验证技能是否真正生效有两种方式。 第一种是显式调用。在对话里输入 text $code-reviewer 帮我审查这段代码 def calc(a,b): return ab如果技能加载成功Claude 会按你定义的“严重/警告/建议”三档格式输出而不是随便给一段泛泛的评价。第二种是自动触发。直接说帮我审查一下这段 Python 代码的规范问题Claude 会根据 description 的语义匹配自动激活code-reviewer。你可以在输出里观察它是否用了你定义的检查清单和输出格式。如果它只是泛泛而谈说明 description 写得不够具体或者技能没被扫描到。我实测下来自动触发的准确率取决于 description 的质量。把“审查代码”“检查规范”“PEP 8”这些词写进去命中率会明显提高。6. 本篇常见错排查技能不生效/skills列表里没有最常见的原因是目录层级搞错了。正确路径是~/.config/claude-code/skills/技能名/SKILL.md注意技能名是文件夹SKILL.md在文件夹里面。如果你直接建了~/.config/claude-code/skills/SKILL.mdClaude Code 扫描不到。另一个原因是 frontmatter 格式错误。YAML 对缩进和冒号后的空格敏感name:code-reviewer这种写法会解析失败必须写成name: code-reviewer。技能加载了但输出格式不对检查 SKILL.md 正文里有没有明确写“输出格式”章节。Claude 不会自动猜你想要什么格式你得把模板写出来。如果写了但没遵守可能是正文太长导致关键指令被稀释试着把输出格式移到文档靠前的位置。自动触发不灵敏description 太短或太泛。比如只写“代码审查”不如写“Python 代码规范审查检查命名、注释、异常处理和类型注解当用户要求审查代码时使用”。把用户可能说的原话写进去匹配率会高很多。修改 SKILL.md 后没变化Claude Code 在启动时加载技能运行中修改文件不会热更新。改完必须退出重进。如果你在调试阶段频繁改建议开两个终端一个改文件一个跑claude。脚本执行报权限错误如果你的技能引用了scripts/下的脚本确保脚本有可执行权限chmod x scripts/process.py。另外脚本里的路径要用绝对路径或相对于技能目录的路径不要用相对于当前工作目录的路径否则换个目录调用就找不到文件。7. 把技能用起来从单技能到组合调用单个技能跑通之后你可以开始组合。比如做一个“提交前检查”流程把code-reviewer和另一个commit-message-writer技能串起来。Claude Code 支持在一个任务里自动调用多个技能前提是每个技能的 description 都能被任务描述命中。组合调用的写法是在 SKILL.md 里引用其他技能## 工作流程 1. 调用 $code-reviewer 审查变更代码 2. 如果审查通过调用 $commit-message-writer 生成提交信息 3. 输出审查报告和提交信息这样你只需要说“帮我做提交前检查”Claude 就会按顺序激活两个技能。技能之间的数据传递靠对话上下文不需要额外配置。如果你想把技能沉淀成团队资产可以把技能目录放到 Git 仓库里团队成员 clone 到各自的~/.config/claude-code/skills/下。这样新人入职第一天就能用上统一的代码审查规范不用再口口相传。对于需要长期跑编码任务和 Agent 的场景可以考虑用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite来获得更稳定的调用配额避免调试技能时被限流打断。技能调试阶段请求比较密集配额充足会省心很多。技能的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里面有接口参数和错误码的完整说明。如果你想先验证模型对话是否正常可以用模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite快速测一下。Claude Code 相关的配置参考在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里面有环境变量和常见问题的排查步骤。技能写多了之后你会发现真正花时间的不是写 SKILL.md而是想清楚“这个任务的固定流程到底是什么”。把流程拆成步骤、把步骤写成检查清单、把检查清单变成可执行的指令——这个过程本身就是对团队工作流的一次梳理。