Claude Code Skills 从零开始：创建、配置与实战

前言最近 Claude Code 的 Skills 功能逐渐成熟它解决了一个很实际的问题每次重复敲相同的指令或者团队里每个人都各自维护一套 prompt。Skills 本质上就是把这些高频操作固化成可复用的“技能包”用的时候/技能名调一下或者让 Claude 根据场景自动触发。花了一下午折腾了一下把过程记下来供参考。一、Skills 是什么Skills 是 Claude Code 的轻量级扩展机制核心就是一个文件夹。里面必须有一个SKILL.md文件告诉 Claude 这个技能是干什么的、该怎么执行。还可以附带脚本、模板、参考文档之类的辅助文件 。简单理解相当于给 Claude 写了一份“工作说明书”遇到对应场景就按这个流程干活。它解决了什么问题减少重复劳动代码审查、部署流程这类操作不用每次都重新描述团队规范统一把技能文件提交到 Git大家共用同一套流程知识沉淀把踩过的坑Gotchas写进技能里下次不会再犯Skills 和 MCP、Commands 的区别这三者容易搞混简单区分一下功能SkillsMCP ServersCommands本质指令集 知识库外部工具/API斜杠快捷命令谁触发Claude 自动或手动Claude 调用用户手动/xxx能做什么指导流程、注入知识读文件、调 API、执行脚本执行工作流上下文占用渐进式加载很轻量全量加载比较重按需加载引用一个社区的观点Skills 比 MCP 好在上下文更精简模型不需要把所有工具定义塞进窗口一个大的 MCP 服务可能吃掉四分之一上下文而 Skills 只有触发时才加载完整指令 。二、创建你的第一个 Skill2.1 确定存放位置Skills 可以放在两个地方取决于你想给谁用 bash# 全局所有项目都能用 mkdir -p ~/.claude/skills/my-first-skill # 项目级只对当前项目生效建议提交到 Git mkdir -p .claude/skills/my-first-skill2.2 编写 SKILL.md这是核心文件分两部分YAML 元数据头部和 Markdown 执行指令。我这里写了一个整理 Python import 顺序的技能作为示例 markdown--- name: python-import-organizer description: 当用户粘贴 Python 代码或要求整理 imports / 格式化代码 / 排序导入语句时按 PEP 8 isort 顺序整理标准库优先其次第三方库最后本地模块。不要用于非 Python 代码。 --- # Python Import Organizer 当用户要求整理 Python 导入语句时 1. 将 imports 分成三组标准库 / 第三方库 / 本地模块 2. 每组内按字母顺序排序 3. 组之间加一个空行 4. 只有在用户明确要求时才删除未使用的 import ## 注意事项Gotchas - 只整理 import 区块不要改函数代码 - 不要不经询问就自动删除 imports - 注意 from __future__ import annotations 这类特殊导入要放在最前面几个关键配置项说明name技能名只能用小写字母、数字、连字符description最重要Claude 靠它判断是否自动触发。要写清楚触发场景建议包含 2-3 个具体例子disable-model-invocation: true禁止 AI 自动调用只允许手动/技能名适合部署等高危操作allowed-tools技能执行时免授权可用的工具遵循最小权限原则2.3 测试调用重启 Claude Code让它重新扫描技能目录然后试一下text# 方式一直接描述需求让 Claude 自动匹配 帮我整理一下这段 Python 的 imports # 方式二手动调用 /python-import-organizer如果 Claude 不触发多半是description写得太笼统匹配不上对话内容 。三、进阶目录结构与渐进式加载一个完整的技能目录长这样 textmy-skill/ ├── SKILL.md # 必需核心配置 ├── reference.md # 可选详细文档Claude 按需读取 ├── examples.md # 可选输出示例 └── scripts/ # 可选辅助脚本 └── helper.sh渐进式加载的妙处Skills 启动时只加载SKILL.md中的name和description大约只占 100 tokens。触发后才加载完整指令脚本和参考文档则是在需要时才读取 。这个设计的好处是你可以把大量参考资料放在reference.md里不会把对话上下文撑爆Claude 只有在执行相关步骤时才会去翻文档。四、把 Skills 打包成 Plugin当你有多个技能需要跨项目共享时建议打包成 Plugin 。目录结构textmy-plugin/ ├── .claude-plugin/ │ └── plugin.json # 插件清单 └── skills/ ├── code-review/ │ └── SKILL.md └── deploy/ └── SKILL.mdplugin.json 示例json{ name: my-plugin, description: 团队内部常用技能集, version: 1.0.0, author: { name: Your Team } }本地测试bash# 带插件启动 claude --plugin-dir ./my-plugin # 调用时加命名空间前缀 /my-plugin:code-review插件里的 skills 会自动加上命名空间如/my-plugin:xxx避免不同插件同名冲突 。五、社区技能推荐不想从零写的话可以直接用社区现成的。几个我觉得不错的Anthropic 官方技能包bashgit clone https://github.com/anthropics/skills.git ~/.claude/skills/anthropic-skills包含 docx、xlsx、pptx、pdf 等文档处理技能直接能用。claude-skills-suite40 个技能合集覆盖前端、后端、数据库、安全审查等场景 。Skill Wizard交互式创建工具会问你一系列问题然后生成技能 bashgit clone https://github.com/greeun/skill-wizard.git ~/.claude/skills/skill-wizard # 然后说 我要创建一个新技能它会引导你完成六、踩坑记录description 写得太宽泛Claude 要么不触发要么不该触发的时候触发。解法是描述里明确写 When the user asks X / Y / Z 和 Do NOT use for ... 来收窄范围 。把 SKILL.md 写成了通用教程Anthropic 团队的建议是不要在技能里重复 Claude 本来就知道的东西。要聚焦在它不知道的信息上——比如你们公司的 API 坑点、特殊的业务流程、内部库的使用规范 。Gotchas 章节价值最高把之前踩过的坑记录在技能里下次 Claude 就不会再犯。这是技能迭代的重点 。不要过度指定步骤给 Claude 必要的指引就好留点灵活性让它根据实际情况调整。写得太死反而不一定执行得好 。总结Skills 的核心就三件事怎么放~/.claude/skills/或.claude/skills/怎么写一个 SKILL.md 文件YAML 元数据 Markdown 指令怎么用自动触发或手动/技能名把团队里反复做的那些事——代码审查、环境配置、部署流程、文档生成——沉淀成 Skills长期来看还是挺划算的。