企业官网建设流程全解析

很多开发者在第一次听到“Claude Skills”时，第一反应是“这不就是提示词模板吗”。实际接触之后会发现，它更像是把提示词、脚本、参考文档、执行工作流打包成一个可复用单元的结构化方案。ComposioHQ 维护的awesome-claude-skills仓库，则是目前社区里整理 Claude Skills 资源比较集中的一份精选列表。

本文将围绕这个仓库展开，讲清楚 Claude Skills 的核心机制、目录结构、安装方式，并给出一个可直接上手的本地技能编写示例，最后补充常见报错和工程化建议。无论你是刚接触 Claude Claude 的新手，还是已经在用 Claude Code 做自动化任务的进阶开发者，这篇文章都值得收藏备用。

1. 背景与核心概念：Claude Skills 到底是什么

1.1 从“复制粘贴提示词”到“可复用技能”

在日常使用 Claude 的过程中，很多开发者会遇到一个场景：每天都要让模型执行同一类任务，比如“总结代码变更”“生成 PR 描述”“检查 Markdown 文档格式”。过去最简单粗暴的做法，是把一长段提示词复制进对话框，或者保存在本地笔记里反复粘贴。

这种做法有三个明显问题：

• 提示词不稳定：每次粘贴时可能漏掉某一段，或者不小心改错了措辞，模型输出质量随之波动。
• 上下文被浪费：长提示词每次都进入上下文窗口，消耗 token，也压缩了真正重要的业务信息空间。
• 知识无法沉淀：某位同事总结出来的“最佳提示词”只在个人笔记里，团队其他人完全不知道，也没有版本管理。

Claude Skills（Agent Skills）就是为了解决这个问题出现的。它本质上是一个标准化的技能包：一个文件夹里包含SKILL.md主文件，用来告诉 Claude 这个技能是做什么的、应该按什么步骤执行；同时可以附带脚本、模板、参考文档等资源文件。

当技能被安装到指定目录后，Claude 会在对话或任务执行过程中自动识别并调用它。调用时，不需要把完整技能内容塞进每一轮对话，只需要通过自然语言或@技能名的方式触发，模型会按需加载技能内容。

1.2 Claude Skills 和 MCP、Function Calling 的区别

刚接触这个概念时，很容易把 Skills、MCP（Model Context Protocol）和 Function Calling 混为一谈。这里用一个表格梳理三者的边界：

简单理解：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、Windows（WSL 环境更推荐）均可。
• 如果技能涉及脚本执行，还需要对应的运行时，比如 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仓库为例，一般安装流程是：

1. 克隆或下载仓库，找到你需要的技能目录。
2. 将技能目录复制到~/.claude/skills或项目的.claude/skills下。
3. 重启 Claude Code 会话或重新打开 Claude 客户端。
4. 在对话中用自然语言描述任务，观察技能是否触发。

# 克隆仓库到本地，用于查看和挑选技能 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.py

SKILL.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、scripts

SKILL.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 Skill

4.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/scripts

4.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 Code：

claude

在会话中输入：

帮我生成这个分支的 PR 描述

观察 Claude 是否加载了git-pr-helper技能，按步骤执行git diff，并输出结构化 PR 描述。

如果技能未触发，可以尝试显式指定：

使用 @git-pr-helper 生成 PR 描述

如果依然没有生效，请参考下一章排查方案。

5. 精选仓库中的技能方向与选择思路

5.1 社区技能常见类别

浏览awesome-claude-skills时，你会发现社区技能主要集中在以下方向：

这些分类并不严格，很多技能同时覆盖多个方向。关键是从中挑选与自身工作流最贴近的 2 到 3 个进行深入研究。

5.2 如何评估一个技能的质量

从仓库中看到某个技能时，不要急于安装。建议按以下标准评估：

• Frontmatter 是否完整：name和description是否存在，描述是否清晰。
• 正文是否有可执行步骤：技能不能只说“做高质量总结”，要给出具体步骤、命令或判断规则。
• 是否有示例和边界说明：好的技能会说明什么情况下不使用、输入缺失时如何处理。
• 脚本是否可审计：如果技能附带脚本，应打开阅读一遍，确认没有危险命令或可疑行为。
• 维护活跃度：优先选择近期仍在更新的技能，而不是长期无人维护的冷门项目。

5.3 从“使用技能”到“自研技能”

awesome-claude-skills的最高价值，是让你在较短时间内理解“什么样的技能设计才有效”。如果你能读懂仓库中几个高质量技能的内部结构，就可以开始编写自己的私有技能。

自研技能的常见切入点是：把自己团队里反复使用的提示词模板、操作手册、代码规范，整理成标准化的SKILL.md。这比从零写一套复杂应用更节省成本，也能让团队整体收益。

6. 常见问题与排查思路

除了这些具体问题，再补充一个通用排查顺序：

1. 确认技能目录路径正确。
2. 确认SKILL.md文件名拼写准确。
3. 确认 Frontmatter 格式没有语法错误。
4. 在会话中显式输入@技能名测试。
5. 如果还不行，用官方最小示例替换你的文件，排除内容问题。

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 的目录约定、触发方式和客户端行为也可能随版本调整。遇到不生效的情况，优先查阅官方最新文档，再结合本文的排查思路定位问题。如果你把某个技能从想法落地成了可用工具，后续迭代的方向也会越来越清晰。