Claude Skills指南：从提示词到可复用技能工程化实践

前段时间在 GitHub 上刷到一个叫awesome-claude-skills的项目，收藏夹里一下子多了二十多个仓库。这个项目看起来就是个“资源列表”，但它背后反映的事情很有意思：Claude 的能力已经从“聊天”进化到了“执行”，而claude-skills恰恰是这条路上最值得关注的一环。

如果你只是把 Claude 当成一个高级问答机器，那这篇文章可能帮助有限。但如果你想让 Claude 真正帮你干活——比如自动整理文档、处理代码仓库、按固定流程输出内容——那skills（技能）就是目前最实用的方式之一。这个仓库把社区里散落的各种技能定义、模板、示例和最佳实践收集到了一起，相当于一张现成的地图，照着走就能省掉大量踩坑时间。

这篇内容适合谁？我觉得有三类人一定会从中受益：想在 Claude Code 里做自动化工作流的人、想做 Agent 但苦于不知道怎么设计“可复用技能”的人，以及单纯想看看别人怎么定义一套高质量提示词的人。接下来我会从项目定位、技能机制、实际开发、模板拆解、问题排查几个维度展开，讲的都是可以直接上手的经验和思路。

1. 先聊聊这个项目的定位：awesome 系的“地图册”逻辑

1.1 它解决的第一个问题：从“知道 Claude 很聪明”到“真正用好它”

awesome 开头的仓库在开源社区里太经典了，它代表的不只是链接集合，更是一种知识沉淀方式。这类项目的价值，关键是看能不能帮后来者节省找信息的时间。

awesome-claude-skills面对的问题很直接：Claude 官方推出了 Agent Skills 概念，给了你一套让模型掌握“特定领域操作流程”的框架，但真正到实际开发时，大多数人依然不知道怎么下手。技能文件怎么写才规范？目录结构怎么组织？描述字段怎么措辞才能被模型精准触发？这些细节官方文档有，但散落在各处，特别是社区实践的经验更不好找。

这个仓库就是把分散的知识聚拢起来：有官方规范链接，有社区贡献的技能仓库，有各种模板和示例。它的意义不是告诉你“Claude 很厉害”，而是告诉你“别人已经用这套机制做到了什么程度”，然后你可以直接参考、修改、复用。

1.2 仓库里到底装了什么：链接、模板、文档、成套技能

我翻完这个仓库之后，发现它其实包含了几类不同层次的内容，每一类对应不同的使用需求。

第一类是官方资源入口，也就是 Anthropic 关于 Agent Skills 的文档、指南和示例代码。这类内容适合想从根上理解机制的人，开发者看完能搞清 SKILL.md 的结构、技能的加载方式、渐进式披露（Progressive Disclosure）这些核心设计，搞清楚为什么技能包能省 token、为什么文件不至于一上来全塞进上下文。

第二类是社区技能仓库链接，每个仓库都是一个完整的技能实现。比如有人写了 PDF 处理技能，有人写了代码审查技能，有人写了团队周报生成技能。这些直接就能 import 进去用，或者改造成自己想要的样子。

第三类是模板和教程，包括怎么写 SKILL.md 的前置条件、怎么定义输出格式、怎么把外部脚本接入技能体系。这部分内容对新手最友好，照着模板填内容，基本不会出错。

第四类是更进阶的工具链，有些仓库不只是技能定义，还配套了 CLI 工具、测试脚本、技能开发脚手架等，帮你在本地高效管理多个技能，甚至一键打包发布。

一句话总结：这个 repo 的价值不在“数量”，而在“分类清晰、体系完整”，它把 Claude Skills 从零散实践变成了一门半正式的工程方法，初学者可以当教程读，老手可以当索引查。

2. Claude Skills 的核心机制到底是怎么运作的

2.1 SKILL.md：每个技能的“说明书”

Claude Skills 的最小单位，就是包含一个 SKILL.md 文件的目录。这个文件用 Markdown 编写，开头是 YAML 格式的 frontmatter，之后是正文指令。看起来很简单，但所有精妙之处都藏在这种结构设计里。

我拿一个实际例子来说。假设你要让 Claude 学会整理会议纪要，SKILL.md 的 frontmatter 大概长这样：

--- name: meeting-notes description: 将原始会议记录整理为结构化要点并输出待办事项。 ---

后面的正文就是真正的“技能指令”：告诉 Claude 遇到什么样的输入时该采用什么处理步骤、要遵循什么格式、生产什么样的输出。这部分可以写得很细，包括每一步怎么处理、涉及哪些术语替换规则、最后输出的模板长什么样。

