之前翻 GitHub 时看到 ComposioHQ 开了一个叫 awesome-claude-skills 的仓库把社区里零散的 Claude Skills 资源做了系统整理。说实话Claude Skills 这个概念刚出来的时候资料确实乱官方文档偏原理社区示例偏碎片真要照着搭一个能跑的技能包得自己拼半天。这篇文章就围绕 awesome-claude-skills 展开先讲清楚 Claude Skills 到底是什么、仓库里有什么再给一套从查找、安装到自写的完整实操流程最后补上常见的坑与工程建议。无论你是刚开始接触 Claude 生态的新手还是已经在做 Agent 应用的开发者都可以在本文里找到能直接落地的内容。1. 背景Claude Skills 是什么为什么值得关注1.1 从“提示词”到“技能包”的转变过去使用 Claude 这类大模型我们通常把指令全部写在 Prompt 里告诉它你是谁、你要做什么、输出格式是什么、有哪些注意事项。这种方式的缺点是所有逻辑都堆在一次对话上下文中系统提示词越长模型越容易在复杂任务中迷失重点而且换一个项目就要复制粘贴一大段 Prompt维护成本很高。Claude SkillsAgent Skills是 Anthropic 在 Claude Agent SDK 中引入的一种能力组织方式。它的核心思路是把“完成某类任务所需的知识、步骤、脚本和约束条件”打包成一个独立目录这个目录称为 Skill。每个 Skill 都包含一个 SKILL.md 描述文件以及若干辅助脚本、参考文档和资源文件。模型在对话过程中会根据用户请求自动判断是否调用某个 Skill然后读取它的说明并执行对应步骤。换句话说Prompt 是“一次性指令”而 Skill 是“可复用、可共享、可版本管理的能力单元”。这种转变对做 Agent 应用的开发者影响很大你不再需要在每次会话里复述大量操作步骤只需要告诉模型“去加载 XX 技能”它就知道该怎么做。1.2 Claude Skills 解决什么问题Claude Skills 主要解决三类问题。第一是可复用性。一个团队内部可以把数据清洗流程、日志分析流程、代码审查流程做成 Skill 文件提交到仓库里任何成员在自己的 Claude 环境中安装后就能直接使用。第二是可维护性。传统 Prompt 一旦写长调整一个细节就要改整段文字。Skill 把任务说明拆成多个资源文件比如 SKILL.md 只写“什么时候用、按什么步骤做”具体代码逻辑放在脚本文件里改动脚本并不影响模型的调用判断逻辑。第三是社区生态。Skills 天然适合以开源仓库的形式分发因为目录结构清晰、依赖声明简单、跨平台安装方便。基于这个特性社区很快就出现了大量按场景整理的 Skills 集合awesome-claude-skills 就是这个生态下的一个重要索引库。1.3 awesome-claude-skills 的定位awesome-claude-skills 由 ComposioHQ 发起。Composio 本身是做 AI Agent 工具接入的平台它为开发者提供统一的工具连接能力让 Agent 能调用 GitHub、Slack、数据库、浏览器等外部服务。ComposioHQ 在 GitHub 上维护 awesome-claude-skills相当于把 Agent 工具生态的经验延展到 Claude Skills 领域。这个仓库不是一套官方框架代码而是一份高质量的索引与示例集合。它的意义在于当你不知道该从哪里找现成 Skill、不知道该选哪类实现方式时先到这个仓库里筛选一遍能省掉大量重复造轮子的时间。由于仓库更新速度较快具体收录内容、分类方式都建议以仓库当前 README 和目录为准本文侧重讲解的是“如何使用这类仓库”的方法论。2. Claude Agent Skills 核心机制拆解2.1 Skills 在 Claude 应用中如何工作在 Claude Code、Claude Agent SDK 这类环境中Skills 的调用链路大致如下用户向 Claude 提出任务。Claude 分析任务目标判断是否匹配某个已安装 Skill 的描述。如果匹配模型读取该 Skill 的 SKILL.md。模型按照 SKILL.md 中描述的步骤执行必要时运行脚本文件、读取参考资料。执行结果返回给用户整个过程会在对话上下文中留下记录。这里最关键的判断依据是 SKILL.md 顶部的 description 字段。模型通过 description 来决定“这个任务是否需要触发技能”因此描述写得越清晰、越贴近实际使用场景技能被正确触发的概率越高。2.2 SKILL.md 的规范一个典型 Skill 目录结构大致如下my-skill/ ├── SKILL.md ├── scripts/ │ └── process.py ├── references/ │ └── guide.md └── assets/ └── template.txtSKILL.md 是入口文件一般包含 YAML 格式的 frontmatter 和 Markdown 正文。frontmatter 中最重要的字段是 name 和 description正文则写清楚“什么时候使用、执行步骤、参数说明、注意事项”。下面是一个简化示例--- name: markdown-link-checker description: 检查 Markdown 文档中的外链是否有效。当用户要求验证文档链接、清理失效链接、批量检查 Markdown 文件链接时使用。 --- # Markdown Link Checker ## 使用场景 - 用户提交一篇或多篇 Markdown 文档要求检查其中的外部链接。 - 用户要求报告失效链接清单。 ## 执行步骤 1. 接收待检查的文件路径列表。 2. 使用 scripts/check_links.py 提取文档中的所有外部链接。 3. 对每个链接发起 HTTP HEAD 请求记录状态码。 4. 输出检查报告按“正常链接 / 失效链接 / 无法判断”分组。 ## 注意事项 - 对疑似失效的链接建议用 GET 请求二次确认避免误判。 - 大批量检查时请控制并发数避免给对方服务器造成压力。这段描述不是给普通用户看的而是给 Claude 模型看的。所以写作时不能只写“本技能用于检查链接”而要写清楚“哪些请求会触发它、具体执行步骤、脚本怎么调用”。2.3 Skills 与传统 Prompt、MCP 的区别很多读者会混淆外部工具MCP和 Skills 的概念这里做一个表格区分。对比维度传统 PromptMCP 工具Claude Skills本质一次性指令文本外部工具调用协议能力单元由描述脚本资源组成是否携带代码一般不携带工具本身有服务端实现可以包含脚本文件复用方式复制粘贴文本注册工具服务目录级分发可放入版本库触发方式每次手动写入模型按需调用工具模型根据 description 自动匹配典型场景固定格式输出查询数据库、调 API复杂的多步骤工作流简单理解MCP 解决“模型如何安全地调用外部工具”Claude Skills 解决“模型如何按照固定流程处理一类任务”。两者可以配合使用Skill 的辅助脚本里完全可以封装对 MCP 工具的调用。3. ComposioHQ / awesome-claude-skills 仓库解读3.1 仓库概况awesome-claude-skills 本质是一个极客风格的 Awesome 清单仓库通过 README 和目录组织大量 Claude Skills 资源。与多数 awesome 系列仓库一样它的核心价值在于“聚合”和“筛选”。从仓库维护方 ComposioHQ 的角度看这个项目还有一个隐性目标吸引更多开发者关注 Agent 工具生态推动 Claude Skills 的标准化和工具化。因此仓库内除了有社区贡献的技能列表通常也会包含开发者贡献指南、分类索引以及部分使用说明。3.2 内容分类与阅读方法由于仓库内容持续更新这里不给出一份会过时的清单而是提供一个阅读方法。打开仓库后建议按以下顺序浏览先读 README 顶部的简介了解仓库定位和维护方式。查看分类目录通常包含开发效率、数据处理、自动化测试、内容生成、系统运维等方向。按场景筛选先确定自己的业务场景再找对应分类下的 Skill。进入某个 Skill 的仓库查看它的 SKILL.md 是否清晰、最近提交时间、Issue 活跃度。需要注意的是并不是所有收录 Skill 的质量都一样。部分项目只是概念演示部分项目已经可以用于生产环境挑选时要有自己的判断标准。3.3 适合哪些读者这个仓库适合三类读者刚接触 Claude Skills想找一个能跑通的示例进行学习。已经在开发 Agent 应用希望把常用操作沉淀为标准技能包的开发者。想了解社区技术趋势观察哪些 Skill 方向热度较高的研究者。对第一类读者建议先别急着读源码而是照着官方文档或仓库示例手动安装一个 Skill跑通后再回来看目录结构会更容易理解。4. 环境准备与版本说明4.1 运行环境要安装和使用 Claude Skills最常用的运行环境是 Claude Code它支持在命令行中与 Claude 交互并读取本地 Skills 目录。此外Claude Agent SDK 也支持 Skills但本文的操作演示以 Claude Code 场景为主因为它的安装和使用门槛更低。版本方面Claude Skills 机制在 2025 年逐步完善不同版本的 Claude Code 对 Skills 的支持程度有差异。本文的目录约定与安装路径以常见版本为准如果你的环境中没有生效第一件事就是确认 Claude Code 或 Agent SDK 的版本再查阅对应版本文档。4.2 确认 Claude Code 可用在安装任何 Skill 之前先确认 Claude Code 已经能在本机正常启动claude --version如果命令不存在说明 Claude Code 尚未安装或没有正确加入 PATH。这里不展开安装过程因为不同系统的安装方式差别较大建议直接查阅 Claude Code 官方安装指南。重点提示一切涉及模型 API、认证凭证的操作都应使用自己账号下合法申请的密钥并且不要把密钥提交到公共仓库。4.3 Skills 目录结构约定Claude Code 默认在以下位置查找 Skills~/.claude/skills/也可以为特定项目配置项目级 Skills 目录常见结构如下project-root/ └── .claude/ └── skills/ ├── skill-a/ │ ├── SKILL.md │ └── scripts/ └── skill-b/ └── SKILL.md个人级目录对所有项目生效项目级目录只对当前项目生效。实际使用时推荐遵循“通用技能放用户级项目专属技能放项目级”的隔离原则。5. 完整实战安装并使用一个社区 Skill5.1 查找并筛选 Skill直接从 awesome-claude-skills 仓库的 README 或分类目录里找一个你感兴趣的 Skill。假设当前业务经常需要处理 PDF 文档需要提取文本、抽取关键表格那就找一个“PDF 文档处理类”的 Skill。筛选时留意三点SKILL.md 里的 description 是否与你的任务场景契合。仓库是否还处于活跃维护状态最近是否有提交。依赖是否复杂如果依赖大量私有 API 或需要额外服务接入成本会明显增加。5.2 克隆 Skill 到本地找到目标 Skill 后先用 git 把对应仓库克隆到临时目录。例如git clone https://github.com/your-target-user/your-target-skill.git cd your-target-skill克隆后先查看目录结构确认里面确实包含 SKILL.md而不是一个普通项目。如果目录中只有一堆脚本但缺少 SKILL.md这个项目就不符合 Claude Skills 规范需要谨慎选择。5.3 将 Skill 安装到 Claude 目录将整个 Skill 目录复制到 Claude 的 Skills 目录中。以用户级安装为例mkdir -p ~/.claude/skills cp -r your-target-skill ~/.claude/skills/复制完成后检查目录ls -la ~/.claude/skills/正常情况下你会看到类似下面的结构~/.claude/skills/ └── your-target-skill/ ├── SKILL.md └── scripts/这里有一个关键约束SKILL.md 必须直接放在技能目录的顶层不能嵌套到下一级子目录中。如果目标仓库把 SKILL.md 放在了子目录里可以手动调整目录层级。5.4 在 Claude Code 中触发 Skill安装完成后打开 Claude Code直接描述你的任务。比如刚刚安装了 PDF 处理类 Skill你可以输入类似这样的请求请处理当前目录下的 report.pdf提取其中的主要结论并输出为 markdown 格式。这里不建议手动打出技能名称去强制触发因为 Claude Skills 的设计初衷就是让模型根据任务描述自动匹配。如果模型判断任务符合该 Skill 的使用场景它会在回答中引用 SKILL.md 并执行对应流程。如果你希望快速确认技能是否已被识别可以查看 Claude Code 启动时的加载日志或者通过对话让 Claude 列出它掌握的部分技能能力请告诉我你的工作环境中安装了哪些技能以及它们分别适合做哪些事情。5.5 验证结果无论是让 Claude 复述技能内容还是直接执行一个测试任务最终都要落到结果验证上。以“Markdown 链接检查”类的技能为例你可以准备一个包含正常链接、失效链接、空链接的测试文档执行后检查模型是否输出了分类报告以及失效链接是否被准确标记。如果模型完全没有调用技能而是用自己的通用知识回答大概率是 description 与任务表述不匹配或者 Skills 目录没有被正确加载。此时回到第 4 节的目录约定重新检查。6. 从零手写一个 Skill理解内部原理阅读现成样例只是第一步自己动手写一个 Skill 能帮你真正理解 SDK 的加载机制。这里我们实现一个最简单的“链接提取”技能用来从网页 HTML 中提取所有外部链接并去重。6.1 创建目录结构在项目级 .claude/skills 下创建项目mkdir -p .claude/skills/link-extractor/scripts目录结构如下.claude/skills/link-extractor/ ├── SKILL.md └── scripts/ └── extract_links.py6.2 编写 SKILL.md--- name: link-extractor description: 从 HTML 文件中提取全部外链并去重排序。当用户要求分析网页链接、提取 href、检查页面外链时使用。 --- # Link Extractor ## 使用场景 - 用户提供一个本地 HTML 文件希望提取其中所有 a 标签的 href 值。 - 用户希望对外链做去重并排序便于后续检查。 ## 执行步骤 1. 获取用户提供的 HTML 文件路径。 2. 使用 scripts/extract_links.py 处理文件。 3. 脚本输出按字母排序、去重后的链接列表。 4. 向用户展示结果并说明提取到多少个唯一链接。 ## 注意事项 - 只支持本地文件路径不接受 URL 参数避免模型擅自请求外部网页。 - 脚本只做静态提取不执行 JavaScript动态渲染页面不在支持范围内。 - 如果文件不存在或编码错误直接报告错误信息。6.3 编写辅助脚本#!/usr/bin/env python3 Extract unique links from a local HTML file. import argparse import re import sys from urllib.parse import urljoin def extract_links(file_path: str) - list[str]: try: with open(file_path, r, encodingutf-8, errorsreplace) as fp: content fp.read() except FileNotFoundError: print(fERROR: file not found: {file_path}, filesys.stderr) sys.exit(1) hrefs re.findall(rhref[\]([^\])[\], content, flagsre.IGNORECASE) cleaned set() for href in hrefs: stripped href.strip() if not stripped or stripped.startswith(#): continue if stripped.startswith(http://) or stripped.startswith(https://): cleaned.add(stripped) return sorted(cleaned) def main() - None: parser argparse.ArgumentParser(descriptionExtract unique external links from HTML.) parser.add_argument(file, helppath to local HTML file) args parser.parse_args() links extract_links(args.file) print(fTOTAL_UNIQUE_LINKS: {len(links)}) for link in links: print(link) if __name__ __main__: main()这个脚本虽然简单但已经包含了一个 Skill 辅助脚本应有的基本要素入口文件、参数解析、错误处理、结构化输出。模型在读取 SKILL.md 后能够理解“我应该用这个脚本处理什么文件、输出什么格式”从而准确调用它。6.4 运行与验证先用一段简单的 HTML 测试脚本!DOCTYPE html html body a hrefhttps://example.com/page1Page 1/a a hrefhttps://example.com/page1Page 1 duplicate/a a href#section-topTop/a a href/internal/pathInternal/a /body /html执行命令python3 .claude/skills/link-extractor/scripts/extract_links.py test.html预期输出TOTAL_UNIQUE_LINKS: 1 https://example.com/page1这里去掉了内部链接和锚点链接只保留外部绝对链接符合 SKILL.md 中的约束说明。6.5 调用链路复盘当你向 Claude 提出“提取 index.html 中的外链”时实际链路是Claude 分析请求匹配到 link-extractor 的 description。模型打开 SKILL.md看到执行步骤和注意事项。模型构建命令行调用运行 Python 脚本。模型读取 stdout 输出并把它整理成自然语言回复。理解这条链路后你就能针对模型触发不准确、脚本报错、输出格式混乱等问题做精准优化。7. 常见问题与排查思路问题现象常见原因解决思路模型完全不调用 Skilldescription 与用户请求不匹配或技能目录未被加载检查 SKILL.md 的 description 是否覆盖了目标场景确认 SKILL.md 在正确目录层级Skill 被识别但执行时报错脚本依赖缺失、Python 版本不兼容在本地手动运行脚本先确认脚本本身没有问题再检查模型是否按正确参数调用技能无法跨项目使用安装到了项目级目录而不是用户级目录把通用技能复制到 ~/.claude/skills/ 下输出结果不稳定SKILL.md 中的步骤描述不够明确增加明确的输入输出格式说明比如“输出为 Markdown 表格”“按失效状态分组”安装后发现新技能没有立即生效技能目录是在当前会话启动后新增的重启 Claude Code或创建新会话后再尝试辅助脚本执行了错误参数SKILL.md 中参数说明不清晰在 SKILL.md 中给出脚本用法示例例如 python scripts/xxx.py input_path排查这类问题时最重要的手段是脱离模型单独运行脚本。如果脚本在纯命令行环境下能稳定输出再把问题定位到模型理解层面如果脚本本身在不同环境下输出不一致那就算模型完美调用结果也不可能可靠。8. 工程与实践建议8.1 写好 SKILL.md 比写代码更关键很多人容易把重心放在辅助脚本上其实对 Claude Skills 来说SKILL.md 才是模型理解任务的入口。好的 SKILL.md 应该有这几部分description 明确说明“什么时候触发、什么时候不触发”避免模型在无关任务中误用。执行步骤足够细让模型不需要自己“猜测”中间过程。注意事项包含边界哪些输入不支持、哪些操作不允许、哪些命令有副作用。给出一个或两个最小调用示例模型参照示例调用脚本的成功率会明显提升。8.2 控制技能的安全边界Skill 的本质是“让模型运行你写的代码”所以它的安全边界非常重要。编写技能时优先坚持最小权限原则脚本只允许处理用户明确指定的本地文件不主动访问网络、不读取系统敏感目录。涉及删除、覆盖、批量修改文件的操作必须在 SKILL.md 中明确要求模型先向用户确认。不要在 Skill 目录中硬编码任何 API 密钥、Token 或个人配置。如果技能需要调用外部 API优先让用户运行时传入密钥而不是预置在脚本里。从社区复制 Skill 时先阅读辅助脚本源码确认没有恶意逻辑后再安装。8.3 版本管理与迁移建议Skills 虽然是目录形式但它同样是代码应该纳入版本控制。推荐的做法是为每个重要 Skill 单独建仓库或者在 monorepo 中按目录维护。在 SKILL.md 中记录适用的 Claude Code 版本避免升级环境后行为变化。给脚本注明 Python 版本和依赖必要时提供 requirements.txt。当 Claude 官方调整 Skill 规范时优先关注 SKILL.md 字段和目录结构的变化及时迁移。8.4 避免常见的“伪 Skill”社区里有一部分项目只是给普通脚本套了一层 SKILL.md并不符合真实调用逻辑。识别方法很简单看 SKILL.md 的 description 是否聚焦在一个具体场景执行步骤是否可被模型理解辅助脚本是否能被模型直接运行。如果三者中有两项不满足它大概率是个“伪 Skill”日常使用价值有限。8.5 从 awesome-claude-skills 获取灵感的正确姿势不要只把 awesome-claude-skills 当成下载站也可以把它当成思路参考观察那些受欢迎的项目是怎么组织 SKILL.md、怎么设计脚本、怎么处理错误和边界的。你可以在这些项目中看到公共模式比如“先检查输入合法性、再执行主逻辑、最后输出结构化结果”然后把模式迁移到自己的业务场景。9. 总结与下一步这篇文章围绕 ComposioHQ 发起的 awesome-claude-skills 仓库讲清了 Claude Skills 的本质、仓库的定位、社区 Skill 的安装方法以及如何从零编写一个属于自己的 Skill。核心收获可以归纳为三点第一Skill 的核心是 SKILL.md模型通过它来判断和使用能力第二安装 Skill 的本质是往指定目录放一个结构化的目录并保证辅助脚本可独立运行第三从社区拿来的 Skill 必须做安全审查和边界验证不能直接盲目信任。下一步可以尝试三条学习路径一是把 awesome-claude-skills 中的两三个高质量项目完整阅读一遍记录它们如何描述触发条件和执行步骤二是选择一个自己日常重复度高的任务按本文第 6 节的方式从零写一个 Skill并持续迭代 SKILL.md 里的描述三是关注 Claude 官方对 Skill 机制的更新及时把新版规范落实到自己的技能包中。如果本文对你有帮助可以收藏备用后续在实际项目中遇到有意思的踩坑案例也欢迎回来继续交流。