很多开发者在第一次听到“Claude Skills”时第一反应是“这不就是提示词模板吗”。实际接触之后会发现它更像是把提示词、脚本、参考文档、执行工作流打包成一个可复用单元的结构化方案。ComposioHQ 维护的awesome-claude-skills仓库则是目前社区里整理 Claude Skills 资源比较集中的一份精选列表。本文将围绕这个仓库展开讲清楚 Claude Skills 的核心机制、目录结构、安装方式并给出一个可直接上手的本地技能编写示例最后补充常见报错和工程化建议。无论你是刚接触 Claude Claude 的新手还是已经在用 Claude Code 做自动化任务的进阶开发者这篇文章都值得收藏备用。1. 背景与核心概念Claude Skills 到底是什么1.1 从“复制粘贴提示词”到“可复用技能”在日常使用 Claude 的过程中很多开发者会遇到一个场景每天都要让模型执行同一类任务比如“总结代码变更”“生成 PR 描述”“检查 Markdown 文档格式”。过去最简单粗暴的做法是把一长段提示词复制进对话框或者保存在本地笔记里反复粘贴。这种做法有三个明显问题提示词不稳定每次粘贴时可能漏掉某一段或者不小心改错了措辞模型输出质量随之波动。上下文被浪费长提示词每次都进入上下文窗口消耗 token也压缩了真正重要的业务信息空间。知识无法沉淀某位同事总结出来的“最佳提示词”只在个人笔记里团队其他人完全不知道也没有版本管理。Claude SkillsAgent Skills就是为了解决这个问题出现的。它本质上是一个标准化的技能包一个文件夹里包含SKILL.md主文件用来告诉 Claude 这个技能是做什么的、应该按什么步骤执行同时可以附带脚本、模板、参考文档等资源文件。当技能被安装到指定目录后Claude 会在对话或任务执行过程中自动识别并调用它。调用时不需要把完整技能内容塞进每一轮对话只需要通过自然语言或技能名的方式触发模型会按需加载技能内容。1.2 Claude Skills 和 MCP、Function Calling 的区别刚接触这个概念时很容易把 Skills、MCPModel Context Protocol和 Function Calling 混为一谈。这里用一个表格梳理三者的边界概念核心作用典型场景和 Claude Skills 的关系Function Calling让模型输出结构化参数调用外部函数天气查询、数据库查询、订单创建偏底层能力Skills 可以调用函数完成动作MCP统一协议连接外部工具和数据源GitHub、Slack、数据库连接器打开外部系统通道Skills 可以封装 MCP 工具的使用流程Claude Skills打包提示词、脚本和参考材料把“做事的方法”标准化代码审查、文档生成、工作流自动化偏方法论和知识封装描述“怎么做”简单理解MCP 解决的是“模型能连上哪些外部系统”Skills 解决的是“模型应该如何高质量完成某类任务”。比如你已经有 GitHub MCP 工具模型可以读取仓库、创建 Issue但未必知道“一个好的 PR 描述应该包含哪些模块、按什么顺序写”。通过安装一个pr-description技能模型就知道了这套规范并在执行时自动套用。1.3 awesome-claude-skills 在生态中的位置ComposioHQ 本身是 AI Agent 集成平台主要做工具和 API 的连接层。awesome-claude-skills是其维护的一份 GitHub 精选列表聚集了社区里质量较高的 Claude Skills 资源。仓库名字沿用了 Awesome 系列的命名惯例特点是分类清晰、更新较快、社区贡献为主。对于普通开发者来说这份仓库最实用的价值不是“把里面所有技能都装上”而是提供一个发现技能的入口你可以快速知道社区里已有哪些技能方向、哪些作者在做贡献、当前主流技能长什么样然后挑选其中少量技能深入阅读源码甚至可以借鉴其结构编写属于自己的技能。2. 环境准备与部署位置2.1 版本与环境说明Claude Skills 能力与 Claude 客户端、Claude Code 的版本强相关。本文示例以 2025 年下半年公开的 Claude 能力为参考具体路径和行为请以你当前版本的实际表现为准。在动手之前建议先确认以下环境一个可正常使用的 Claude 账号订阅版或 API 可用。如果使用 Claude Code请确保 CLI 已安装并能正常登录。操作系统不限Linux、macOS、WindowsWSL 环境更推荐均可。如果技能涉及脚本执行还需要对应的运行时比如 Node.js、Python 或 Shell。不同客户端加载技能的方式不完全一样但常见的目录约定是用户级目录~/.claude/skills项目级目录项目根目录/.claude/skills项目级目录一般优先于用户级目录便于针对不同项目挂载不同技能。2.2 查看技能目录是否生效可以先创建目录并确认路径。在终端执行mkdir -p ~/.claude/skills ls -la ~/.claude/skills如果是在项目中使用则在项目根目录执行mkdir -p .claude/skills ls -la .claude/skills对于刚接触 Claude Code 的读者可以用下面命令查看版本claude --version如果命令提示找不到claude说明 Claude Code 未安装或未加入 PATH需要先完成 CLI 的安装和登录配置。2.3 安装社区技能的基本步骤以awesome-claude-skills仓库为例一般安装流程是克隆或下载仓库找到你需要的技能目录。将技能目录复制到~/.claude/skills或项目的.claude/skills下。重启 Claude Code 会话或重新打开 Claude 客户端。在对话中用自然语言描述任务观察技能是否触发。# 克隆仓库到本地用于查看和挑选技能 git clone https://github.com/ComposioHQ/awesome-claude-skills.git # 进入仓库目录 cd awesome-claude-skills # 查看仓库结构 ls -la需要注意不是仓库中所有内容都可以直接复制使用。每个技能文件夹内部必须包含合法的SKILL.md文件才会被 Claude 识别。后续章节会详细拆解这个文件的结构。3. 核心机制拆解一个 Skill 的结构与原理3.1 SKILL.md 文件结构一个标准的 Claude Skill 目录通常长这样your-skill-name/ ├── SKILL.md ├── assets/ │ ├── example-input.md │ └── template.md └── scripts/ └── generate_report.pySKILL.md是技能的核心入口一般由两部分组成YAML Frontmatter位于文件最上方用---包裹声明技能的元信息比如name和description。Markdown 正文在 Frontmatter 之后用自然语言描述技能的执行流程、注意事项、示例和判断条件。一个最简单的SKILL.md示例如下--- name: markdown-format-checker description: 检查 Markdown 文档的标题层级、代码块标注和列表格式并输出规范化建议。 --- # Markdown 格式检查 当用户要求检查 Markdown 格式或文档规范时请按以下步骤执行 1. 读取用户提供的 Markdown 文件内容。 2. 检查一级标题是否重复、H2/H3 层级是否跳跃。 3. 检查代码块是否标注语言类型。 4. 检查列表缩进是否一致。 5. 输出问题列表和修改建议。 如果文件较长先输出目录结构总览再逐段检查。3.2 Frontmatter 中的关键字段在SKILL.md中description字段非常关键。Claude 判断是否调用技能主要依赖的就是这段描述。它相当于技能的“广告词”决定了什么场景下能被命中。几个建议description要写清楚“什么时候用”而不是只写“这是什么”。尽量在描述中自然包含触发词比如“检查 Markdown”“梳理文档结构”“生成 PR 描述”。不要写得过长否则每次对话都会消耗额外 token。name字段要具备区分度因为你可能同时安装多个技能。如果描述写得太模糊比如“处理文档”可能会导致技能在无关场景下被错误触发如果写得太窄比如“检查 Etsy 商品描述是否超过 140 字”则可能在实际使用中很难命中。3.3 正文内容与 assets、scriptsSKILL.md正文的作用是告诉 Claude“具体怎么做”。你可以把正文理解为一套为模型准备的作业指导书。正文里可以包含清晰的步骤清单。输入、输出格式。边界条件和异常处理规则。对脚本的调用方式。参考示例。assets和scripts目录则用于存放辅助资源。assets/存放模板、示例文件、参考文档等。它们不会被执行只作为模型生成内容时的参考材料。scripts/存放可执行脚本。Claude 在需要时可能会调用这些脚本完成数据处理、文件生成等操作。比如你写了一个“日报生成”技能SKILL.md描述工作流assets/template.md提供日报模板scripts/aggregate_data.py负责从多个 CSV 汇总数据。这样技能就是一个完整的小工具而不是单纯一段提示词。3.4 技能如何被触发Claude Skills 的触发方式主要有两种自动触发用户输入与技能描述高度匹配模型自动加载技能内容。显式触发用户直接输入技能名强制指定使用某个技能。对于自动触发模型会先读取当前可用技能的name和description判断是否需要使用。因此描述写得越精准触发成功率越高。显式触发则适合“自己知道要用哪个技能、不希望模型自由发挥”的场景。比如你已经知道有个pr-helper技能可以直接在对话中指出。4. 完整实战编写并挂载一个本地 Claude Skill4.1 需求场景为了让读者更直观地理解我们编写一个本地技能git-pr-helper。这个技能的功能是分析当前 Git 仓库的改动内容生成一份结构化的 PR 描述并附带 reviewer 检查点。为什么选这个场景因为它在日常开发中高频出现而且涉及代码执行读取git diff、结构化输出PR 模板和检查清单能覆盖一个技能的大部分要素。4.2 创建目录和文件首先创建目录结构mkdir -p ~/.claude/skills/git-pr-helper mkdir -p ~/.claude/skills/git-pr-helper/scripts如果你的项目想单独使用也可以创建在项目目录mkdir -p .claude/skills/git-pr-helper mkdir -p .claude/skills/git-pr-helper/scripts4.3 编写 SKILL.md创建文件~/.claude/skills/git-pr-helper/SKILL.md内容如下--- name: git-pr-helper description: 分析 Git 仓库的代码变更生成 PR 描述和 reviewer 检查清单。当用户要求生成 PR 描述、总结 git diff、准备代码审查时使用。 --- # Git PR Helper 当用户请求生成 PR 描述或审查代码变更时按以下步骤执行。 ## 第一步获取变更概览 在项目根目录执行 bash git diff HEAD --stat如果仓库没有提交历史或者用户指定了分支则改用git diff main...HEAD --stat如果出现错误提示先检查当前是否处于未提交状态还是跨分支比较然后选择合适的 diff 命令。第二步查看具体变更执行git diff HEAD如果改动文件数量很大优先输出每个文件的摘要再按重要程度输出完整 diff。重点观察新增或删除的核心业务逻辑。配置文件和依赖变更。数据库脚本或迁移文件。明显的调试残留代码。第三步生成 PR 描述按照以下模板输出 PR 描述## 变更背景 用 2-3 句话描述为什么做这次变更 ## 主要改动 - 模块 A新增 xxx 功能 - 模块 B重构 xxx 逻辑 - 模块 C修复 xxx 问题 ## 影响范围 - 受影响接口 - 受影响数据表 - 是否需要回归测试 ## Reviewer 检查点 - [ ] 是否有调试代码残留 - [ ] 是否包含敏感信息或硬编码密钥 - [ ] 是否存在明显的事务或并发问题 - [ ] 是否补充了必要的测试 - [ ] 依赖变更是否合理如果用户提供了团队 PR 模板优先使用用户模板替换上述结构。输出格式直接输出 Markdown 格式的 PR 描述不要额外解释执行过程。注意上面代码块中的多级 Markdown 在真实文件里要保持缩进正确。这里的重点是展示 SKILL.md 的写法而不是直接复制的最终文件。 ### 4.4 添加辅助脚本 为了让技能更完整我们再添加一个辅助脚本 scripts/changed_files.sh用于输出变更文件列表和对应行数 bash #!/usr/bin/env bash # 文件路径~/.claude/skills/git-pr-helper/scripts/changed_files.sh echo Changed Files git diff HEAD --stat echo echo Changed File List git diff HEAD --name-only执行前赋予执行权限chmod x ~/.claude/skills/git-pr-helper/scripts/changed_files.sh然后在SKILL.md的第一步中可以补充一句也可以直接运行bash ~/.claude/skills/git-pr-helper/scripts/changed_files.sh获取变更列表。这样做的好处是当 Claude 在某些环境中无法直接解析git diff --stat输出时可以通过脚本获得稳定格式的结果。4.5 在 Claude Code 中验证保存文件后进入任意一个 Git 项目目录启动 Claude Codeclaude在会话中输入帮我生成这个分支的 PR 描述观察 Claude 是否加载了git-pr-helper技能按步骤执行git diff并输出结构化 PR 描述。如果技能未触发可以尝试显式指定使用 git-pr-helper 生成 PR 描述如果依然没有生效请参考下一章排查方案。5. 精选仓库中的技能方向与选择思路5.1 社区技能常见类别浏览awesome-claude-skills时你会发现社区技能主要集中在以下方向方向典型能力适用对象代码工程生成 PR 描述、代码审查、提交信息规范化后端、前端、全栈开发者文档处理Markdown 格式化、技术文档翻译、需求文档拆分文档工程师、开发组长项目管理周报生成、会议纪要素材整理、Issue 分类研发管理岗位数据分析CSV 文件总结、SQL 优化建议、数据质量检查数据开发、运维、测试个人效率邮件摘要、日程规划、会议记录结构化所有办公场景这些分类并不严格很多技能同时覆盖多个方向。关键是从中挑选与自身工作流最贴近的 2 到 3 个进行深入研究。5.2 如何评估一个技能的质量从仓库中看到某个技能时不要急于安装。建议按以下标准评估Frontmatter 是否完整name和description是否存在描述是否清晰。正文是否有可执行步骤技能不能只说“做高质量总结”要给出具体步骤、命令或判断规则。是否有示例和边界说明好的技能会说明什么情况下不使用、输入缺失时如何处理。脚本是否可审计如果技能附带脚本应打开阅读一遍确认没有危险命令或可疑行为。维护活跃度优先选择近期仍在更新的技能而不是长期无人维护的冷门项目。5.3 从“使用技能”到“自研技能”awesome-claude-skills的最高价值是让你在较短时间内理解“什么样的技能设计才有效”。如果你能读懂仓库中几个高质量技能的内部结构就可以开始编写自己的私有技能。自研技能的常见切入点是把自己团队里反复使用的提示词模板、操作手册、代码规范整理成标准化的SKILL.md。这比从零写一套复杂应用更节省成本也能让团队整体收益。6. 常见问题与排查思路问题现象常见原因解决思路技能完全不生效技能目录不在 Claude 扫描范围内或SKILL.md命名/结构错误检查目录是否为~/.claude/skills或.claude/skills确认文件名必须是SKILL.md技能偶尔触发有时不触发description触发条件不清晰或描述过于笼统重写 description加入更具体的行为动词和任务关键词显式技能名无效技能名称大小写不匹配或当前会话未重启重启 Claude Code或确认客户端已重新加载技能技能中的脚本无法执行脚本缺少执行权限或运行时未安装执行chmod x确认脚本依赖的 Python/Node 等环境存在技能输出宁可绕一大圈也不执行正文没有给出明确的第一步模型在自由发挥在正文步骤中写清“第一步做什么、第二步做什么”减少自由度技能和 MCP 工具行为重复对某个外部系统既配了 MCP又装了技能明确分工MCP 负责连接技能负责规范和方法必要时只保留一个入口安装很多技能后响应变慢description 太多每次对话都要扫描判断精简技能数量删除不常用的技能或把 description 改写得更短技能内容泄露在回答中正文包含敏感示例或内部路径技能内不要写入真实密钥路径使用通用占位符如PROJECT_ROOT除了这些具体问题再补充一个通用排查顺序确认技能目录路径正确。确认SKILL.md文件名拼写准确。确认 Frontmatter 格式没有语法错误。在会话中显式输入技能名测试。如果还不行用官方最小示例替换你的文件排除内容问题。7. 最佳实践与工程建议7.1 从少数技能开始逐步扩展并不建议一次性把仓库中所有技能都安装起来。技能越多每一轮对话中模型需要扫描的description就越多不仅浪费 token还容易误触发。建议最多在全局目录保留 5 到 10 个常用技能其余技能按项目需求挂载到项目级目录。7.2 用 Git 管理你的技能技能本身是文本文件天然适合纳入版本管理。建议为团队单独创建一个team-skills仓库把标准技能集中管理成员通过 Git 拉取更新。这样可以解决个人技能散落、团队无法共享的问题。一个简单结构如下team-skills/ ├── README.md ├── code-review/ ├── pr-description/ ├── release-notes/ └── meeting-minutes/成员拿到仓库后只需将需要的技能软链接或复制到自己的~/.claude/skills下。7.3 安全边界要划清Claude Skills 虽然本质上是文本和脚本但它允许模型在本地环境执行命令。因此安装第三方技能前必须逐行阅读SKILL.md和附带脚本。不要在技能脚本中写入任何长期有效的密钥。生产环境使用技能时使用最小权限账号运行 Claude Code。如果技能会执行网络请求确保请求目标是可信域名。敏感数据文件不要放在assets/中因为技能可能被分享或同步到其他设备。7.4 控制 token 成本技能被引入对话时其描述会占用上下文预算。因此description写得简短、精准是控制成本的关键。SKILL.md正文不应该在每轮对话中都完整加载应该等到技能被实际调用时才加载。如果你的技能正文特别长可以考虑把内容拆分成多个文件只在SKILL.md中保留索引和加载方法避免一次性消耗过多上下文。7.5 用示例和负数规则提升技能稳定性在编写技能正文时除了写“要做什么”还可以写“不要做什么”。负向规则能显著减少模型的自由发挥空间。例如不要生成超过 3 行的总结不要包含主观评价不要引用未在 diff 中出现的文件名。这些约束越明确技能输出越稳定。7.6 定期回看并更新技能技能不是写出来就一劳永逸的。团队成员在使用过程中会发现新的边界情况或更好的做法应该每隔一段时间把这些经验回写进SKILL.md。建议把技能更新纳入代码评审流程像维护普通代码一样维护技能。8. 总结与后续学习建议通过本文你应该已经掌握了几个关键点Claude Skills 不是简单的提示词模板而是包含SKILL.md、脚本和资源文件的标准化技能包。awesome-claude-skills仓库是发现社区技能和学习优秀设计的重要入口。技能的核心质量在于description的触发准确性和正文步骤的可执行性。实际落地时要从少量技能开始优先解决团队最高频的任务。下一步可以考虑打开awesome-claude-skills挑选 1 个技能阅读其完整源码理解作者的设计思路。把你团队最常用的操作手册改造成第一个自研技能。在项目级目录中测试技能再逐步推广到团队仓库。最后提醒一句技术生态更新很快Claude Skills 的目录约定、触发方式和客户端行为也可能随版本调整。遇到不生效的情况优先查阅官方最新文档再结合本文的排查思路定位问题。如果你把某个技能从想法落地成了可用工具后续迭代的方向也会越来越清晰。 Claude Skills实战：从SKILL.md到自定义技能包
很多开发者在第一次听到“Claude Skills”时第一反应是“这不就是提示词模板吗”。实际接触之后会发现它更像是把提示词、脚本、参考文档、执行工作流打包成一个可复用单元的结构化方案。ComposioHQ 维护的awesome-claude-skills仓库则是目前社区里整理 Claude Skills 资源比较集中的一份精选列表。本文将围绕这个仓库展开讲清楚 Claude Skills 的核心机制、目录结构、安装方式并给出一个可直接上手的本地技能编写示例最后补充常见报错和工程化建议。无论你是刚接触 Claude Claude 的新手还是已经在用 Claude Code 做自动化任务的进阶开发者这篇文章都值得收藏备用。1. 背景与核心概念Claude Skills 到底是什么1.1 从“复制粘贴提示词”到“可复用技能”在日常使用 Claude 的过程中很多开发者会遇到一个场景每天都要让模型执行同一类任务比如“总结代码变更”“生成 PR 描述”“检查 Markdown 文档格式”。过去最简单粗暴的做法是把一长段提示词复制进对话框或者保存在本地笔记里反复粘贴。这种做法有三个明显问题提示词不稳定每次粘贴时可能漏掉某一段或者不小心改错了措辞模型输出质量随之波动。上下文被浪费长提示词每次都进入上下文窗口消耗 token也压缩了真正重要的业务信息空间。知识无法沉淀某位同事总结出来的“最佳提示词”只在个人笔记里团队其他人完全不知道也没有版本管理。Claude SkillsAgent Skills就是为了解决这个问题出现的。它本质上是一个标准化的技能包一个文件夹里包含SKILL.md主文件用来告诉 Claude 这个技能是做什么的、应该按什么步骤执行同时可以附带脚本、模板、参考文档等资源文件。当技能被安装到指定目录后Claude 会在对话或任务执行过程中自动识别并调用它。调用时不需要把完整技能内容塞进每一轮对话只需要通过自然语言或技能名的方式触发模型会按需加载技能内容。1.2 Claude Skills 和 MCP、Function Calling 的区别刚接触这个概念时很容易把 Skills、MCPModel Context Protocol和 Function Calling 混为一谈。这里用一个表格梳理三者的边界概念核心作用典型场景和 Claude Skills 的关系Function Calling让模型输出结构化参数调用外部函数天气查询、数据库查询、订单创建偏底层能力Skills 可以调用函数完成动作MCP统一协议连接外部工具和数据源GitHub、Slack、数据库连接器打开外部系统通道Skills 可以封装 MCP 工具的使用流程Claude Skills打包提示词、脚本和参考材料把“做事的方法”标准化代码审查、文档生成、工作流自动化偏方法论和知识封装描述“怎么做”简单理解MCP 解决的是“模型能连上哪些外部系统”Skills 解决的是“模型应该如何高质量完成某类任务”。比如你已经有 GitHub MCP 工具模型可以读取仓库、创建 Issue但未必知道“一个好的 PR 描述应该包含哪些模块、按什么顺序写”。通过安装一个pr-description技能模型就知道了这套规范并在执行时自动套用。1.3 awesome-claude-skills 在生态中的位置ComposioHQ 本身是 AI Agent 集成平台主要做工具和 API 的连接层。awesome-claude-skills是其维护的一份 GitHub 精选列表聚集了社区里质量较高的 Claude Skills 资源。仓库名字沿用了 Awesome 系列的命名惯例特点是分类清晰、更新较快、社区贡献为主。对于普通开发者来说这份仓库最实用的价值不是“把里面所有技能都装上”而是提供一个发现技能的入口你可以快速知道社区里已有哪些技能方向、哪些作者在做贡献、当前主流技能长什么样然后挑选其中少量技能深入阅读源码甚至可以借鉴其结构编写属于自己的技能。2. 环境准备与部署位置2.1 版本与环境说明Claude Skills 能力与 Claude 客户端、Claude Code 的版本强相关。本文示例以 2025 年下半年公开的 Claude 能力为参考具体路径和行为请以你当前版本的实际表现为准。在动手之前建议先确认以下环境一个可正常使用的 Claude 账号订阅版或 API 可用。如果使用 Claude Code请确保 CLI 已安装并能正常登录。操作系统不限Linux、macOS、WindowsWSL 环境更推荐均可。如果技能涉及脚本执行还需要对应的运行时比如 Node.js、Python 或 Shell。不同客户端加载技能的方式不完全一样但常见的目录约定是用户级目录~/.claude/skills项目级目录项目根目录/.claude/skills项目级目录一般优先于用户级目录便于针对不同项目挂载不同技能。2.2 查看技能目录是否生效可以先创建目录并确认路径。在终端执行mkdir -p ~/.claude/skills ls -la ~/.claude/skills如果是在项目中使用则在项目根目录执行mkdir -p .claude/skills ls -la .claude/skills对于刚接触 Claude Code 的读者可以用下面命令查看版本claude --version如果命令提示找不到claude说明 Claude Code 未安装或未加入 PATH需要先完成 CLI 的安装和登录配置。2.3 安装社区技能的基本步骤以awesome-claude-skills仓库为例一般安装流程是克隆或下载仓库找到你需要的技能目录。将技能目录复制到~/.claude/skills或项目的.claude/skills下。重启 Claude Code 会话或重新打开 Claude 客户端。在对话中用自然语言描述任务观察技能是否触发。# 克隆仓库到本地用于查看和挑选技能 git clone https://github.com/ComposioHQ/awesome-claude-skills.git # 进入仓库目录 cd awesome-claude-skills # 查看仓库结构 ls -la需要注意不是仓库中所有内容都可以直接复制使用。每个技能文件夹内部必须包含合法的SKILL.md文件才会被 Claude 识别。后续章节会详细拆解这个文件的结构。3. 核心机制拆解一个 Skill 的结构与原理3.1 SKILL.md 文件结构一个标准的 Claude Skill 目录通常长这样your-skill-name/ ├── SKILL.md ├── assets/ │ ├── example-input.md │ └── template.md └── scripts/ └── generate_report.pySKILL.md是技能的核心入口一般由两部分组成YAML Frontmatter位于文件最上方用---包裹声明技能的元信息比如name和description。Markdown 正文在 Frontmatter 之后用自然语言描述技能的执行流程、注意事项、示例和判断条件。一个最简单的SKILL.md示例如下--- name: markdown-format-checker description: 检查 Markdown 文档的标题层级、代码块标注和列表格式并输出规范化建议。 --- # Markdown 格式检查 当用户要求检查 Markdown 格式或文档规范时请按以下步骤执行 1. 读取用户提供的 Markdown 文件内容。 2. 检查一级标题是否重复、H2/H3 层级是否跳跃。 3. 检查代码块是否标注语言类型。 4. 检查列表缩进是否一致。 5. 输出问题列表和修改建议。 如果文件较长先输出目录结构总览再逐段检查。3.2 Frontmatter 中的关键字段在SKILL.md中description字段非常关键。Claude 判断是否调用技能主要依赖的就是这段描述。它相当于技能的“广告词”决定了什么场景下能被命中。几个建议description要写清楚“什么时候用”而不是只写“这是什么”。尽量在描述中自然包含触发词比如“检查 Markdown”“梳理文档结构”“生成 PR 描述”。不要写得过长否则每次对话都会消耗额外 token。name字段要具备区分度因为你可能同时安装多个技能。如果描述写得太模糊比如“处理文档”可能会导致技能在无关场景下被错误触发如果写得太窄比如“检查 Etsy 商品描述是否超过 140 字”则可能在实际使用中很难命中。3.3 正文内容与 assets、scriptsSKILL.md正文的作用是告诉 Claude“具体怎么做”。你可以把正文理解为一套为模型准备的作业指导书。正文里可以包含清晰的步骤清单。输入、输出格式。边界条件和异常处理规则。对脚本的调用方式。参考示例。assets和scripts目录则用于存放辅助资源。assets/存放模板、示例文件、参考文档等。它们不会被执行只作为模型生成内容时的参考材料。scripts/存放可执行脚本。Claude 在需要时可能会调用这些脚本完成数据处理、文件生成等操作。比如你写了一个“日报生成”技能SKILL.md描述工作流assets/template.md提供日报模板scripts/aggregate_data.py负责从多个 CSV 汇总数据。这样技能就是一个完整的小工具而不是单纯一段提示词。3.4 技能如何被触发Claude Skills 的触发方式主要有两种自动触发用户输入与技能描述高度匹配模型自动加载技能内容。显式触发用户直接输入技能名强制指定使用某个技能。对于自动触发模型会先读取当前可用技能的name和description判断是否需要使用。因此描述写得越精准触发成功率越高。显式触发则适合“自己知道要用哪个技能、不希望模型自由发挥”的场景。比如你已经知道有个pr-helper技能可以直接在对话中指出。4. 完整实战编写并挂载一个本地 Claude Skill4.1 需求场景为了让读者更直观地理解我们编写一个本地技能git-pr-helper。这个技能的功能是分析当前 Git 仓库的改动内容生成一份结构化的 PR 描述并附带 reviewer 检查点。为什么选这个场景因为它在日常开发中高频出现而且涉及代码执行读取git diff、结构化输出PR 模板和检查清单能覆盖一个技能的大部分要素。4.2 创建目录和文件首先创建目录结构mkdir -p ~/.claude/skills/git-pr-helper mkdir -p ~/.claude/skills/git-pr-helper/scripts如果你的项目想单独使用也可以创建在项目目录mkdir -p .claude/skills/git-pr-helper mkdir -p .claude/skills/git-pr-helper/scripts4.3 编写 SKILL.md创建文件~/.claude/skills/git-pr-helper/SKILL.md内容如下--- name: git-pr-helper description: 分析 Git 仓库的代码变更生成 PR 描述和 reviewer 检查清单。当用户要求生成 PR 描述、总结 git diff、准备代码审查时使用。 --- # Git PR Helper 当用户请求生成 PR 描述或审查代码变更时按以下步骤执行。 ## 第一步获取变更概览 在项目根目录执行 bash git diff HEAD --stat如果仓库没有提交历史或者用户指定了分支则改用git diff main...HEAD --stat如果出现错误提示先检查当前是否处于未提交状态还是跨分支比较然后选择合适的 diff 命令。第二步查看具体变更执行git diff HEAD如果改动文件数量很大优先输出每个文件的摘要再按重要程度输出完整 diff。重点观察新增或删除的核心业务逻辑。配置文件和依赖变更。数据库脚本或迁移文件。明显的调试残留代码。第三步生成 PR 描述按照以下模板输出 PR 描述## 变更背景 用 2-3 句话描述为什么做这次变更 ## 主要改动 - 模块 A新增 xxx 功能 - 模块 B重构 xxx 逻辑 - 模块 C修复 xxx 问题 ## 影响范围 - 受影响接口 - 受影响数据表 - 是否需要回归测试 ## Reviewer 检查点 - [ ] 是否有调试代码残留 - [ ] 是否包含敏感信息或硬编码密钥 - [ ] 是否存在明显的事务或并发问题 - [ ] 是否补充了必要的测试 - [ ] 依赖变更是否合理如果用户提供了团队 PR 模板优先使用用户模板替换上述结构。输出格式直接输出 Markdown 格式的 PR 描述不要额外解释执行过程。注意上面代码块中的多级 Markdown 在真实文件里要保持缩进正确。这里的重点是展示 SKILL.md 的写法而不是直接复制的最终文件。 ### 4.4 添加辅助脚本 为了让技能更完整我们再添加一个辅助脚本 scripts/changed_files.sh用于输出变更文件列表和对应行数 bash #!/usr/bin/env bash # 文件路径~/.claude/skills/git-pr-helper/scripts/changed_files.sh echo Changed Files git diff HEAD --stat echo echo Changed File List git diff HEAD --name-only执行前赋予执行权限chmod x ~/.claude/skills/git-pr-helper/scripts/changed_files.sh然后在SKILL.md的第一步中可以补充一句也可以直接运行bash ~/.claude/skills/git-pr-helper/scripts/changed_files.sh获取变更列表。这样做的好处是当 Claude 在某些环境中无法直接解析git diff --stat输出时可以通过脚本获得稳定格式的结果。4.5 在 Claude Code 中验证保存文件后进入任意一个 Git 项目目录启动 Claude Codeclaude在会话中输入帮我生成这个分支的 PR 描述观察 Claude 是否加载了git-pr-helper技能按步骤执行git diff并输出结构化 PR 描述。如果技能未触发可以尝试显式指定使用 git-pr-helper 生成 PR 描述如果依然没有生效请参考下一章排查方案。5. 精选仓库中的技能方向与选择思路5.1 社区技能常见类别浏览awesome-claude-skills时你会发现社区技能主要集中在以下方向方向典型能力适用对象代码工程生成 PR 描述、代码审查、提交信息规范化后端、前端、全栈开发者文档处理Markdown 格式化、技术文档翻译、需求文档拆分文档工程师、开发组长项目管理周报生成、会议纪要素材整理、Issue 分类研发管理岗位数据分析CSV 文件总结、SQL 优化建议、数据质量检查数据开发、运维、测试个人效率邮件摘要、日程规划、会议记录结构化所有办公场景这些分类并不严格很多技能同时覆盖多个方向。关键是从中挑选与自身工作流最贴近的 2 到 3 个进行深入研究。5.2 如何评估一个技能的质量从仓库中看到某个技能时不要急于安装。建议按以下标准评估Frontmatter 是否完整name和description是否存在描述是否清晰。正文是否有可执行步骤技能不能只说“做高质量总结”要给出具体步骤、命令或判断规则。是否有示例和边界说明好的技能会说明什么情况下不使用、输入缺失时如何处理。脚本是否可审计如果技能附带脚本应打开阅读一遍确认没有危险命令或可疑行为。维护活跃度优先选择近期仍在更新的技能而不是长期无人维护的冷门项目。5.3 从“使用技能”到“自研技能”awesome-claude-skills的最高价值是让你在较短时间内理解“什么样的技能设计才有效”。如果你能读懂仓库中几个高质量技能的内部结构就可以开始编写自己的私有技能。自研技能的常见切入点是把自己团队里反复使用的提示词模板、操作手册、代码规范整理成标准化的SKILL.md。这比从零写一套复杂应用更节省成本也能让团队整体收益。6. 常见问题与排查思路问题现象常见原因解决思路技能完全不生效技能目录不在 Claude 扫描范围内或SKILL.md命名/结构错误检查目录是否为~/.claude/skills或.claude/skills确认文件名必须是SKILL.md技能偶尔触发有时不触发description触发条件不清晰或描述过于笼统重写 description加入更具体的行为动词和任务关键词显式技能名无效技能名称大小写不匹配或当前会话未重启重启 Claude Code或确认客户端已重新加载技能技能中的脚本无法执行脚本缺少执行权限或运行时未安装执行chmod x确认脚本依赖的 Python/Node 等环境存在技能输出宁可绕一大圈也不执行正文没有给出明确的第一步模型在自由发挥在正文步骤中写清“第一步做什么、第二步做什么”减少自由度技能和 MCP 工具行为重复对某个外部系统既配了 MCP又装了技能明确分工MCP 负责连接技能负责规范和方法必要时只保留一个入口安装很多技能后响应变慢description 太多每次对话都要扫描判断精简技能数量删除不常用的技能或把 description 改写得更短技能内容泄露在回答中正文包含敏感示例或内部路径技能内不要写入真实密钥路径使用通用占位符如PROJECT_ROOT除了这些具体问题再补充一个通用排查顺序确认技能目录路径正确。确认SKILL.md文件名拼写准确。确认 Frontmatter 格式没有语法错误。在会话中显式输入技能名测试。如果还不行用官方最小示例替换你的文件排除内容问题。7. 最佳实践与工程建议7.1 从少数技能开始逐步扩展并不建议一次性把仓库中所有技能都安装起来。技能越多每一轮对话中模型需要扫描的description就越多不仅浪费 token还容易误触发。建议最多在全局目录保留 5 到 10 个常用技能其余技能按项目需求挂载到项目级目录。7.2 用 Git 管理你的技能技能本身是文本文件天然适合纳入版本管理。建议为团队单独创建一个team-skills仓库把标准技能集中管理成员通过 Git 拉取更新。这样可以解决个人技能散落、团队无法共享的问题。一个简单结构如下team-skills/ ├── README.md ├── code-review/ ├── pr-description/ ├── release-notes/ └── meeting-minutes/成员拿到仓库后只需将需要的技能软链接或复制到自己的~/.claude/skills下。7.3 安全边界要划清Claude Skills 虽然本质上是文本和脚本但它允许模型在本地环境执行命令。因此安装第三方技能前必须逐行阅读SKILL.md和附带脚本。不要在技能脚本中写入任何长期有效的密钥。生产环境使用技能时使用最小权限账号运行 Claude Code。如果技能会执行网络请求确保请求目标是可信域名。敏感数据文件不要放在assets/中因为技能可能被分享或同步到其他设备。7.4 控制 token 成本技能被引入对话时其描述会占用上下文预算。因此description写得简短、精准是控制成本的关键。SKILL.md正文不应该在每轮对话中都完整加载应该等到技能被实际调用时才加载。如果你的技能正文特别长可以考虑把内容拆分成多个文件只在SKILL.md中保留索引和加载方法避免一次性消耗过多上下文。7.5 用示例和负数规则提升技能稳定性在编写技能正文时除了写“要做什么”还可以写“不要做什么”。负向规则能显著减少模型的自由发挥空间。例如不要生成超过 3 行的总结不要包含主观评价不要引用未在 diff 中出现的文件名。这些约束越明确技能输出越稳定。7.6 定期回看并更新技能技能不是写出来就一劳永逸的。团队成员在使用过程中会发现新的边界情况或更好的做法应该每隔一段时间把这些经验回写进SKILL.md。建议把技能更新纳入代码评审流程像维护普通代码一样维护技能。8. 总结与后续学习建议通过本文你应该已经掌握了几个关键点Claude Skills 不是简单的提示词模板而是包含SKILL.md、脚本和资源文件的标准化技能包。awesome-claude-skills仓库是发现社区技能和学习优秀设计的重要入口。技能的核心质量在于description的触发准确性和正文步骤的可执行性。实际落地时要从少量技能开始优先解决团队最高频的任务。下一步可以考虑打开awesome-claude-skills挑选 1 个技能阅读其完整源码理解作者的设计思路。把你团队最常用的操作手册改造成第一个自研技能。在项目级目录中测试技能再逐步推广到团队仓库。最后提醒一句技术生态更新很快Claude Skills 的目录约定、触发方式和客户端行为也可能随版本调整。遇到不生效的情况优先查阅官方最新文档再结合本文的排查思路定位问题。如果你把某个技能从想法落地成了可用工具后续迭代的方向也会越来越清晰。