这里的关键在于，SKILL.md 不是一段普通的提示词，它是一套围绕特定任务组织的指令集合，目标是让模型按照一套可复现、可预测的流程去完成工作。就好比你教一个新入职的助理“处理报销单时要按这个流程、填这个表、注意这几个坑”，技能文件就是这个助理的操作手册。

描述字段尤其重要，它是模型判断“该不该启用这个技能”的依据。我自己的经验是：描述要写“在什么场景、解决什么问题”，而不是“这个技能能做什么”。比如“根据会议记录提取行动项并生成 Markdown 待办清单，适用于项目管理、团队协作场景”，比“一个会议纪要整理技能”更具体，触发命中率也高得多。

2.2 技能触发：显式与隐式两套逻辑

技能触发机制是很多人第一次上手时搞不清楚的地方，这里值得多花点篇幅说清楚。

显式触发，就是用户或程序直接指定使用某个技能。在 Claude Code 这类交互环境中，你可以通过斜杠命令或者对话中提起技能名称来激活它。这种方式最可靠，适合用户明确知道自己要做什么的场景。比如你输入“运行一下周报生成技能”，那模型就直接加载这个技能执行。

隐式触发，则是模型根据对话上下文和用户意图，自动判断该用哪个技能。这时候 SKILL.md 里的 description 就成了唯一的判断依据。模型会读取所有技能的描述，结合当前对话内容进行匹配，选出相关性最高的那个。也就是说，描述写得好不好直接决定了隐式触发的准确性。

还有一个特别有意思的设计是“渐进式披露”（Progressive Disclosure）。技能目录里的内容不是一次性全加载到上下文，而是只加载 SKILL.md 作为索引，等到真正决定使用该技能时，才进一步读取相关的脚本、模板、参考文档。这种机制让模型在平时保持轻量，只在需要时按需加载更多上下文，既省 token 又保证了响应质量。

这种设计与人类处理信息的方式很像：你不会一进门就把团队所有文档都背下来，而是遇到具体任务时才去翻阅对应资料。

2.3 技能与 MCP、Prompt 的边界

提到 Claude Skills，就绕不开另外两个经常一起出现的概念：MCP（Model Context Protocol）和 Prompt。很多人在早期容易把它们搞混，我就曾经把技能定义写成了一堆工具调用，后来才慢慢摸清边界。

MCP 解决的是“Claude 如何连接外部工具和数据源”的问题。它定义了一套协议，让模型可以调用外部服务、数据库、API、文件系统等。它更像是“手”，负责实际去执行操作、获取数据。比如发送 HTTP 请求、读写文件、查数据库，这些都是 MCP 干的事。

Skill 解决的是“Claude 如何按照流程完成一项业务任务”的问题。它更像“大脑中的流程手册”：什么时候该调用哪个工具、各步骤顺序是什么、结果要以什么格式输出。一个技能可以内部调用多个 MCP 工具，把整个流程编排起来。

至于 Prompt，则是更宽泛的概念。任何一次给模型的指令都是 prompt，而 Skill 本质上是一种结构化、可复用的高级 prompt。换句话说，Skill 是 prompt 的工程化、产品化形态，可以分发、版本化、共享。

三者的关系打个比方：Prompt 是“你跟实习生说的一句话”，Skill 是“给实习生的标准作业指导书”，MCP 是“实习生能接触到的工具库和系统”。一个完整的技能包，通常是把三者的优势结合在一起，这也是 awesome-claude-skills 很多仓库展示的标准形态。

3. 自己动手写一个可用的 Skill：从零到一

3.1 前期规划：选场景、画边界

动手写代码之前，最重要的事情其实是选场景和画边界。我见过很多写出来的技能不好用，根本原因不是文件格式有问题，而是场景没选对。

好的技能场景有几个特征：任务流程相对固定，输入输出边界清晰，判断规则比较客观。比如“文档格式转换”“数据清洗”“每日总结生成”这类任务，就很适合做成技能。反过来，如果任务需要大量开放式判断，比如“写一份有创意的营销方案”，就不太适合做成技能——这种需求更适合直接用对话完成。

画边界的意思是，你要明确这个技能“管什么、不管什么”。以“PDF 表格提取”技能为例，它的输入边界是“含清晰表格结构的 PDF 文件”，输出边界是“Markdown 格式的表格数据”。至于 PDF 里是扫描件还是文字版、表格嵌套复杂怎么办，这些要么在技能里做前置说明，要么直接明确“不支持”以降低模型误判概率。

