Claude Skills 深度解析：SKILL.md 配置、创建与多工具使用指南

1. 从一次“重复劳动”说起Claude Skills 到底解决什么问题如果你最近在折腾 Claude Code大概率会遇到一个尴尬场景每次让它处理 PDF 表格、生成周报、或者按团队规范写提交信息你都得把同一段提示词重新贴一遍。贴多了会烦烦了就想找个地方把它“存起来”下次直接调用。Claude Skills 就是干这个的——它把提示词、脚本、参考文档、模板资源打包成一个标准文件夹让 Claude 在需要时自动加载不需要时完全不占上下文。一句话概括Claude Skills 是给 AI Agent 用的“技能包”核心文件是SKILL.md本质是一个带 YAML 元数据的 Markdown 指令文件。它适合谁适合每天和 Claude Code、CodeX、OpenCode 打交道想把个人或团队工作流沉淀下来的开发者。你不需要会写复杂插件只要会写 Markdown、会建文件夹就能做出第一个 Skill。我试过把“中文转英文 URL slug”和“内容转小红书风格”两个小功能塞进一个 Skill结果在 Claude Code 里输入/my-zmt-tool就能直接触发比每次重新描述需求快得多。下面从概念到落地把 SKILL.md 的配置、创建、多工具使用完整走一遍。2. 前置准备TaoToken 接入与 Claude Code 环境确认在动手写 Skill 之前得先保证你的 Claude Code 能正常跑起来。如果你用的是官方订阅直接跳过这段如果通过 API 方式接入可以用 TaoToken 作为统一入口它兼容 Anthropic 风格的接口配置起来比较省事。TaoToken 官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接填就行。在 Claude Code 里配置环境变量通常是在~/.claude/settings.json或项目级.claude/settings.json中指定{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_API_Key } }API Key 可以在控制台创建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后复制保存别提交到 Git。注意Skills 运行在代码执行环境中具备文件系统访问和 bash 命令能力。所以你的 Claude Code 必须能正常执行本地命令否则 Skill 里的脚本无法运行。确认环境没问题后用/skills命令看看当前已安装的技能列表。如果返回空列表或提示命令不存在说明版本太旧先升级 Claude Code。3. SKILL.md 骨架与目录结构可复制的配置模板Claude Skills 的目录结构非常直观一个 Skill 就是一个文件夹my-skill/ ├── SKILL.md # 必选元数据 指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板、资源文件SKILL.md分两部分YAML 前置元数据和 Markdown 正文。元数据必填字段只有两个--- name: my-zmt-tool description: 将中文内容转换为英文 URL slug并将文章改写为小红书风格。适用于自媒体内容处理场景。 ---name最多 64 字符只能用小写字母、数字和连字符description最多 1024 字符不能为空。可选字段包括license、compatibility、metadata、allowed-tools。Markdown 正文没有固定格式但建议写清楚工作流、最佳实践和示例。下面是一个可直接复制的完整骨架--- name: my-zmt-tool description: 自媒体内容助手支持中文转英文 URL slug 和内容转小红书风格。 --- # 自媒体内容助手 ## 功能一中文转英文 URL slug 当用户提供中文标题时执行以下步骤 1. 将中文翻译为简洁英文 2. 全部转为小写 3. 空格替换为连字符 4. 去除特殊字符 示例 输入Claude Skills 深度解析 输出claude-skills-deep-dive ## 功能二内容转小红书风格 当用户要求改写为小红书风格时 1. 开头加一句吸引人的钩子 2. 每段不超过 3 行 3. 适当使用换行和短句 4. 结尾加 3-5 个相关话题标签 ## 注意事项 - 保持原意不变 - 不要添加虚假信息 - 输出前检查是否有敏感词把这段内容保存为my-skill/SKILL.md一个最小可用的 Skill 就完成了。如果你想让 Skill 更强大可以在scripts/里放 Python 或 bash 脚本在 Markdown 里用相对路径引用。4. 在 Claude Code 中加载、触发与验证 SkillSkill 的存放位置决定了它的生效范围类型生效范围目录位置Personal Skills全局所有项目~/.claude/skills/Project Skills单个项目.claude/skills/Plugin Skills取决于插件由插件定义安装方式就是把整个技能目录复制过去mkdir -p ~/.claude/skills cp -r my-skill ~/.claude/skills/复制完成后在 Claude Code 里输入/skills应该能看到my-zmt-tool出现在列表中。如果没出现检查目录层级是否正确——必须是~/.claude/skills/my-skill/SKILL.md不能多一层或少一层。触发方式有两种。自动触发Claude 根据任务描述和 Skill 的description自动匹配加载。手动触发输入/my-zmt-tool主动调用。手动触发适合你有明确偏好、不想让模型自己判断的场景。验证是否生效可以输入一个测试请求帮我把“Claude Skills 深度解析”转成英文 URL slug如果 Skill 加载成功Claude 会按照 SKILL.md 里定义的步骤输出claude-skills-deep-dive。如果它没按格式来说明 Skill 没被触发检查description是否足够明确。5. CodeX 与 OpenCode 中的 Skills 使用差异Agent Skills 已经被推动为开放标准Claude 里创建的 Skill 可以直接复制到 CodeX 使用。安装路径不同mkdir -p ~/.codex/skills cp -r my-skill ~/.codex/skills/CodeX 里列出技能同样用/skills但手动调用方式不一样——它用$skill-name而不是/skill-name。这是 CodeX 把 Skills 和自身命令分开的设计。另外 CodeX 额外提供skill-creator和skill-installer命令前者引导式创建技能后者从仓库安装。OpenCode 作为开源版 Claude Code适合需要多模型混用的场景。它的 Skills 搜索路径自动兼容 Claude 的目录不需要复制项目配置.opencode/skills/name/SKILL.md 全局配置~/.config/opencode/skills/name/SKILL.md 兼容 Claude 项目.claude/skills/name/SKILL.md 兼容 Claude 全局~/.claude/skills/name/SKILL.mdOpenCode 目前没有内置/skills命令可以通过对话询问 AI 列出当前可用技能。使用方式与 Claude Code 类似支持自动和手动引用。提示跨工具迁移时注意allowed-tools字段的兼容性。不同工具支持的工具名可能不同迁移后建议先跑一次验证。6. 常见报错与排查Skill 不触发、脚本失败、路径错误问题一/skills列表里看不到新技能。最常见原因是目录层级不对。正确路径是~/.claude/skills/my-skill/SKILL.md如果你放成了~/.claude/skills/SKILL.mdClaude 不会识别。另外检查SKILL.md文件名大小写必须是全大写。问题二Skill 存在但自动触发不生效。大概率是description写得太模糊。比如只写“处理文本”模型无法判断什么时候该加载。改成“将中文内容转换为英文 URL slug并将文章改写为小红书风格”这种具体描述匹配率会明显提升。问题三脚本执行失败。Skills 运行在本地代码执行环境受本地环境影响。比如脚本里用了python3但系统只有python就会报 command not found。建议在脚本开头加 shebang并在 SKILL.md 里注明依赖#!/usr/bin/env python3 # 依赖Python 3.8问题四YAML 元数据解析报错。检查name是否包含大写字母或下划线description是否超过 1024 字符。YAML 对缩进敏感冒号后面要加空格。问题五CodeX 里用/skill-name调用没反应。CodeX 的手动调用符号是$不是/。改成$my-zmt-tool再试。如果排查过程中需要重新生成 API Key 或查看接入文档可以走这两个入口API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先验证模型对话是否正常可以用模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。7. 把 Skill 用起来从单次调用到长期编码工作流Skill 真正的价值不在于省一次提示词而在于把重复工作流固化下来。如果你每天都在 Claude Code 里做类似任务建议把常用能力拆成独立 Skill按项目或全局存放。长期编码和 Agent 场景可以配合 Coding Plan 使用入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。一个实用技巧Skill 的description里把触发关键词写全比如“PDF 表格提取、表单填充、文档合并”这样模型在遇到相关任务时更容易自动加载。另外references/目录适合放团队规范文档assets/放模板文件脚本放scripts/保持 SKILL.md 本身简洁加载更快。最后提醒一点Skill 是开放标准今天在 Claude Code 里写的技能包明天可以复制到 CodeX 或 OpenCode 继续用。尽早沉淀自己的常用能力比每次重新描述需求划算得多。