做 AI 编程工具这几年真正拉开差距的从来不是模型聪明不聪明而是你有没有把自己团队的做事方法“灌”进工具里。Claude Code 之所以在 GitHub 上热度一直很高不是因为它能多写几行代码而是因为它提供了一套把“工作流程”变成“可复用能力”的机制也就是 Skill。这一期内容不聊虚的直接把 Skill 的创建、组合、从 GitHub 获取第三方技能包以及如何接入日常开发流程讲清楚。很多人装完 Claude Code打开就是一个终端对话框让它写个函数能写让它改个 bug 能改但换个项目、换个团队又回到了从零开始的状态。问题不在于 AI 不够强而是你没有一个能把“项目规范、代码风格、验证步骤”打包交给 AI 的载体。Skill 解决的就是这件事把一次性的“帮忙写代码”变成可持续的“按你的标准自动干活”。如果你最近刚好在折腾 Claude Code或者从 GitHub 下了一些 skill 却不知道怎么用这篇文章建议收藏后照着做。1. 这篇文章真正要解决的问题先给结论Claude Code 的安装本身并不难难的是让它在真实项目里稳定地输出符合预期的结果。大多数用户的体验曲线是这样的——第一次用觉得惊艳第二次用发现它不了解你的项目背景第三次用发现它每次都要重新交代一堆上下文效率反而下降了。Skill 的存在就是用来解决这个“每次都要重新交代”的问题。它相当于给 AI 预装了一份“项目岗位说明书”你的项目结构是什么、代码规范有哪些、常见的坑在哪里、处理某类任务时应该按什么步骤走。一旦定义好后续只需要一句话触发AI 就会按既定流程执行。这篇文章要覆盖四件事Claude Code 和 Skill 的基本概念以及它们和普通 Prompt 的本质区别Skill 的目录结构与创建方法包含可以直接复制的 SKILL.md 示例三个实用 Skill 的组合工作流从一个需求描述到代码生成再到代码审查将 Claude Code 接入 GitHub 日常协作流程的注意事项避免 AI 乱提交、乱改分支。无论你是前端、后端还是主要用 AI 做自动化脚本的开发者这套思路都适用。核心不是某个具体插件有多神而是你掌握“如何给 AI 定义能力边界”之后能把任何团队规范沉淀进工具里。2. 基础概念Claude Code、Skill 与组合插件的区别2.1 Claude Code 是什么Claude Code 是 Anthropic 推出的终端 AI 编程助手核心交互发生在命令行里。它可以直接读取项目文件、执行命令、编辑代码并且以会话方式与开发者协作。相比网页版聊天窗口它的优势在于“手”更长——能真实操作你的项目而不是只给一段建议。它通常具备这些能力读取项目目录结构理解上下文在用户确认后修改代码文件执行测试、构建等命令配合 Git 完成仓库操作通过扩展机制加载额外能力。安装方式比较统一命令行下通过 npm 全局安装即可node -v npm -v npm install -g anthropic-ai/claude-code claude --version安装完成后在项目根目录执行claude即可启动会话。如果是第一次使用需要先完成登录授权后续才能正常调用模型。2.2 Skill 是什么Skill 可以理解为“你交给 AI 的一份结构化操作手册”。它存储在项目的.claude/skills/目录下每个 Skill 是一个独立子目录子目录里有一个SKILL.md文件用于描述该能力的作用范围、触发条件和具体工作流程。通俗类比一下如果 AI 是一个新入职的工程师普通 Prompt 相当于你口头交代“帮我看一下这个页面为什么白屏”而 Skill 相当于你递给他一份《前端问题排查手册》里面写了“先看控制台报错、再查网络请求、然后检查组件生命周期、最后按规范输出修复方案”。效果差别显而易见。这正好解释了为什么单纯堆 Prompt 解决不了效率问题。口头交代每次都要重新说而且容易遗漏关键约束Skill 则把经验固化成了可重复执行的流程。2.3 插件、Skill 与普通 Prompt 的对比对比项普通 PromptSkill社区插件包是否可复用较低每次需重新描述高定义后随时触发高克隆即用是否能约束流程弱模型自由发挥强按操作手册执行取决于 Skill 内容是否包含工具权限无可声明允许使用的工具可声明团队共享成本需要复制粘贴文本直接入库Git 统一管理依赖仓库维护“插件”这个词在 Claude Code 社区里通常指的就是“被打包成 Skill 的扩展能力”。有些插件仓库会把多个 Skill 放在一个项目里方便用户一次克隆、按需选用。因此下文提到“组合插件”本质上就是多个 Skill 的组合使用。2.4 还需要知道的一点MCP 扩展Skill 负责“教会 AI 怎么按流程干活”而 MCPModel Context Protocol负责“让 AI 能连上更多外部数据源或工具”。两者可以互补。例如你可以在 Claude Code 中挂一个内部文档服务的 MCP让 AI 在按 Skill 流程执行时还能主动查询最新文档。claude mcp add team-docs --transport http --url http://your-internal-docs-service不过 MCP 的搭建属于另一个话题本期先以 Skill 为主线。了解这一点是为了避免你把 Skill 和 MCP 混为一谈。3. 环境准备与前置条件开始写 Skill 之前先把运行环境准备到可复现状态。以下步骤适用于常见开发系统版本细节请以你本机实际安装为准但思路是通用的。3.1 安装 Node.js 与 npmClaude Code 通过 npm 分发因此机器上需要有 Node.js 环境。node -v npm -v如果输出显示版本号说明环境正常。如果提示命令不存在需要先安装 Node.js LTS 版本再重新打开终端确认。3.2 安装并登录 Claude Codenpm install -g anthropic-ai/claude-code claude --version安装完成后在项目目录执行claude首次启动通常需要登录。根据界面提示完成授权。登录成功后可以用/status或/model命令确认当前会话使用的模型。需要注意Claude Code 版本迭代很快不同版本的配置命令可能略有差异。遇到“模型名称不识别”之类的报错优先查看官方更新日志而不是在配置文件里乱猜模型名。3.3 决定 Skill 放在项目级还是用户级Claude Code 的 Skill 可以放在不同层级项目级放在当前项目的.claude/skills/目录仅对当前仓库生效用户级放在用户主目录的~/.claude/skills/目录对所有项目生效。判断标准很简单如果这个 Skill 是团队项目规范放项目级并跟随 Git 仓库共享如果是你个人常用的通用方法放用户级。4. Skill 的目录结构与创建方法4.1 目录结构一个最小 Skill 的目录结构如下your-project/ ├── .claude/ │ └── skills/ │ └── frontend-codegen/ │ └── SKILL.md ├── src/ └── package.json这里的frontend-codegen是 Skill 名称目录名建议使用小写英文加连字符便于跨环境识别。4.2 SKILL.md 文件格式SKILL.md由两部分组成开头的 YAML 元信息和正文 Markdown 操作流程。--- name: frontend-codegen description: 根据需求描述生成前端静态页面代码包含 HTML、CSS 和基础交互。 allowed-tools: - Read - Write - Edit - Bash --- # 前端页面生成 Skill ## 适用场景 - 需要从产品描述快速生成可运行的静态页面 - 需要将低保真原型改写成规范的 HTML/CSS 页面 ## 工作流程 1. 读取项目根目录 docs/ 下的需求文档提取页面区块和交互要求。 2. 确定页面资源存放目录建议放在 src/pages/ 与 src/styles/ 下。 3. 生成 HTML 文件时遵循项目现有的 class 命名规范。 4. 生成 CSS 文件时使用项目已有的设计变量不引入新颜色体系。 5. 完成后输出文件清单和启动方式。字段解释字段作用是否必填nameSkill 的唯一名称必填description用一句话说明该 Skill 解决什么问题必填allowed-tools声明该 Skill 执行时可使用的工具白名单建议填写在 Claude Code 中定义allowed-tools是控制 AI 行为边界的关键。例如只让 Skill 读写代码文件不允许执行包管理命令就在白名单里去掉 Bash。这样能显著降低 AI 乱执行命令的风险。4.3 在对话中触发 SkillSkill 定义完成后不需要安装也不需要重启。你可以直接在 Claude Code 的对话里用自然语言触发也可以把 Skill 名称醒目地放在任务描述中。请使用 frontend-codegen 技能根据 docs/todo-app.md 的需求生成一个待办事项页面的完整实现。如果 Skill 的 description 写得足够清晰AI 可能会在任务匹配时自动调用。但更稳妥的做法是主动指定名称避免它凭感觉选择错误流程。4.4 从 GitHub 获取社区 Skill 包社区中有不少开发者把封装好的 Skill 包推到 GitHub 上你可以通过git clone方式获取然后放到项目的.claude/skills/目录下。cd your-project/.claude/skills git clone https://github.com/yourname/awesome-claude-skills.git接着检查克隆下来的项目目录结构只保留需要的 Skill 子目录删除无用的说明文档和示例文件避免干扰 Claude Code 识别。这里要特别提醒不要盲装来路不明的 Skill。Skill 本质是可执行指令一个恶意 Skill 完全可能诱导 AI 读取敏感文件、执行危险命令。安装前至少要看一遍 SKILL.md 内容确认它不会调用超出预期的工具再放进项目目录。5. 完整示例用组合 Skill 完成一个小需求迭代理论知识讲完下面用一个完整示例演示“组合插件”的实际打开方式。为了便于理解这里以“开发一个待办事项页面”为例。5.1 示例需求产品给了这样一段描述做一个待办事项页面用户可以新增待办、勾选完成、删除待办。页面要适配移动端和桌面端。数据先存在本地 localStorage后续再接入后端接口。按照传统方式你可能直接让 AI 一口气生成代码。但第一次生成的代码往往不符合项目规范还要反复改。使用组合 Skill 后流程会变成需求澄清 - 代码生成 - 代码审查。5.2 Skill A需求澄清.claude/skills/requirement-clarify/SKILL.md--- name: requirement-clarify description: 将模糊的产品描述拆解为可开发的需求点输出功能清单和边界条件。 allowed-tools: - Read - Write --- # 需求澄清 ## 工作步骤 1. 读取用户提供的需求描述。 2. 拆解出功能点区分 P0 必做与 P1 可延后。 3. 列出容易遗漏的边界条件空数据、超长文案、重复提交、设备适配。 4. 将结果输出到 docs/requirements.md。这个 Skill 的价值在于强制 AI 在写代码前先把“要做什么”想清楚而不是拿到描述就开工。5.3 Skill B前端代码生成.claude/skills/frontend-codegen/SKILL.md--- name: frontend-codegen description: 根据需求文档生成前端静态页面代码严格按照项目已有目录结构输出。 allowed-tools: - Read - Write - Edit --- # 待办页面代码生成 ## 输入 - docs/requirements.md ## 工作步骤 1. 读取 docs/requirements.md确认功能清单。 2. 按 modules/todo/ 目录组织代码 - todo.html页面结构 - todo.css样式 - todo.js交互逻辑 3. 使用原生 HTML/CSS/JS 实现不引入框架。 4. 数据存储使用 localStorage。 5. 页面必须兼容 375px 宽度移动端和 1280px 桌面端。这里没有给 AI 开放 Bash 权限目的是让它专注写代码不要在执行过程中顺手装依赖或跑脚本。5.4 Skill C代码审查.claude/skills/frontend-review/SKILL.md--- name: frontend-review description: 检查前端代码文件的功能完整性、可维护性和常见安全风险输出评审意见。 allowed-tools: - Read - Bash --- # 前端代码审查 ## 工作步骤 1. 读取 modules/todo/ 下所有代码文件。 2. 检查以下要点 - 是否有缺失的交互逻辑 - 是否有 XSS 风险例如通过 innerHTML 直接插入用户输入 - 样式是否覆盖移动端和桌面端 - 是否有重复代码 - 是否有关键函数缺少注释。 3. 输出评审结果按阻塞、重要、建议三级分类。注意代码审查 Skill 允许使用 Bash但仅用于查看文件内容和运行静态检查不应修改代码。5.5 组合调用在 Claude Code 中这样发起一次完整流程请依次使用 requirement-clarify、frontend-codegen、frontend-review 三个技能完成待办事项页面的开发。先澄清需求再生成代码最后审查代码。这种写法把责任边界划得很清楚AI 不能跳过需求澄清直接写代码也不能写完就宣称完成必须经过一轮审查。审查结果如果出现阻塞问题再回到代码生成阶段修复。5.6 示例执行结果执行完成后项目中会出现docs/requirements.md # 需求澄清产物 modules/todo/todo.html # 页面结构 modules/todo/todo.css # 页面样式 modules/todo/todo.js # 交互逻辑打开todo.html可以验证页面功能。如果发现 AI 在审查阶段提出了修改意见可以继续对话要求修复。整个过程的关键收获是需求、开发、审查这三个环节被 Skill 固化成了一条流水线而不是依赖每次重新口头说明。6. 把 Claude Code 接入日常 GitHub 工作流Skill 解决的是“AI 怎么干活”但开发工作始终绕不开团队协作。实际项目中你大概率还要把 AI 产出的代码提交到 Git 仓库。这一章讲清楚接入时的边界防止 AI 把你的仓库搞乱。6.1 推荐的工作流建议遵循以下流程从远程仓库拉取最新代码切出独立的功能分支在功能分支上使用 Claude Code 和 Skill 完成开发人工检查 diff确认没有误改无关文件手动完成 commit 和 push触发代码评审评审通过后合入主干分支。git pull origin main git checkout -b feat/todo-skill-demo # 在 Claude Code 中完成代码生成与审查 git diff git add docs/requirements.md modules/todo git commit -m feat: 使用组合 Skill 完成待办页面 git push origin feat/todo-skill-demo一个比较实用的经验是不要给 AI 开放自动 push 权限。AI 自动提交代码出现冲突或误操作之后排查成本往往比省下的几秒高得多。6.2 让仓库配置成为 Skill 的“项目上下文”Claude Code 支持通过项目配置文件持久化上下文例如在.claude/settings.json中声明项目级设置。团队可以在这里固化一些通用约束与 Skill 配合使用。{ permissions: { deny: [ Bash(npm publish:*), Git(force-push:*) ] } }上面的示例只是演示一种思路把危险操作默认拒绝AI 即使被诱导也不会执行发布和强制推送。实际配置项请以你使用的版本说明为准。6.3 Git 操作时最容易忽略的坑不要创建完分支就切换上下文Claude Code 是按目录读取上下文的工作目录混乱会导致它改错文件提交前一定用git diff --stat查看变更文件列表确认没有包含本地配置、密钥、临时文件如果团队有提交信息规范建议写成项目级 Skill 的一部分让 AI 在生成 commit message 时自动遵守。7. 常见问题与排查方法Skill 在使用过程中比较容易出现的问题主要有以下几类这里整理成排查表。遇到问题时先看现象再按表中顺序检查。问题现象可能原因排查方式解决方案Claude Code 启动失败Node.js 版本过低或未安装 npm执行 node -v、npm -v升级到 LTS 版本后重新安装登录授权失败网络环境无法访问授权服务查看终端报错信息确认代理设置切换到稳定网络重试Skill 不生效SKILL.md 格式错误或目录名不规范检查 YAML 头部是否正确目录是否在 .claude/skills/ 下修正格式后重新发起对话AI 没有按 Skill 流程执行description 描述不清晰或任务中未指定 Skill检查描述是否包含触发关键词在任务描述中显式写出 Skill 名称模型名称不识别版本与模型名称不匹配查看当前版本支持模型列表用 /model 命令选择不手写未知名称克隆 GitHub 仓库失败网络不稳定或仓库地址错误检查仓库地址尝试重新克隆更换网络环境或从可信渠道获取压缩包AI 修改了预期外文件没有限制 allowed-tools 或工作目录错误查看会话中文件操作记录为 Skill 收紧工具白名单重新确认工作目录多个 Skill 文件冲突不同 Skill 定义了同名产物检查输出路径是否重叠统一规划输出目录避免冲突三个比较典型的排查逻辑如果 Skill 文件没生效先看目录层级。.claude/skills/下必须直接是 Skill 子目录子目录里再放 SKILL.md中间不能再多套一层无关目录如果 AI 行为不受控优先检查 allowed-tools。大部分问题源自你给了 AI 过多工具权限尤其是 Bash如果改完 SKILL.md 仍然无效尝试新开一个会话。Claude Code 可能在当前会话中缓存了旧配置。8. 最佳实践与工程建议Skill 用起来不难但要用得稳还是有一些工程层面的细节需要注意。8.1 Skill 的命名与描述要“面向触发”SKILL.md 中的 description 不只是给人看的也是 AI 判断“何时该用这个 Skill”的依据。描述里应该包含足够的关键词。例如“根据需求描述生成前端页面代码包含 HTML、CSS 和基础交互”比“前端生成工具”更容易被正确触发。8.2 收紧权限遵循最小授权原则在 Skill 的 allowed-tools 中只声明完成该任务必需的工具。特别是涉及 Bash 时要明确 AI 可执行的命令范围。代码生成类 Skill 通常不需要 Bash代码审查类 Skill 可以只允许只读命令。8.3 不要把密钥和敏感信息写进 SkillSKILL.md 是纯文本文件通常会被提交到 Git 仓库。任何 API Key、数据库地址、登录凭证都不允许出现在里面。如果 Skill 需要引用内部信息建议通过环境变量或专门的密钥管理工具注入并在文档中注明“从环境变量读取”。8.4 控制组合数量先跑通最小闭环“组合 Skill”不等于“装得越多越好”。每一次组合都会增加上下文复杂度和出错概率。更稳妥的落地方式是从一个最小闭环开始一个需求澄清、一个生成、一个审查跑通后再逐步增加新 Skill。8.5 将 Skill 纳入版本控制团队协作时.claude/skills/目录应当纳入 Git 管理。这样团队所有人的 AI 行为规范保持一致Skill 的改进也有迹可查。同时Skill 变更应该走代码评审不要直接往主干提交未验证的 Skill 文件。8.6 关注版本兼容Claude Code 迭代速度较快Skill 的字段、权限模型和配置方式都可能变化。建议在项目文档里固定 Claude Code 版本或者在升级前先查看变更说明避免团队成员的本地环境版本不一致导致行为差异。9. 总结与后续学习方向如果这一期你只记住三句话那就是Skill 不是锦上添花的“插件”它是把团队经验固化给 AI 的核心载体组合使用 Skill 时要按“澄清 - 生成 - 审查”的流程拆解任务而不是让 AI 一把梭所有让 AI 自动执行的操作都要收紧权限尤其是 Git 提交和 Bash 命令。下一步建议找一个真实的小需求先手动创建两个 Skill 跑通流程再逐步扩展。你可以在 GitHub 上搜索社区维护的 Skill 集合但先学会读懂 SKILL.md 的格式再决定要不要引入。等你熟悉了这类结构也可以把团队的接口规范、部署流程、代码审查清单逐步沉淀成 Skill这才是 Claude Code 真正值得投入时间的方向。