我在实际规划时，会先把技能支持的场景和三到五个典型用例写下来，然后反向推导需要哪些指令、哪些资源、哪些触发条件。这一步虽然费时间，但做得好能让整个开发过程变得非常顺畅。

3.2 搭建目录结构和 SKILL.md 内容

确定好场景后，就可以开始搭目录结构了。标准的 Agent Skill 目录长这样：

my-skill/ ├── SKILL.md ├── scripts/ │ ├── convert.py │ └── template.md └── assets/ └── example.pdf

SKILL.md 是唯一必需的文件，scripts 和 assets 是可选但很有用的资源目录。Claude 只有在实际使用技能时才会按需加载这些文件，所以不用担心目录太大拖慢响应。

SKILL.md 的正文我建议至少包含这几个部分：技能目标、使用步骤、输入输出约定、边界与限制、示例。下面是一个简化但完整可用的 SKILL.md：

--- name: markdown-table-extractor description: 从 PDF 文件中提取表格并转换为 Markdown 格式。适用于财务报表、数据报告、研究论文等 PDF 文档的表格处理。 --- # Markdown 表格提取技能 ## 目标 将用户上传或指定的 PDF 文件中包含的表格内容，准确转换为 Markdown 语法格式的表格输出。 ## 使用步骤 1. 确认 PDF 文件路径或当前附件中的 PDF。 2. 检查 PDF 是否为文字版而非扫描图片版；若为扫描件，提示用户先进行 OCR 处理。 3. 使用 scripts/extract.py 脚本提取表格结构。 4. 按原始表格行列结构输出为 Markdown 表格，数值保留原始精度，不进行四舍五入。 ## 输出约定 - 所有表格输出使用标准 Markdown | 分隔符格式。 - 表头行加粗，使用 --- 分隔线。 - 若表格为空或无法识别，输出“未检测到有效表格结构”。 ## 边界与限制 - 仅支持文字版 PDF，不支持扫描版。 - 合并单元格无法完整保留，会在单元格中用“—”占位。 - 每个 PDF 只处理第一个命名空间下的表格。 ## 示例 输入：财务Q3报告.pdf 输出： | 项目 | 金额（万） | 同比 | |------|-----------|------| | 营收 | 3,205 | +8% |

写这类内容时，“使用步骤”要尽量精确且顺序化。模型是按逐步指令执行的，含糊的表述会导致输出质量参差不齐。我的经验是，把步骤拆到“一个动作一个句子”的程度最合适，兼顾可执行性和灵活性。

3.3 接入 Claude Code 与测试调试

技能写好后，接入 Claude Code 使用非常简单，它默认会从.claude/skills/目录下发现技能。你只需要把你的技能目录放进去，重启会话，模型就能识别。

# 在你的项目目录或全局目录下 mkdir -p .claude/skills cp -r ~/dev/my-skill .claude/skills/

然后对话测试，确认技能是否能被触发。如果不触发，优先检查 SKILL.md 里的 description 是否有明确的关键词，以及当前对话是否包含与该描述相关的信息。我测过一个“视频脚本生成”技能，描述里写了“小红书”、“抖音”、“口播稿”这些词，但只要对话里出现“帮我想个短视频选题”之类的话，它就经常触发失败，原因就是描述和实际请求的表达方式离得太远。

测试环节记得做“干跑模式”验证。所谓干跑，就是不给真实数据，用模拟数据走一遍整个流程，确认指令逻辑本身没有漏洞。很多技能翻车就翻在逻辑漏洞上：步骤顺序颠倒、边界条件没写、示例格式和输出约定不一致。干跑能把这些低级错误一次性暴露出来。

调试期还有一个技巧：在开发阶段给 SKILL.md 的 description 加一个超级明显的前缀，比如“ALWAYS USE WHEN user asks about markdown extraction”，让它更容易被触发，方便反复测试。等到稳定了，再改回正式描述。

另外，注意技能的幂等性。同一个输入执行两次，结果应该基本一致，这是技能可靠性的重要指标。我自己的经验是，在 SKILL.md 里把“输出顺序”“排序规则”“冲突处理方式”都写明确，能明显提高输出的稳定性。否则模型一旦发挥“创造力”，输出可能每次都不一样。

4. 从 awesome 列表里能抄到的几种高质量模板

4.1 文档处理类技能模板

awesome-claude-skills 里最多的一类，就是文档处理类技能。这类技能最容易落地见效，也很适合作为新手练手模板。

文档处理技能通常做这几件事：读取指定文件、提取结构化内容、按预设模板输出。比如有仓库实现了“会议纪要处理”技能，不仅能提取要点，还能自动把待办事项拆给对应负责人；有“合同风险扫描”技能，会逐条检查合同文本中的风险条款并生成摘要报告。

