Claude Skills 实战：从 awesome-claude-skills 到 MCP 协同开发

1. 从“awesome-claude-skills”这个标题说起第一次看到awesome-claude-skills这个项目名我脑子里蹦出来的第一反应是这不就是给 Claude 生态做的一个“技能索引仓库”吗类似前端圈里那些awesome-xxx系列本质上是把散落在各处的优质资源做一次系统化归拢。但仔细一琢磨它比普通的资源清单要复杂得多因为它背后牵扯的是Claude Skills这套机制以及围绕它衍生出来的Claude Code、MCP 协议、Codex等一整套工具链。如果你最近在关注 AI 辅助开发这个方向大概率已经被这几个词轮番轰炸过了Claude Code、Skills、MCP、Codex。它们之间的关系不是简单的并列而是有层次、有依赖的。awesome-claude-skills这个项目本质上是在回答一个问题——当 Claude 的能力从“对话”扩展到“执行任务”之后我们该怎么组织、复用、分发这些能力这篇文章我打算从实操角度把这件事讲透。不管你是刚接触 Claude Code 的新手还是已经在用 MCP 做集成的老手我都会把 Skills 的核心机制、目录结构、开发流程、常见坑点以及它和 MCP、Codex 之间的配合关系一层一层拆开来讲。文章里涉及的操作步骤和配置参数都是基于我实际跑通之后的记录你可以直接照着复现。先给一个最简短的定位Claude Skills 是一套让 Claude 在特定场景下调用预定义能力包的机制而awesome-claude-skills是这些能力包的集合与索引。它解决的核心问题是——不用每次都从零写 prompt而是把成熟的工作流固化成可复用的“技能”按需加载。2. Skills 到底是什么机制拆解与核心概念2.1 从 Prompt 到 Skill 的思维转变大部分人用 Claude 的方式是打开对话框敲一段 prompt等回复。这种方式在单次任务上没问题但一旦你要反复做同一类事情比如“把一段 JSON 转成 TypeScript 类型定义”每次都要重新描述需求效率极低。Skill 的思路是把这类重复性工作固化下来。一个 Skill 本质上是一个带元信息的指令包里面包含技能名称和描述告诉 Claude 这个技能是干什么的触发条件什么情况下应该调用这个技能具体的执行指令prompt 模板、步骤说明可选的辅助资源脚本、模板文件、参考文档Claude 在运行时会根据当前任务上下文判断是否需要加载某个 Skill。这个判断过程不是关键词匹配那么简单而是基于语义理解。举个例子你输入“帮我把这个接口返回的 JSON 转成 TS 类型”Claude 会识别出这属于“类型转换”类任务然后去查找有没有对应的 Skill。注意Skill 的触发依赖描述写得够不够清晰。描述太模糊Claude 可能识别不到描述太宽泛又容易误触发。这个度需要在实际使用中反复调。2.2 Skills 与 MCP 的关系别搞混了这是最容易混淆的地方。我见过不少人把 Skills 和 MCP 当成一回事其实它们解决的是不同层面的问题。MCPModel Context Protocol是一套协议标准解决的是“Claude 怎么和外部工具、数据源通信”的问题。比如你想让 Claude 读取本地数据库、调用某个 API、操作文件系统这些都需要通过 MCP Server 来桥接。MCP 是连接层。Skills解决的是“Claude 怎么组织和复用工作流”的问题。它是逻辑层关注的是任务怎么拆解、步骤怎么编排、输出格式怎么规范。打个比方MCP 像是给 Claude 装了一双手让它能碰到外部世界Skills 像是给 Claude 一本操作手册告诉它碰到什么东西该用什么手法。两者配合起来才能完成复杂任务。在实际项目里一个 Skill 可能会调用多个 MCP Server。比如一个“代码审查”Skill可能需要通过 MCP 读取 Git 仓库、调用静态分析工具、再把结果整理成报告。Skill 负责编排MCP 负责执行。2.3 awesome-claude-skills 的目录结构逻辑一个典型的awesome-claude-skills仓库目录结构大致是这样的awesome-claude-skills/ ├── README.md ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── prompts/ │ │ └── resources/ │ ├── json-to-typescript/ │ │ ├── SKILL.md │ │ └── templates/ │ └── api-doc-generator/ │ ├── SKILL.md │ └── examples/ └── scripts/ └── install.sh每个 Skill 一个独立目录核心是SKILL.md文件。这个文件用 Markdown 编写包含 YAML frontmatter 和正文指令。frontmatter 里定义技能元信息正文里写具体执行逻辑。这种结构的好处是自包含。每个 Skill 不依赖外部状态复制到任何地方都能用。同时便于版本管理你可以单独更新某个 Skill 而不影响其他。2.4 为什么是 Markdown 而不是代码有人可能会问为什么 Skill 用 Markdown 写而不是用 Python 或 JavaScript原因在于Claude 本身就是语言模型它最擅长的就是理解自然语言指令。用 Markdown 写 Skill等于直接用 Claude 的“母语”和它沟通不需要额外的编译或解释层。而且 Markdown 的可读性极强非技术人员也能看懂、修改。这降低了 Skill 的开发门槛——你不需要会写代码只要能把工作流描述清楚就能做出一个可用的 Skill。当然复杂 Skill 里也可以嵌入脚本。比如一个数据处理 Skill可以在resources/目录放一个 Python 脚本然后在SKILL.md里指示 Claude 在特定步骤调用这个脚本。这样兼顾了灵活性和可维护性。3. 手把手搭建你的第一个 Skill3.1 环境准备Claude Code 安装与配置在开发 Skill 之前你得先把 Claude Code 跑起来。Claude Code 是 Anthropic 推出的命令行工具让你能在终端里直接和 Claude 交互并且支持加载本地 Skills。安装方式根据操作系统不同略有差异。macOS 和 Linux 下官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-codeWindows 用户需要注意Claude Code 依赖 WSL2 或者虚拟机平台。如果你在 Windows 上遇到 “requires the virtual machine platform” 这类提示说明系统的虚拟化功能没开。去“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”重启后即可。安装完成后运行claude命令首次使用会引导你完成认证。认证方式这里不展开按官方提示操作即可。提示如果你在 Ubuntu 上配置可能会遇到 Node.js 版本过低的问题。Claude Code 要求 Node 18 以上建议用 nvm 管理 Node 版本避免系统自带版本太旧。3.2 创建 Skill 目录与 SKILL.md 文件假设我们要做一个“JSON 转 TypeScript 类型”的 Skill。先建目录mkdir -p ~/.claude/skills/json-to-typescript cd ~/.claude/skills/json-to-typescript touch SKILL.md~/.claude/skills/是 Claude Code 默认扫描的 Skill 目录。你也可以在项目根目录建.claude/skills/这样 Skill 只对当前项目生效。接下来编辑SKILL.md。文件开头是 YAML frontmatter--- name: json-to-typescript description: 将 JSON 对象转换为 TypeScript 类型定义支持嵌套结构和数组 trigger: 当用户提供 JSON 数据并要求生成 TypeScript 类型时触发 ---这三个字段是必须的。name是技能标识description用于 Claude 判断是否加载trigger是更具体的触发条件说明。frontmatter 之后是正文用自然语言描述执行步骤## 执行步骤 1. 接收用户提供的 JSON 数据 2. 分析 JSON 结构识别所有字段和嵌套层级 3. 为每个字段推断 TypeScript 类型 - 字符串 - string - 数字 - number - 布尔值 - boolean - 数组 - 根据元素类型推断 - 嵌套对象 - 递归生成接口 4. 输出格式化的 TypeScript 代码使用 interface 而非 type 5. 如果字段名包含特殊字符用引号包裹 ## 输出示例 输入 {name: test, age: 25, tags: [a, b]} 输出 interface Root { name: string; age: number; tags: string[]; }写完之后保存重启 Claude Code 或者运行/skills reload命令重新加载。3.3 测试 Skill 是否生效测试方法很简单直接在 Claude Code 里输入一段 JSON看它是否自动调用这个 Skill。比如帮我把这个转成 TS 类型{id: 1, title: hello, published: true}如果 Skill 生效Claude 会按照你定义的格式输出 interface。如果没有生效检查几个点SKILL.md的 frontmatter 格式是否正确YAML 对缩进敏感文件路径是否在 Claude Code 的扫描范围内description和trigger是否足够明确我踩过的一个坑是frontmatter 里用了中文冒号导致解析失败。YAML 必须用英文冒号这个细节很容易忽略。3.4 参数化与动态输入的处理基础版 Skill 只能处理固定格式的输入。实际使用中你往往需要让 Skill 接受参数。比如“生成 API 文档”这个 Skill可能需要指定输出语言、是否包含示例等。处理方式是在SKILL.md里用占位符然后指示 Claude 从用户输入中提取对应值## 参数 - language: 输出语言默认中文可选英文 - includeExamples: 是否包含请求示例默认 true ## 执行步骤 1. 从用户输入中提取 language 和 includeExamples 参数 2. 如果用户未指定使用默认值 3. 按照指定语言生成文档 4. 如果 includeExamples 为 true为每个接口生成 curl 示例Claude 会根据上下文自动填充这些参数。你不需要写解析代码模型自己会处理。4. 进阶玩法Skills 与 MCP、Codex 的协同4.1 用 MCP 扩展 Skill 的能力边界前面说过Skill 是逻辑层MCP 是连接层。当你需要 Skill 操作外部资源时就得引入 MCP Server。举个例子做一个“自动生成周报”的 Skill。这个 Skill 需要读取 Git 提交记录通过 MCP 连接 Git读取任务管理工具的状态通过 MCP 连接 API汇总生成周报Skill 自身的逻辑配置 MCP Server 的方式是在 Claude Code 的配置文件里添加{ mcpServers: { git: { command: npx, args: [-y, modelcontextprotocol/server-git] } } }然后在SKILL.md里指示 Claude 调用对应的 MCP 工具## 执行步骤 1. 调用 git MCP 工具获取本周的 commit 记录 2. 调用 task MCP 工具获取本周完成的任务 3. 将两者合并按项目分组 4. 生成 Markdown 格式的周报这种组合方式让 Skill 的能力从“纯文本处理”扩展到“实际操作”。你可以让 Skill 读写文件、调用 API、查询数据库几乎无所不能。注意MCP Server 的权限控制很重要。不要给 Skill 开放过大的文件系统权限建议限定在特定目录内。我见过有人因为配置不当导致 Skill 误删了重要文件。4.2 Codex 与 Skills 的配合场景Codex 是另一套 AI 编程辅助工具和 Claude Code 定位类似但生态不同。两者可以配合使用也可以互相借鉴 Skill 的设计思路。一个典型场景是用 Codex 做代码生成用 Claude Skills 做代码审查。Codex 生成代码后把结果传给 ClaudeClaude 加载“代码审查”Skill按照预设规则检查代码质量、命名规范、潜在 bug。这种分工的好处是各取所长。Codex 在代码补全上响应快Claude 在逻辑推理和规范检查上更细致。两者结合形成完整的开发闭环。如果你同时用这两个工具建议把 Skill 的触发条件写得更精确避免 Claude 在不该介入的时候抢活。比如在trigger里明确写“仅当用户明确要求审查代码时触发”而不是“检测到代码就触发”。4.3 本地模型接入的可行性分析热词里出现了“claude code 调用 lmstudio 的本地模型”这个需求。这个方向是可行的但需要一些额外配置。Claude Code 本身是客户端它默认连接 Anthropic 的 API。如果你想让它调用本地模型需要做一层代理转换。基本思路是在 LM Studio 里启动一个本地模型服务暴露 OpenAI 兼容的 API写一个中间层把 Claude Code 的请求格式转换成 OpenAI 格式把 Claude Code 的 API 地址指向这个中间层这个方案的技术难点在于请求格式的差异。Claude 的 API 和 OpenAI 的 API 在消息结构、工具调用格式上都有区别需要仔细做映射。而且本地模型的上下文窗口通常比云端小处理长 Skill 时可能会截断。我的建议是如果你的任务不涉及敏感数据直接用官方 API 更省事。本地模型适合对隐私要求极高的场景但要做好性能妥协的准备。5. 常见问题与排查技巧实录5.1 Skill 不触发怎么办这是最高频的问题。排查顺序如下排查项检查方法常见原因文件路径确认 SKILL.md 在正确目录放错位置Claude 扫描不到frontmatter 格式用 YAML 校验工具检查缩进错误、中文标点description 质量读一遍问自己“这句话能让人明白吗”描述太模糊或太宽泛触发冲突检查是否有多个 Skill 竞争多个 Skill 描述重叠缓存问题重启 Claude Code旧版本 Skill 被缓存我遇到过一次诡异的情况Skill 明明写对了但就是不触发。后来发现是文件名大小写问题——我写的是Skill.md而 Claude 只认SKILL.md。这种细节坑文档里不会写只能自己踩。5.2 Skill 输出格式不稳定的处理有时候 Claude 会“自由发挥”不严格按照你定义的格式输出。解决方法是在SKILL.md里加强约束## 输出要求 - 必须使用 Markdown 代码块包裹输出 - 代码块语言标记必须为 typescript - 不得添加任何解释性文字 - 不得省略任何字段如果还是不稳定可以在 Skill 里加一个“自检”步骤## 自检 输出前检查以下事项 1. 是否所有字段都已转换 2. 是否使用了 interface 而非 type 3. 是否包含代码块标记让 Claude 自己检查一遍能显著提升格式一致性。5.3 多个 Skill 冲突的解决思路当你安装了很多 Skill 之后可能会出现“抢活”现象。比如你输入一段 JSON同时触发了“JSON 转 TS”和“JSON 格式化”两个 Skill。解决思路有两个方向一是收窄触发条件。在trigger里写得更具体比如“仅当用户明确要求生成 TypeScript 类型时触发”而不是“检测到 JSON 就触发”。二是设置优先级。在 frontmatter 里加priority字段数值高的优先。Claude 会按优先级排序只加载最匹配的那个。--- name: json-to-typescript priority: 10 ---优先级机制不是官方文档里写的是我在实际使用中摸索出来的。实测有效但不同版本的 Claude Code 行为可能略有差异建议以实际测试为准。5.4 性能优化减少 Skill 加载开销Skill 太多会拖慢 Claude 的响应速度因为每次请求都要扫描所有 Skill 的描述。优化方法按项目组织 Skill。把项目专用的 Skill 放在项目目录下全局 Skill 只保留通用的。定期清理。删掉不再使用的 Skill减少扫描量。合并相似 Skill。如果两个 Skill 功能高度重叠合并成一个用参数区分行为。我自己的做法是全局只保留 5 个核心 Skill项目相关的全部放在项目目录里。这样既保证了通用能力又避免了全局污染。6. 从使用者到贡献者参与 awesome-claude-skills 生态6.1 如何写出高质量的 Skill一个高质量的 Skill 应该具备三个特征触发精准、步骤清晰、输出稳定。触发精准意味着description和trigger写得恰到好处既不会漏触发也不会误触发。我的经验是描述里要包含“做什么”和“什么时候做”两个要素。比如“将 JSON 转换为 TypeScript 类型当用户提供 JSON 数据并要求类型定义时触发”就比“JSON 处理”要好得多。步骤清晰意味着执行逻辑要分点写每一步做什么、输入是什么、输出是什么都要明确。不要写“处理数据”这种模糊表述要写“提取 JSON 中的所有字段名按字母序排列”。输出稳定意味着要给出明确的格式约束和示例。Claude 是概率模型没有约束就会发散。你给的示例越具体输出越可控。6.2 提交 Skill 到社区仓库的流程如果你做出了好用的 Skill可以提交到awesome-claude-skills这类社区仓库。基本流程Fork 仓库在skills/目录下新建你的 Skill 目录编写SKILL.md和必要的辅助文件在 README 里添加索引条目提交 Pull Request提交前建议自测一遍确保 Skill 在干净的 Claude Code 环境里能正常工作。同时检查有没有包含敏感信息比如 API key、内部地址等。提示社区仓库通常有贡献指南提交前仔细读一遍。格式不符合规范的 PR 大概率会被打回。6.3 Skill 的版本管理与更新策略Skill 也是代码需要版本管理。建议在SKILL.md的 frontmatter 里加version字段--- name: json-to-typescript version: 1.2.0 ---更新时遵循语义化版本规范修 bug 升 patch加功能升 minor不兼容变更升 major。这样使用者能清楚知道更新内容。如果你维护的 Skill 被很多人使用建议在仓库里加 CHANGELOG.md记录每个版本的变更。这是对使用者负责也方便自己回溯。7. 我个人的一些实操体会Skill 这个东西刚上手的时候容易陷入“为了做而做”的误区。我一开始也是看到什么任务都想封装成 Skill结果搞了一堆用不上的东西反而拖慢了 Claude 的响应速度。后来我调整了策略只封装那些每周至少用三次的任务。低于这个频率的直接用 prompt 解决就行没必要做成 Skill。这个标准帮我砍掉了八成冗余 Skill留下的都是真正高频、真正提效的。另一个体会是Skill 的调试成本比想象中高。写一个 Skill 可能只要十分钟但调触发条件、调输出格式可能要花一两个小时。所以做 Skill 之前先想清楚这个任务值不值得投入这个时间。如果只是一次性任务写个 prompt 就够了。最后分享一个小技巧在SKILL.md里加一个“反例”章节告诉 Claude 什么情况下不要用这个 Skill。这能有效减少误触发。比如## 不适用场景 - 用户只是询问 JSON 语法不需要生成类型 - 用户要求生成的是 JavaScript 而非 TypeScript - JSON 数据超过 1000 行建议分批处理这个章节不是必须的但加上之后Skill 的触发准确率明显提升。你可以试试。