“skills”这个词最近在 AI 圈子里热度非常高。如果你关注 Claude、GPT、各类 agent 框架会发现它们都在反复提到同一个概念Skills。简单说这是把 AI 从一个“啥都会但啥都不精”的通用助手变成一个“真正懂你工作流”的专属搭档的一种配置方式。这篇文章我以目前讨论度最高、落地路径最清晰的 Claude Skills 为例从设计原理到实操细节完整讲清楚 Skills 到底怎么写、怎么调、怎么避免踩坑。无论你是做开发的、写文档的还是整天被周报和日常事务缠住的运营这套思路基本都能套用。我最早接触 Skills 时以为它不过是“高级版的 system prompt”后来自己动手写完第一个 skill 才发现差得远。它更像是在模型旁边放了一本“岗位说明书 工具包 作业模板”让模型在正确时机主动翻出来用。这篇我会把一个可落地复用的 skill 从零写完目录结构、核心文件、脚本、测试方法全部分享出来最后还会把我踩过的坑挨个复盘。1. Skills 是什么先搞清这个新概念在解决什么问题1.1 从“聊天助手”到“会干活的助手”过去我们用 AI 干活最常见的方式是把背景资料粘贴进对话框把要求一条条写清楚再补充一些格式说明最后生成内容。这个模式有三个让人很头疼的问题。第一重复劳动。你每周都要写周报于是每周都要重新把项目背景、格式要求、语气偏好讲一遍。哪怕你已经把这段提示词存成了文本每次调用还是得复制粘贴而且经常忘了某个细节。第二上下文有限。模型能记住的内容是有限的你把一整套公司规范、代码仓库结构说明、输出模板都塞进去真正留给任务处理的空间就少了效果自然会打折。第三换一个场景就“失忆”。上周刚教过它怎么整理 Git 提交记录今天换个项目目录它又像是第一次听说这个需求。Skills 就是冲着这三个问题来的。它不是一个“一次性提示词”而是一个可以被反复加载的“能力包”。一个 Skill 本质上就是一个文件夹里面有一个核心的 SKILL.md 文件用来描述这个技能是什么、什么时候用、具体怎么执行文件夹里还可以放辅助脚本、模板、参考资料等等。模型在对话过程中会根据语义自动判断当前场景是否匹配某个 Skill匹配了就主动加载对应文件夹里的全部内容像是一个经验丰富的员工在开工前打开了自己的工作手册。1.2 Skills 和 Prompt、插件、子代理有什么本质区别很多人一听就说“这不就是写个 Prompt 吗”我一开始也这么想但用完之后发现差距非常明显。写 Prompt 等于你每次都向模型口述一份临时工作指令内容质量完全取决于你当时的表达是否完整。而 Skills 是结构化的工作包指令、资源、模板、脚本都规范地放在固定位置模型不是“听你说”而是“自己去查自己应该怎么做”。这就像你给员工布置任务一种是每次临时口头说明一种是直接丢给他一份完整的 SOP 文档质量稳定性完全不一样。Skills 和插件Plugin / Tools的区别也很关键。插件通常是一个可执行的函数或外部 API比如搜索、访问数据库、调用计算引擎而 Skills 更像是“知识 过程 工作流”的载体。插件告诉模型“你能调用什么”Skills 则告诉模型“这个任务应该怎么做、按什么顺序、有哪些注意事项”。在某些场景下一个 Skill 内部可以调用多个插件它俩不是替代关系而是协作关系。再说子代理Subagent。子代理是独立运行的、有专门目标的小模型实例通常用于并行处理子任务而 Skill 更轻量它是加载到主对话中的指令和资源没有独立的执行循环。可以这么理解子代理是一个外包团队Skill 是一本团队看到就能照着干活的标准作业手册。1.3 哪些场景值得投入时间写一个 Skill写 Skill 需要成本所以并不是所有事情都适合。从我的经验看有三类场景性价比特别高。第一类是高频重复任务。典型的就是周报月报、代码审查、发布检查清单。这些任务流程固定、格式统一每次做都要重复解释一遍规则写成 Skill 后一发入魂。第二类是领域知识包。比如你要处理某种特殊的文件格式或者需要遵循公司内部的一套 CSS 命名规范或者是识别某种特定领域的专业术语。这些知识平时占上下文又没法每次都说清楚封装成 Skill 最合适。第三类是多步骤工作流。比如“从 Git 提交记录生成发布说明”“对一批图片做统一压缩和重命名”“把项目文档改写成面向用户的介绍文案”。这类任务链路长、步骤多写成 Skill 后模型就能稳定按照流程一步步走完不会中途漏掉某个环节。但如果只是一次性的、没有复用价值的任务那写个普通提示词就够了没必要上 Skills。合理判断很重要不然容易变成“为了写 Skill 而写 Skill”的形式主义。2. 动手前先拆解一个 Skill 的内部结构和运行机制2.1 SKILL.md 是入口frontmatter 与正文各管什么每一个 Skill 里最重要的文件就是固定命名、放在根目录下的 SKILL.md。这个文件由两部分组成开头的 YAML frontmatter 和正文的 Markdown 指令。frontmatter 里有两个字段是必须的name 和 description。name 是这个 Skill 的唯一标识命名规则一般要求使用小写字母、数字和连字符比如 weekly-report-generator不要有空格和特殊符号。description 是模型判断“什么场景下该用这个 Skill”的依据所以不能写得太含糊。标准写法应该包含触发条件、适用场景、任务类型这几个维度。我举个直白一点的例子“Generate weekly status reports from git commit history and project tasks”这句话就比“A tool for reports”好用得多。正文部分才是核心写的是这个 Skill 的执行指令。你需要告诉模型这个任务的背景知识、执行步骤、输出格式、注意事项、可能遇到的边界情况。有人说“正文越详细越好”这话只说对了一半。详细不代表啰嗦重点是结构清晰、指令明确、有可执行性。模型是按步骤执行的所以你最好把流程拆成明确的编号步骤而不是写一长段描述让它自己理解。下面是一个 SKILL.md 最小可用的例子--- name: weekly-report-generator description: Generate weekly status reports from git commit history and project tasks. Use when the user asks for a weekly report, work summary, or progress update. --- # Weekly Report Generator Generate a concise weekly status report based on the users current project context. ## Steps 1. Collect recent git commit history from the current project. 2. Group commits by relevant themes or modules. 3. Summarize each group into 2-3 bullet points, written in a professional but plain tone. 4. Include a Highlights section and a Next Week Plan section. 5. Output the report in Markdown format. ## Constraints - Always base the summary on real commit messages, do not invent changes. - If commit history is empty, state that clearly instead of generating fake content. - Keep the report under 300 words unless the user requests more detail.2.2 资源文件怎么放脚本、模板、参考文档的组织方式一个 Skill 的价值往往不只是指令本身还在于它携带的资源。SKILL.md 是入口但里面可以引用同目录下的其他文件推荐的目录结构通常是这样weekly-report-generator/ ├── SKILL.md ├── scripts/ │ └── collect_git_log.py ├── templates/ │ └── weekly_report_template.md └── references/ └── writing_style_guide.mdscripts 目录放可执行脚本比如用 Python 写的数据收集脚本、用 Shell 写的批处理脚本。模型执行时可以直接读取脚本内容来理解逻辑也可以根据你的指示让脚本生成中间结果。templates 目录放输出模板当你的任务有固定格式要求时模板可以显著降低模型自由发挥的空间。references 目录放背景资料、样例、规则说明这些内容不需要时刻出现在上下文中但模型可以在需要时读取。目录和文件名的规范程度很重要。如果命名乱七八糟模型加载时容易“迷路”。保持可读性强的文件结构本身就是给模型提供良好的工作环境。这里有一个实用小技巧在一个 Skill 内部引用资源文件时尽量使用相对路径并且要在 SKILL.md 里明确写出路径结构这样模型可以顺着路径找到资源。2.3 命名、描述和触发机制决定 Skill 会不会被“想起来”理解触发机制是写 Skill 的关键一步。模型不是每次都把所有 Skill 全部加载进上下文那样成本太高也不现实。更合理的方式是模型会根据对话内容做一个语义匹配判断“当前这个场景和我的技能库里的哪个描述更匹配”匹配度够高的时候才会加载对应 Skill。所以 description 写得不好直接后果就是 Skill “永远不会被想起来”。比如你的 description 只写“A tool for reports”那模型遇到“帮我写一下这个月的总结”时很可能就无法理解这个 Skill 和当前任务的关联。反过来如果你在 description 里明确写了触发条件和对应场景比如“Generate weekly status reports from git commit history and project tasks. Use when the user asks for a weekly report, work summary, or progress update”模型匹配的概率就会大幅提升。另外如果你在对话里能明确感知到某个 Skill 应该被使用通常也可以直接在指令里点名引用它。不同工具对这种手动引用的语法设计不太一样有的用 有的用特殊标记。我发现最可靠的方式是把 Skill 的 name 直接写进对话比如“用 weekly-report-generator 帮我生成这周的周报”模型通常就能正确加载。不过要说明的是不同客户端和框架的触发方式会有差异实际使用前最好查一下对应工具的文档。3. 实操演示从零写一个“周报生成”Skill3.1 准备项目目录和基础配置文件理论讲再多不如动手写一个。我以“周报生成器”为例完整演示一遍从零到一的过程。这个例子很典型流程固定、需要外部数据、模板要求明确几乎把 Skill 的核心要素都覆盖了。首先创建目录结构mkdir -p weekly-report-generator/{scripts,templates,references}然后进入目录创建 SKILL.md。这个文件是所有逻辑的核心我一定要把任务背景、执行步骤、输出约束写清楚。frontmatter 里的 description 要覆盖尽可能多的触发场景。下面是我实际使用的版本--- name: weekly-report-generator description: Generate weekly status reports from git commit history and project tasks. Use when the user asks for a weekly report, work summary, progress update, or weekly review. --- # Weekly Report Generator You are helping the user create a weekly status report for their current project. ## Workflow 1. Run the script scripts/collect_git_log.py to collect git commit history from the current repository. 2. Read the raw output and group commits into logical themes such as features, bug fixes, refactoring, documentation, and experiments. 3. For each theme, write 2-3 concise bullet points. Write in the users default working language unless specified otherwise. 4. Include a Highlights section that describes the most important achievement this week. 5. Include a Blockers section, noting any issue that prevented progress. 6. Include a Next Week Plan section with 3-5 planned tasks. 7. Render the final output using the template in templates/weekly_report_template.md. ## Constraints - Only use information present in the collected git log. Do not invent any work items. - If the commit history is empty, say so explicitly in the report and ask the user to provide manual input. - Keep the tone professional and concise. - Do not include internal links, screenshots, or emojis in the report.这里有一个很重要的设计思路我没有让模型“凭空生成”内容而是让它先通过脚本拿真实数据再根据真实数据做归纳总结。这样做出来的周报才是有依据的而不是模型自己编出来的“幻觉报告”。3.2 编写辅助脚本用真实数据喂给模型接下来是 scripts/collect_git_log.py。这个脚本负责从当前 Git 仓库里读取最近七天的提交记录作为生成周报的原始素材。代码不复杂但解决了一个实际问题模型并不能直接、高效地从庞大的 Git 历史里提取信息而脚本可以快速输出结构化结果。#!/usr/bin/env python3 import subprocess import sys from datetime import datetime, timedelta def get_git_log(since: str, days: int 7) - str: since_date (datetime.now() - timedelta(daysdays)).strftime(%Y-%m-%d) cmd [ git, log, --since, since_date, --prettyformat:%h|%an|%ad|%s, --dateformat:%Y-%m-%d %H:%M, ] try: result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) return result.stdout except subprocess.CalledProcessError as e: return fERROR: {e.stderr} def main(): days 7 if len(sys.argv) 1: days int(sys.argv[1]) data get_git_log(, days) if not data.strip(): print(NO_COMMITS) return lines data.strip().splitlines() for line in lines: commit_hash, author, date, subject line.split(|, 3) print(f- {date} | {author} | {subject} ({commit_hash})) if __name__ __main__: main()这里的核心价值是让模型拿到“干净的、按时间排列、包含作者和提交说明”的数据。模型不需要自己去翻 Git 历史也不需要担心自己无法执行命令行操作。脚本把“数据获取”和“内容生成”两个阶段解耦开各司其职这在实际使用中效率高很多。然后创建 templates/weekly_report_template.md用来约束最终输出的版式## Weekly Report (Week of {{ start_date }}) ### Highlights - ### Changes by Theme #### Features - #### Bug Fixes - #### Refactoring Maintenance - #### Documentation - ### Blockers - ### Next Week Plan -模板的意义在于基本确定输出骨架让模型在框架内填充内容。很多人觉得“模板会限制模型发挥”但实际经验是对于重复性任务给模型清晰的模板反而能提升输出质量和一致性。尤其是周报这种内容格式有明确预期的场景模板价值非常高。3.3 编写参考文档让模型了解你的写作偏好references 目录里我放了一份 writing_style_guide.md用来描述周报的语气和用词偏好。这听起来有点多余但实际操作时效果非常明显。# Writing Style Guide - Use professional but plain language. Avoid buzzwords such as synergy, drill down, circle back. - Prefer action verbs: implemented, fixed, refactored, investigated, documented, tested. - When describing impact, be specific. Instead of improved performance, write reduced page load time by 40%. - Keep each bullet point between 12 and 25 words. - Use past tense for completed work. - Write in the users default working language unless specified otherwise.当你把这类“软性要求”放进 references而不是直接塞进 SKILL.md 正文时好处是SKILL.md 保持简洁核心步骤不会被淹没模型的注意力更容易集中在核心指令上。而当真正需要调整风格时直接改 references 里的文件就行不用动主流程。3.4 加载与测试观察模型是怎么把 Skill 用起来的写完文件后需要实际测试。不同工具的测试流程会有些差异以 Claude Code 为例把 weekly-report-generator 目录放到项目的 .claude/skills/ 目录下或者放到用户的全局 skills 目录下然后在对话里输入帮我生成这周的周报这时候模型会做的事情大概分几步第一步判断这个请求符合 weekly-report-generator 的描述第二步读取 SKILL.md第三步按照 SKILL.md 里的指令先运行 collect_git_log.py 脚本第四步读取模板和写作指南最后生成并输出周报。我第一次测试时故意不点名 Skill只说了“写个周报”模型照样正确调用了它。这种“不主动点名、模型自觉调用”的体验非常关键说明我的 description 写得够清晰。如果模型没有正确触发优先排查 description这是最常见的失败原因之一。4. 写 Skill 时的常见坑与排查技巧实录4.1 Skill 不生效先检查这几个位置Skill 不生效是遇到最多的问题。常见的表现有模型完全没有反应好像 Skill 不存在或者模型加载了但执行到一半跑偏了又或者模型执行完之后输出的内容不符合预期。第一步先检查目录位置是否放对了。不同工具对 Skill 的扫描路径有严格约定项目级通常放在 .claude/skills/ 或类似目录下全局级放在用户目录下。放错位置等于白写。我自己就踩过这种坑把目录放到了项目根目录下结果模型一直没反应后来才发现少了一层父目录。第二步检查 name 是否合法。如果 name 里用了空格、大写字母或者特殊字符很多工具会直接忽略掉这个 Skill。写完后建议先用工具自带的 skills 列表命令确认能被正常识别。第三步检查 SKILL.md 的文件名大小写。SKILL.md 必须是这个大小写和这个后缀名不能写成 skill.md 或 SKILL.MD。Linux 环境下尤其容易忽略这个问题。第四步检查 frontmatter 格式。YAML frontmatter 必须放在文件最顶部并且用---包裹。如果格式非法解析器可能会跳过整个文件而且不会报错。4.2 description 写不好等于没写description 这个字段容易被低估却是决定触发质量的关键。我见过很多新手写 description 只有一个词比如“周报”或者类似“Generate weekly report”这种只描述输出、不描述触发场景的写法。这样写的问题在于用户的实际表达可能千变万化“帮我总结一下这个星期干了啥”“写个本周总结”“整理下这周进展”这些表达都符合周报需求但模型的语义匹配未必能全部关联到那个只有一个词的 description 上。我的建议是description 至少包含三类信息一是任务动作比如 generate、summarize、analyze二是目标对象比如 git commit history、project tasks、customer feedback三是典型触发表达比如 use when the user asks for a weekly report or progress summary。这样写之后匹配准确率会高很多。还有一个值得注意的点如果你有多个功能相近的 Skill模型可能会选错。比如同时有一个“周报生成器”和一个“项目总结器”两者的描述如果过于接近模型就难以区分。这时候要么功能合并要么在 description 里明确差异化边界。4.3 指令与模板的平衡怎么防止模型“自由发挥”模型在生成内容时天然倾向于“自由发挥”这既是它的优点也是它的缺点。在写 Skill 时如果指令不够明确模型可能会在步骤之间来回跳或者自行添加你觉得不合适的段落结构。最好的解决方式是把自由度留给“内容创作”的部分把约束写在“流程”和“格式”的部分。这是我自己实践下来比较好用的几条原则执行流程写成 numbered steps不要写成一段散文。模型对编号步骤的理解和遵循程度明显更高。对输出格式做明确的标记比如“使用 templates 目录下的模板”“不要包含 emoji”“控制在 300 字以内”。这些都能显著减少返工。明确说明“不要做什么”有时候负面清单比正面要求更有效。比如“不要编造不在 git 记录里的内容”“不要使用夸张营销语气”。不同步骤之间的依赖关系要写清。如果步骤二依赖步骤一的输出要明确说“基于步骤一的结果”。有一点想特别提醒指令过于冗长也会降低遵守度。SKILL.md 不是越厚越好它应该像一个高效的操作手册把必要的信息讲清楚就够了。如果你想给模型补充更多背景知识放在 references 目录里而不是堆在正文中。太长的主流程会让模型抓不住重点反而降低执行质量。4.4 一个常用问题速查表我把实际使用中高频出现的问题和对应的处理思路整理成一张表方便你排查问题现象常见原因排查思路模型完全没反应像没看到 Skill目录位置不对、SKILL.md 大小写错误、frontmatter 非法确认目录路径、文件名、frontmatter 格式模型对不上正确的 Skill选错了description 覆盖不全或与其他 Skill 描述重叠重写 description明确触发场景和名称边界Skill 加载了但模型不按步骤走步骤写成了长段落没有使用编号列表把流程改为编号步骤增强指令的明确性输出格式和预期不一致缺少模板或负面约束不够添加模板文件明确输出格式和禁止事项模型总是编造数据没有提供数据获取的脚本和渠道增加辅助脚本让模型基于真实数据生成内容修改了 Skill 但模型仍用旧逻辑缓存或会话未刷新重启会话或者确保改动保存后重新加载多个 Skill 功能重叠互相干扰Skill 边界不清晰合并功能或细分 description 的使用场景排查的时候有个心态很重要不要假设“是模型的问题”。绝大多数情况下Skill 不生效或者效果差问题都出在描述覆盖不足、目录结构不规范、指令不够清晰这些我们自己能控制的点。先按表格里的思路逐项检查通常都能解决。4.5 一些亲身踩过的坑和调整细节补充几个我实践中反复踩过、最终总结出来的细节经验。第一个是关于脚本的健壮性。我最初写 collect_git_log.py 时没有处理“仓库里没有任何提交记录”的情况结果模型运行脚本得到空输出后竟然真的顺着模板生成了一份全是空内容的周报。后来我在脚本里专门加了 NO_COMMITS 分支并在 SKILL.md 的约束里写清楚“如果 commit history 为空必须明确说明并要求用户提供手工补充”。这种边界情况如果不提前想到模型的处理方式会非常不可预测。第二个是关于语言风格。团队里不同人写的周报风格完全不同有的人习惯列表式有的人习惯段落式。如果你想让 Skill 产出适合自己习惯的内容最好的方式不是改来改去而是把你过去几周满意的周报整理成样例放到 references 目录里。模型能参考样例进行风格对齐这比任何描述都管用。第三个是版本控制。Skill 本身就是配置文件和代码完全可以用 Git 来管理。我自己维护了一个 skills 仓库所有 Skill 都按目录归好每次调整后提交一次要回滚随时可以。时间长了你会发现这就像一个随时可以恢复的“配置备份”比散落在各个聊天记录里的提示词可靠多了。第四个是“从轻开始”的原则。第一次写 Skill 时不要一开始就设计一个大而全的方案。先写一个只覆盖单一场景、只解决一个问题的简单版本跑通了再逐步增加资源和分支逻辑。大而全的 Skill 往往难调试也容易导致模型在步骤之间迷失方向。5. 写 Skill 的进阶建议和工具推荐如果你已经能写出一个正常工作的 Skill下一步要考虑的是如何让这套体系发挥更大的作用。这里分享一些我目前还在用、收益非常明显的做法。一是把内部规范类知识做成 Skill。很多团队有大量的“隐性知识”比如代码提交的格式要求、接口文档的字段命名规则、版本的发布流程。这些内容过去要么写在某个无人阅读的文档里要么在群里反复被追问。整理成 Skill 后团队成员只需要在对话里描述需求模型就自动带上规范执行效率提升非常明显。二是为 Skill 建立“组合使用”的习惯。单独一个 Skill 解决的是单一问题但实际的复杂工作往往需要多步协作。比如我做一个“新项目启动”的 Skill内部自动调用“项目初始化脚本”“依赖库版本检查说明”“代码规范参考”三个配套资源一次性把开发环境、目录结构、规范约束全部准备出来。模型会把它们当成一套操作流程来执行。三是关注社区的现成 Skill。现在各类 AI 工具生态里已经有大量公开的 Skills 仓库覆盖代码审查、文档生成、数据分析、文案撰写等方向。看到符合自己场景的可以直接拿来用再根据自己的实际流程做修改。不用什么都从零写这也是这套机制最有价值的地方。工具选择上我目前主力用 Claude Code 来管理 Skills因为它对 Skill 目录结构的支持比较成熟卸载加载也很灵活。其他支持类似能力的工具还有不少但原理都是通用的只要你理解了 SKILL.md 的结构、资源目录的组织、description 的触发机制换一个工具也只需要调整一下目录位置和格式细节而已。我在实际使用中的体会是Skills 最有价值的地方不是“让 AI 记住某一段提示词”而是建立起一套可持续维护、可复用、可分享的 AI 工作流。它把过去依赖个人记忆的零散经验固化成了结构化的文件让 AI 工具真正变成了团队里那个“最懂规矩、最稳定的执行者”。每次模型自动在正确场景加载正确的技能包时那种“它会主动思考了”的感觉都会让我觉得这套投入非常值得。