这类模板值得学习的点在于“输出约定的细粒度”。拿合同扫描来说，好的技能会明确列出风险等级的定义、每个风险点需要输出哪些字段、最终的汇总表长什么样。这些看起来琐碎，但恰恰是保证输出可用的关键。

我直接拿这类模板改最大，因为文档处理任务的输入输出边界比较清晰，不会出现太多意外情况。而且 Claude 对长文件的阅读理解能力足够强，技能只需专注定义处理规则，脚本层面的工作量会小很多。

4.2 代码仓库级技能模板

另一类很有价值的是面向代码仓库的技能模板。这类技能不止作用于单文件，而是能站在整个项目层面思考问题。

一个常见的例子是“代码迁移”技能：它会分析当前项目的框架版本、识别废弃 API、搜索所有受影响的文件、规划迁移步骤，最后生成逐文件的修改建议。这整个过程如果靠人工写 prompt 来驱动，不仅啰嗦，而且容易遗漏细节。但固化成技能之后，每次执行都会遵循同一套方法论，结果稳定得多。

代码仓库级技能的核心竞争力在“上下文利用策略”。一段优秀的技能指令，会明确告诉模型先看哪些文件、按什么顺序收集信息、如何判断改动的影响范围。比如“迁移前先扫描 package.json 和配置文件，再搜索已废弃的 API 调用”，这些流程逻辑直接决定了任务成败。

我建议从这类模板里重点学习两点：一是如何把大型任务分解成阶段，二是如何在技能内引用项目中的具体文件和目录。用绝对路径还是相对路径、是否要求先运行某个脚本获取环境信息，这些细节在写技能时都要想清楚。

4.3 个人工作流类技能

除了文档和代码，awesome 列表里也有不少适合个人使用的工作流型技能，比如“每日复盘”“知识卡片生成”“博客文章翻译润色”等。这类技能的特点是小而美，写起来不难，但很能提升日常效率。

个人工作流技能的设计重点在“贴近使用习惯”。以“每日复盘”为例，技能内部会定义好复盘模板：今天完成了什么、遇到了什么问题、明天最重要的三件事是什么。你需要把手写复盘时的思考路径，转成模型可执行的指令结构。

这类技能还有个大用途：形成个人知识管理的固定入口。我认识的一个博主把“网页内容摘要”技能挂在了自己的阅读流程里，每当遇到值得收藏的页面时，就调用技能生成结构化的阅读笔记，存进自己的知识库。这种工作流一旦跑通，会形成很强的习惯依赖。

从 awesome 列表里抄模板时，我建议不要只抄文件本身，而是观察它们的构建思路：为什么选这个词做触发词？为什么这个步骤放在前面？对不上的地方改成适合自己的场景，才是真正掌握技能编写的方法。

5. 常见问题与排查实录

5.1 技能不触发：先看描述，再看依赖

技能不触发是使用过程中最让人头疼的问题，我排查过的次数不下两位数。按照我的经验，可以先按下面的优先级顺序逐项排查：

• 检查技能目录是否放在了正确位置，比如 Claude Code 要放在.claude/skills/下。
• 确认 SKILL.md 的文件名大小写和格式正确。
• 检查 description 是否包含了用户请求中的关键词或语义匹配点。
• 看看技能依赖的外部脚本或文件路径是否存在、是否有执行权限。
• 排查技能内容是否意外违反了某种规则，比如系统提示里明确禁止了某种操作。

大部分不触发问题，最后都落在 description 不够“贴题”上。模型是靠语义匹配而不是关键词匹配来激活技能的，所以描述里不能只写“处理PDF”，而要写覆盖用户可能的使用场景描述，比如“将 PDF 中的财务表格转换为 Markdown，支持年报、季报等文件”。

这里还有一个值得注意的点：当项目里同时存在多个技能时，触发的准确性也会下降。技能之间描述过于相似，模型就不知道选哪个。这种情况我通常会在描述里适当增加限定条件，比如给两个 PDF 相关技能分别写“适用于财务报表”和“适用于论文文献”，拉开距离。

5.2 多个技能内容互相冲突：明确优先级

技能一多，冲突问题就来了。比如你有一个“文档格式化”技能，要求输出统一用 GitHub 风格 Markdown，同时又有另一个“周报生成”技能，要求输出特殊的分段格式。当两个技能同时被触发时，模型可能会困惑到底该遵循哪个。

解决冲突的办法主要有两种。一种是在 SKILL.md 里明确声明与其他技能的边界：在“边界与限制”一栏写上“本技能仅处理数据提取，不负责格式化输出”，把职责切割干净。另一种是在技能描述里加上“优先级”或“使用前提”的提示，让模型在冲突时知道如何取舍。

我在我的知识库里维护了一份“技能职责说明表”，把每个技能的擅长的场景和不碰的场景都列出来。技能数量超过 10 个之后，这份表格的价值会越来越大，也方便定期检查和淘汰低效技能。

还有一点，技能内部的指令如果与系统提示（system prompt）冲突，会消耗大量 token 且效果不稳定。所以技能设计时，我建议对某些规则先用“若无特别声明，遵循技能内约定”的措辞，给模型一个明确的裁决依据。

5.3 环境与依赖问题：脚本跑不起来怎么办

很多技能都会附带脚本，比如提取 PDF、调用 API、批量处理文件等。这类技能最容易遇到的问题，就是“SKILL.md 写得很好，但实际运行时脚本报错”。

脚本报错有几类常见原因：依赖库没装、Python 版本不匹配、文件路径引用错误、权限不足。给技能配套脚本时，我会在 SKILL.md 里增加“依赖安装”和“环境要求”章节，写明需要哪些 Python 包、哪个版本、需要什么环境变量。虽然这会增加一点篇幅，但能避免用户拿到技能后一脸懵。

就我个人经验，技能脚本尽量用简单的标准库或最常用的第三方库，不要去依赖冷门工具。比如 PDF 提取，能用 pypdf 就用 pypdf；需要解析表格，pandas 的 read_pdf 或者 pdfplumber 都是稳定选择。越通用的依赖，跨环境复现的难度越低。

另外，脚本出错时的“输出方式”也要设计好。如果脚本失败，技能内部应该定义好异常处理路径：是输出错误信息让用户可视化排查，还是尝试用纯模型能力兜底。我最常用的策略是“脚本优先，模型兜底”，也就是脚本出问题时自动降级为模型直接处理，保证最终用户总有结果能用。

5.4 调试技巧：善用文档补全、单元测试、版本记录

调试技能这件事，本身也有不少经验可以分享。第一，Claude Code 等工具里，你可以直接在对话中打开 SKILL.md 文件，让模型解释它对这份技能的理解。如果解释得与你设计的意图不符，说明指令写得有歧义，需要改写。

第二，给技能做“最小验证”。每次迭代只改一个变量，看看输出变化是否合理。不要同时改描述和正文，否则出了问题根本定位不到原因。我吃过这个亏，一次改了触发词和输出模板，结果触发概率暴跌，花了好一阵子才排查清楚。

第三，建立技能版本记录。SKILL.md 的 frontmatter 之外，我习惯在技能目录里加一个 CHANGELOG，记录每次改动了什么、为什么改。尤其是当技能在团队内共享时，版本记录能避免“这个改了对不对”的争论。

6. 一点个人体会与扩展思路

玩了一段时间 Claude Skills 之后，我的最大感受是：它把“提示词工程”从一次性对话提升到了可维护、可分发的工程资产层面。过去写好一段 prompt，只能藏在收藏夹里，现在可以封装成一个技能文件跟着项目走、跟着团队走，甚至推到社区共享。这种转变的意义，不亚于从手写 SQL 到 ORM 的演进。

我自己现在的技能库大概有十几个，涵盖了文档处理、代码审查、日常写作辅助等几个主要方向。每个技能都为固定场景服务，迭代频率比之前写 prompt 低不少，稳定性却高得多。用 awesome-claude-skills 这类项目作为索引，定期翻一翻，能找到不少值得借鉴的结构设计。

如果你正好开始接触 claude-skills，我的建议很简单：别一上来就写复杂技能，先挑一个你日常重复率最高的任务，照着本文第三节的思路做一个最小可用版本，跑通了再逐步完善。技能的威力从来不在大而全，而在于精准锁定一个场景并把它做到极致。

最后再分享两个小技巧。第一，技能描述里加入“用户目标”角度的短语，比如“用户想要快速了解PDF内容时”，在实践中比“提取PDF内容”更容易触发。第二，测试技能时特意用“不那么标准”的输入来干跑一遍，看它能兜住多少意外情况，这比对着标准输入测试更能检验技能的真实可用性。

这个领域还在快速进化，新的最佳实践几乎每个月都在变。保持关注社区、拆解好仓库、坚持记录自己的技能迭代经验，你会慢慢发现，Claude 这类模型的能力其实远超直觉，关键就在于你愿不愿意花时间把“操作手册”写清楚。