1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在开发者社区、技术群或者视频平台上频繁刷到“skills”这个词大概率不是指传统意义上的“技能”泛称而是特指围绕 Claude 生态、尤其是 Claude Code 和 Agent Skills 体系衍生出来的一整套能力扩展机制。简单来说skills 就是让 AI 助手从“能聊天”变成“能干活”的关键拼图。它不是一个孤立的工具而是一套约定俗成的文件结构、描述规范和执行逻辑让模型能够按照你预设的流程、规则和知识去完成特定任务。我最早接触这个概念是在折腾 Claude Code 的时候。当时想让 AI 帮我处理一些重复性的代码审查和文档生成工作但直接对话总是“每次都要重新解释一遍需求”效率很低。后来发现社区里已经有人在用 SKILL.md 这种文件来定义可复用的能力模块才意识到这就是我需要的方案。skills 解决的核心问题就一个把“一次性提示词”变成“可持久化、可复用、可组合的能力单元”。你写一次后面所有支持这套机制的 AI 工具都能直接调用不用反复调教。这套东西适合谁三类人最应该关注。第一类是日常使用 Claude Code 或类似 AI 编程助手的开发者skills 能让你把常用工作流固化下来比如“按团队规范生成 commit message”“自动检查 SQL 注入风险”“把需求文档转成测试用例”。第二类是需要批量处理特定领域任务的人比如数学建模、数据分析、内容创作社区里已经有大量现成的 skills 可以直接拿来用。第三类是想把自己的经验产品化的人你可以把自己擅长的领域知识写成 skill分享出去或者团队内部复用。但这里有个现实问题网上关于 skills 的信息非常零散有的讲概念有的贴代码有的只给下载链接不说怎么用。新手很容易卡在“知道有这么个东西但不知道从哪下手”的阶段。我踩过这个坑所以这篇文章会把整个链路串起来——从理解 skills 的本质到手动安装、编写、调试、避坑尽量让不同基础的人都能跟着走一遍。2. skills 的核心机制拆解为什么是 SKILL.md而不是别的2.1 文件结构背后的设计逻辑Agent Skills 最核心的载体就是SKILL.md这个文件。你可能会问为什么不是 JSON、YAML 或者直接写代码我一开始也有这个疑问后来实际用下来才理解其中的取舍。Markdown 的好处是人和机器都能读。对模型来说Markdown 的标题层级、列表、代码块本身就是一种天然的结构化提示模型在训练时见过海量 Markdown解析起来非常自然。对人来说你不需要学额外的语法就能看懂和修改降低了维护成本。一个典型的 skill 目录结构大概长这样my-skill/ ├── SKILL.md ├── references/ │ └── style-guide.md ├── scripts/ │ └── validate.py └── assets/ └── template.txtSKILL.md是入口文件里面用 frontmatter 声明元信息正文部分描述这个 skill 能做什么、什么时候触发、具体执行步骤是什么。references放参考文档scripts放可执行脚本assets放模板或静态资源。这种分层的设计让 skill 既有“说明书”又有“工具箱”模型可以根据需要决定是直接读文档回答还是调用脚本执行。注意不同工具对 skill 目录的识别路径可能不同。Claude Code 通常会在项目根目录或用户配置目录下查找.claude/skills或类似路径具体要看你使用的版本和平台。手动安装时路径放错是最常见的“装了但没反应”的原因。2.2 SKILL.md 里到底该写什么我见过很多新手写的 SKILL.md要么太笼统“这个 skill 用来处理数据”要么太啰嗦把整个操作手册全塞进去。好的 SKILL.md 应该像一份给聪明但完全不了解你项目的同事看的交接文档——说清楚目标、输入、输出、步骤和边界。一个实用的模板大概包含这几块--- name: sql-review description: 审查 SQL 语句检查性能问题和注入风险 trigger: 当用户提交 SQL 代码或要求审查数据库查询时 --- ## 目标 对给定的 SQL 语句进行静态审查输出问题列表和修改建议。 ## 输入 - SQL 语句必填 - 数据库类型可选默认 MySQL ## 执行步骤 1. 解析 SQL 语句识别表名、字段、条件、连接方式 2. 检查是否存在 SELECT *、缺少 WHERE 的 UPDATE/DELETE 3. 检查拼接字符串导致的注入风险 4. 检查索引使用情况根据提供的表结构 5. 按严重程度输出问题列表 ## 输出格式 | 严重程度 | 问题 | 位置 | 建议 | |---------|------|------|------| ## 边界 - 不执行 SQL只做静态分析 - 不处理存储过程和触发器这里的关键是trigger 字段。它决定了模型什么时候会主动调用这个 skill。写得太宽泛会导致误触发写得太窄又永远用不上。我的经验是trigger 里要包含用户可能说的原话关键词比如“审查 SQL”“看看这个查询有没有问题”“优化一下这条语句”。2.3 为什么 skills 比传统提示词工程更“稳”传统提示词工程的问题是上下文漂移。你写了一段很长的系统提示对话轮次一多模型可能就忘了前面的约束。skills 的机制不一样它是在需要的时候才被加载进上下文而且有明确的文件边界。模型看到的是一个独立的、自包含的指令单元不容易被其他对话内容干扰。另一个优势是可组合性。你可以同时装多个 skills模型会根据当前任务自动选择相关的。比如你装了“代码审查”“文档生成”“测试用例编写”三个 skills当用户说“帮我看看这段代码并补个测试”模型可以依次调用前两个。这种组合能力是单一提示词很难做到的。3. 手动安装与配置从零把 skills 跑起来3.1 环境准备与前置检查在开始装 skills 之前有几件事必须先确认。第一你的 Claude Code 或相关工具版本是否支持 skills 机制。早期版本可能只支持基础的对话功能没有 skill 加载能力。第二确认你的操作系统和运行环境。Windows 用户可能会遇到一些路径和权限问题后面会细说。我建议按这个清单过一遍检查项要求检查方法工具版本支持 skills 的版本查看官方更新日志或运行claude --version配置目录存在 skills 存放路径检查~/.claude/skills或项目内.claude/skills文件权限可读写尝试在目标目录创建测试文件网络能访问 skill 来源如果从 GitHub 下载确保能正常访问提示如果你在 Windows 上遇到“requires the virtual machine platform”之类的提示通常是 WSL 或虚拟化组件没开。这个和 skills 本身无关但会影响 Claude Code 的正常运行。建议先把基础环境跑通再折腾 skills。3.2 从 GitHub 手动安装一个 skill 的完整流程网上很多 skill 都托管在 GitHub 上但 Claude Code 并没有一键安装的命令至少目前主流版本是这样。所以手动安装是必备技能。我以安装一个假设的“code-review” skill 为例把每一步拆开讲。第一步找到 skill 仓库。通常仓库根目录或某个子目录下会有SKILL.md文件。你要做的是确认这个 skill 的入口文件在哪以及它是否依赖额外的脚本或资源。第二步下载到本地。可以直接用 git clone也可以下载 zip 解压。我习惯用 git clone方便后续更新git clone https://github.com/example/code-review-skill.git第三步放到正确的目录。这是最容易出错的地方。Claude Code 查找 skills 的路径通常是用户级~/.claude/skills/项目级项目根目录/.claude/skills/用户级对所有项目生效项目级只对当前项目生效。我一般把通用型的 skill 放用户级项目特定的放项目级。把刚才 clone 下来的整个文件夹复制过去cp -r code-review-skill ~/.claude/skills/第四步验证是否被识别。重启 Claude Code然后问它“你现在有哪些可用的 skills”或者直接触发相关任务看它会不会调用。如果没反应检查目录名和 SKILL.md 的 frontmatter 格式是否正确。第五步调试和调整。如果 skill 被识别但效果不对先看 SKILL.md 的 trigger 是否匹配你的说法再看执行步骤是否清晰。很多时候问题出在描述太模糊模型不知道什么时候该用。3.3 Windows 和 macOS 的差异处理Windows 上装 skills 有几个坑我亲自踩过。首先是路径分隔符Windows 用反斜杠但很多 skill 脚本里写的是正斜杠。如果脚本执行报错先检查路径写法。其次是换行符Windows 的 CRLF 和 Unix 的 LF 在某些解析场景下会导致问题建议用编辑器统一转成 LF。另外Windows 上 Claude Code 可能依赖 WSL 环境。如果你在 PowerShell 里直接运行遇到问题可以试试在 WSL 终端里操作。文件放在 WSL 的文件系统里路径用/home/username/.claude/skills/这种形式。macOS 相对省心但要注意权限问题。如果从网上下载的 skill 文件夹带有隔离属性可能需要手动去掉xattr -d com.apple.quarantine ~/.claude/skills/your-skill4. 自己写一个 skill从需求到可运行4.1 选题什么样的任务适合做成 skill不是所有事情都值得写成 skill。我总结了一个简单的判断标准如果一个任务你每周至少重复一次而且步骤相对固定那就值得做成 skill。比如“把会议记录转成待办事项”“按模板生成周报”“检查代码里的敏感信息”“把需求描述转成用户故事”。反过来那些一次性的、高度依赖具体上下文的、需要大量人工判断的任务做成 skill 反而累赘。比如“帮我设计一个系统架构”这种任务每次的约束条件都不一样硬写成 skill 会非常僵硬。社区里比较受欢迎的 skills 类型包括代码审查、文档生成、数据清洗、数学建模辅助、内容改写、测试用例生成。你可以先从自己最熟悉的领域入手写一个解决自己痛点的小 skill跑通之后再扩展。4.2 编写 SKILL.md 的实操要点写 SKILL.md 的时候我建议遵循“先写清楚再写简洁”的原则。第一版可以啰嗦一点把各种边界情况都列出来等实际用顺了再精简。几个关键点name 要短且唯一避免和已有 skill 冲突。用英文小写加连字符比如sql-review、doc-gen。description 要一句话说清楚价值不要写“这是一个用于处理数据的 skill”这种废话。写成“把 CSV 文件按指定列去重并输出统计报告”就具体多了。trigger 要包含用户可能的表达方式。可以多写几个同义句用逗号分隔。执行步骤要可操作。不要写“分析数据”要写“读取 CSV 文件识别数值列和分类列对数值列计算均值和标准差”。输出格式要明确。模型需要知道最终产出是什么形式是 Markdown 表格、JSON、还是纯文本。注意SKILL.md 里不要写和任务无关的背景故事。模型不需要知道你为什么要做这个 skill它只需要知道怎么做。冗余信息会占用上下文窗口降低执行准确率。4.3 测试与迭代怎么知道 skill 写得好不好写完第一版之后别急着分享。先自己用一周记录每次触发的情况。我通常会关注三个指标触发准确率该用的时候有没有用、执行正确率步骤有没有跑偏、输出可用率结果能不能直接用。如果触发不准调整 trigger 的关键词。如果执行跑偏检查步骤是不是有歧义。如果输出不可用把输出格式写得更具体最好给一个示例。迭代的时候建议保留版本记录。我习惯在 SKILL.md 底部加一个简单的变更日志## 变更记录 - v1.0 初始版本 - v1.1 增加对 PostgreSQL 的支持 - v1.2 修复 trigger 误触发问题这样团队协作或者分享出去的时候别人能快速了解这个 skill 的演进过程。5. 常见问题与排查技巧实录5.1 装了 skill 但模型不调用怎么查这是最高频的问题。排查顺序我一般是这样确认目录对不对。运行ls ~/.claude/skills/看看文件夹在不在。确认 SKILL.md 格式对不对。frontmatter 必须以---开头和结尾中间不能有空行错误。确认 trigger 是否匹配。你说话的方式和 trigger 里写的差太远模型可能识别不到。试着用 trigger 里的原话去触发。确认工具版本支持。有些老版本根本不读 skills 目录升级到最新版再试。看日志。如果工具支持 verbose 模式打开后能看到 skill 加载的详细过程。5.2 skill 执行到一半卡住或报错这种情况通常是脚本依赖或路径问题。先看报错信息里有没有“file not found”或“permission denied”。如果是脚本问题手动在终端里跑一遍那个脚本看能不能独立执行。如果是路径问题把 SKILL.md 里的相对路径改成绝对路径试试。还有一个隐蔽的坑脚本里的 shebang 行。如果脚本第一行是#!/usr/bin/env python3但你的系统里 python3 不在这个路径就会执行失败。用which python3确认实际路径。5.3 多个 skills 冲突怎么办当你装了很多 skills可能会出现两个 skill 都觉得自己该被调用的情况。这时候模型可能会选错或者把两个 skill 的步骤混在一起。解决办法有两个一是把 trigger 写得更精确减少重叠二是给 skill 加优先级标记在 description 里写明“仅当用户明确要求 X 时使用”。我自己的习惯是同类任务只保留一个 skill。比如代码审查要么用社区版要么用自己的不要同时装两个功能重叠的。5.4 常见问题速查表现象可能原因解决方法装了没反应目录错误检查~/.claude/skills或项目内路径触发不准确trigger 太宽/太窄调整关键词增加同义表达执行报错脚本依赖缺失手动运行脚本安装缺失依赖输出格式乱输出描述不清晰在 SKILL.md 中给出明确示例多个 skill 打架功能重叠合并或禁用其中一个Windows 路径问题分隔符或权限用 WSL 或统一用正斜杠提示每次修改 SKILL.md 后最好重启一下工具确保新配置被加载。有些工具会缓存 skill 列表不重启可能看不到变化。6. 进阶玩法把 skills 用出组合拳6.1 数学建模场景下的 skills 组合数学建模比赛是 skills 应用的一个典型场景。我见过有人把“数据预处理”“模型选择”“论文排版”分别做成三个 skill比赛时按流程依次调用。数据预处理 skill 负责清洗和归一化模型选择 skill 根据问题类型推荐算法论文排版 skill 按竞赛模板生成文档。这种组合能把重复劳动压缩到最低把时间留给真正的建模思考。具体操作上你可以在项目目录下建一个.claude/skills文件夹把三个 skill 都放进去。然后在对话里说“先做数据预处理再选模型最后按模板排版”模型会依次触发对应的 skill。关键是每个 skill 的输入输出要能衔接上比如预处理 skill 的输出格式要能被模型选择 skill 直接读取。6.2 内容创作与 AI 漫剧的 skills 实践最近 AI 漫剧很火有人用 skills 来管理角色设定、分镜脚本和台词风格。比如建一个“角色一致性”skill里面定义每个角色的说话习惯、外貌特征、背景故事。每次生成新剧情时模型会自动加载这个 skill确保角色不会“串味”。另一个“分镜格式”skill 负责把剧本转成标准的分镜表格方便后续制作。这种用法的核心思路是把创作规范从人脑里搬到文件里。以前这些设定可能散落在各种笔记和聊天记录里现在集中在一个 SKILL.md 中模型每次都能读到最新版本减少了前后不一致的问题。6.3 团队协作中的 skills 管理如果是团队使用skills 的版本管理就很重要。我建议把 skills 目录纳入 Git 仓库和代码一起管理。每个人都可以提交新的 skill 或修改现有的通过 PR 流程审核。这样既能保证质量又能让知识沉淀下来。另外团队内部可以约定一套命名规范比如team-前缀表示内部专用ext-前缀表示外部引入。这样一眼就能看出 skill 的来源和维护责任。7. 我踩过的坑和最后分享几个实用技巧第一个坑是贪多。刚开始我装了十几个 skills结果模型经常选错反而降低了效率。后来精简到五个常用的准确率明显提升。所以别追求数量先把一两个用到极致。第二个坑是SKILL.md 写得太长。我一开始把各种边界情况都写进去结果模型执行时反而抓不住重点。后来学会把详细参考放到references目录SKILL.md 只保留核心步骤和触发条件效果好很多。第三个坑是忽略版本更新。有些社区 skill 更新后改了目录结构或依赖我直接覆盖安装导致旧配置丢失。现在我会先备份再更新或者用 git 管理方便回滚。最后分享一个小技巧给 skill 加一个“自检”步骤。在 SKILL.md 的最后写一句“执行完成后检查输出是否满足以下条件……”。模型会自己验证一遍减少低级错误。这个技巧在代码审查和文档生成类 skill 里特别管用。还有一个实用建议如果你不确定某个任务适不适合做成 skill先用普通对话跑几遍把有效的提示词记录下来再整理成 SKILL.md。这样写出来的 skill 更接地气也更容易一次跑通。
从零掌握 Claude Agent Skills：SKILL.md 编写、手动安装与实战避坑指南
1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在开发者社区、技术群或者视频平台上频繁刷到“skills”这个词大概率不是指传统意义上的“技能”泛称而是特指围绕 Claude 生态、尤其是 Claude Code 和 Agent Skills 体系衍生出来的一整套能力扩展机制。简单来说skills 就是让 AI 助手从“能聊天”变成“能干活”的关键拼图。它不是一个孤立的工具而是一套约定俗成的文件结构、描述规范和执行逻辑让模型能够按照你预设的流程、规则和知识去完成特定任务。我最早接触这个概念是在折腾 Claude Code 的时候。当时想让 AI 帮我处理一些重复性的代码审查和文档生成工作但直接对话总是“每次都要重新解释一遍需求”效率很低。后来发现社区里已经有人在用 SKILL.md 这种文件来定义可复用的能力模块才意识到这就是我需要的方案。skills 解决的核心问题就一个把“一次性提示词”变成“可持久化、可复用、可组合的能力单元”。你写一次后面所有支持这套机制的 AI 工具都能直接调用不用反复调教。这套东西适合谁三类人最应该关注。第一类是日常使用 Claude Code 或类似 AI 编程助手的开发者skills 能让你把常用工作流固化下来比如“按团队规范生成 commit message”“自动检查 SQL 注入风险”“把需求文档转成测试用例”。第二类是需要批量处理特定领域任务的人比如数学建模、数据分析、内容创作社区里已经有大量现成的 skills 可以直接拿来用。第三类是想把自己的经验产品化的人你可以把自己擅长的领域知识写成 skill分享出去或者团队内部复用。但这里有个现实问题网上关于 skills 的信息非常零散有的讲概念有的贴代码有的只给下载链接不说怎么用。新手很容易卡在“知道有这么个东西但不知道从哪下手”的阶段。我踩过这个坑所以这篇文章会把整个链路串起来——从理解 skills 的本质到手动安装、编写、调试、避坑尽量让不同基础的人都能跟着走一遍。2. skills 的核心机制拆解为什么是 SKILL.md而不是别的2.1 文件结构背后的设计逻辑Agent Skills 最核心的载体就是SKILL.md这个文件。你可能会问为什么不是 JSON、YAML 或者直接写代码我一开始也有这个疑问后来实际用下来才理解其中的取舍。Markdown 的好处是人和机器都能读。对模型来说Markdown 的标题层级、列表、代码块本身就是一种天然的结构化提示模型在训练时见过海量 Markdown解析起来非常自然。对人来说你不需要学额外的语法就能看懂和修改降低了维护成本。一个典型的 skill 目录结构大概长这样my-skill/ ├── SKILL.md ├── references/ │ └── style-guide.md ├── scripts/ │ └── validate.py └── assets/ └── template.txtSKILL.md是入口文件里面用 frontmatter 声明元信息正文部分描述这个 skill 能做什么、什么时候触发、具体执行步骤是什么。references放参考文档scripts放可执行脚本assets放模板或静态资源。这种分层的设计让 skill 既有“说明书”又有“工具箱”模型可以根据需要决定是直接读文档回答还是调用脚本执行。注意不同工具对 skill 目录的识别路径可能不同。Claude Code 通常会在项目根目录或用户配置目录下查找.claude/skills或类似路径具体要看你使用的版本和平台。手动安装时路径放错是最常见的“装了但没反应”的原因。2.2 SKILL.md 里到底该写什么我见过很多新手写的 SKILL.md要么太笼统“这个 skill 用来处理数据”要么太啰嗦把整个操作手册全塞进去。好的 SKILL.md 应该像一份给聪明但完全不了解你项目的同事看的交接文档——说清楚目标、输入、输出、步骤和边界。一个实用的模板大概包含这几块--- name: sql-review description: 审查 SQL 语句检查性能问题和注入风险 trigger: 当用户提交 SQL 代码或要求审查数据库查询时 --- ## 目标 对给定的 SQL 语句进行静态审查输出问题列表和修改建议。 ## 输入 - SQL 语句必填 - 数据库类型可选默认 MySQL ## 执行步骤 1. 解析 SQL 语句识别表名、字段、条件、连接方式 2. 检查是否存在 SELECT *、缺少 WHERE 的 UPDATE/DELETE 3. 检查拼接字符串导致的注入风险 4. 检查索引使用情况根据提供的表结构 5. 按严重程度输出问题列表 ## 输出格式 | 严重程度 | 问题 | 位置 | 建议 | |---------|------|------|------| ## 边界 - 不执行 SQL只做静态分析 - 不处理存储过程和触发器这里的关键是trigger 字段。它决定了模型什么时候会主动调用这个 skill。写得太宽泛会导致误触发写得太窄又永远用不上。我的经验是trigger 里要包含用户可能说的原话关键词比如“审查 SQL”“看看这个查询有没有问题”“优化一下这条语句”。2.3 为什么 skills 比传统提示词工程更“稳”传统提示词工程的问题是上下文漂移。你写了一段很长的系统提示对话轮次一多模型可能就忘了前面的约束。skills 的机制不一样它是在需要的时候才被加载进上下文而且有明确的文件边界。模型看到的是一个独立的、自包含的指令单元不容易被其他对话内容干扰。另一个优势是可组合性。你可以同时装多个 skills模型会根据当前任务自动选择相关的。比如你装了“代码审查”“文档生成”“测试用例编写”三个 skills当用户说“帮我看看这段代码并补个测试”模型可以依次调用前两个。这种组合能力是单一提示词很难做到的。3. 手动安装与配置从零把 skills 跑起来3.1 环境准备与前置检查在开始装 skills 之前有几件事必须先确认。第一你的 Claude Code 或相关工具版本是否支持 skills 机制。早期版本可能只支持基础的对话功能没有 skill 加载能力。第二确认你的操作系统和运行环境。Windows 用户可能会遇到一些路径和权限问题后面会细说。我建议按这个清单过一遍检查项要求检查方法工具版本支持 skills 的版本查看官方更新日志或运行claude --version配置目录存在 skills 存放路径检查~/.claude/skills或项目内.claude/skills文件权限可读写尝试在目标目录创建测试文件网络能访问 skill 来源如果从 GitHub 下载确保能正常访问提示如果你在 Windows 上遇到“requires the virtual machine platform”之类的提示通常是 WSL 或虚拟化组件没开。这个和 skills 本身无关但会影响 Claude Code 的正常运行。建议先把基础环境跑通再折腾 skills。3.2 从 GitHub 手动安装一个 skill 的完整流程网上很多 skill 都托管在 GitHub 上但 Claude Code 并没有一键安装的命令至少目前主流版本是这样。所以手动安装是必备技能。我以安装一个假设的“code-review” skill 为例把每一步拆开讲。第一步找到 skill 仓库。通常仓库根目录或某个子目录下会有SKILL.md文件。你要做的是确认这个 skill 的入口文件在哪以及它是否依赖额外的脚本或资源。第二步下载到本地。可以直接用 git clone也可以下载 zip 解压。我习惯用 git clone方便后续更新git clone https://github.com/example/code-review-skill.git第三步放到正确的目录。这是最容易出错的地方。Claude Code 查找 skills 的路径通常是用户级~/.claude/skills/项目级项目根目录/.claude/skills/用户级对所有项目生效项目级只对当前项目生效。我一般把通用型的 skill 放用户级项目特定的放项目级。把刚才 clone 下来的整个文件夹复制过去cp -r code-review-skill ~/.claude/skills/第四步验证是否被识别。重启 Claude Code然后问它“你现在有哪些可用的 skills”或者直接触发相关任务看它会不会调用。如果没反应检查目录名和 SKILL.md 的 frontmatter 格式是否正确。第五步调试和调整。如果 skill 被识别但效果不对先看 SKILL.md 的 trigger 是否匹配你的说法再看执行步骤是否清晰。很多时候问题出在描述太模糊模型不知道什么时候该用。3.3 Windows 和 macOS 的差异处理Windows 上装 skills 有几个坑我亲自踩过。首先是路径分隔符Windows 用反斜杠但很多 skill 脚本里写的是正斜杠。如果脚本执行报错先检查路径写法。其次是换行符Windows 的 CRLF 和 Unix 的 LF 在某些解析场景下会导致问题建议用编辑器统一转成 LF。另外Windows 上 Claude Code 可能依赖 WSL 环境。如果你在 PowerShell 里直接运行遇到问题可以试试在 WSL 终端里操作。文件放在 WSL 的文件系统里路径用/home/username/.claude/skills/这种形式。macOS 相对省心但要注意权限问题。如果从网上下载的 skill 文件夹带有隔离属性可能需要手动去掉xattr -d com.apple.quarantine ~/.claude/skills/your-skill4. 自己写一个 skill从需求到可运行4.1 选题什么样的任务适合做成 skill不是所有事情都值得写成 skill。我总结了一个简单的判断标准如果一个任务你每周至少重复一次而且步骤相对固定那就值得做成 skill。比如“把会议记录转成待办事项”“按模板生成周报”“检查代码里的敏感信息”“把需求描述转成用户故事”。反过来那些一次性的、高度依赖具体上下文的、需要大量人工判断的任务做成 skill 反而累赘。比如“帮我设计一个系统架构”这种任务每次的约束条件都不一样硬写成 skill 会非常僵硬。社区里比较受欢迎的 skills 类型包括代码审查、文档生成、数据清洗、数学建模辅助、内容改写、测试用例生成。你可以先从自己最熟悉的领域入手写一个解决自己痛点的小 skill跑通之后再扩展。4.2 编写 SKILL.md 的实操要点写 SKILL.md 的时候我建议遵循“先写清楚再写简洁”的原则。第一版可以啰嗦一点把各种边界情况都列出来等实际用顺了再精简。几个关键点name 要短且唯一避免和已有 skill 冲突。用英文小写加连字符比如sql-review、doc-gen。description 要一句话说清楚价值不要写“这是一个用于处理数据的 skill”这种废话。写成“把 CSV 文件按指定列去重并输出统计报告”就具体多了。trigger 要包含用户可能的表达方式。可以多写几个同义句用逗号分隔。执行步骤要可操作。不要写“分析数据”要写“读取 CSV 文件识别数值列和分类列对数值列计算均值和标准差”。输出格式要明确。模型需要知道最终产出是什么形式是 Markdown 表格、JSON、还是纯文本。注意SKILL.md 里不要写和任务无关的背景故事。模型不需要知道你为什么要做这个 skill它只需要知道怎么做。冗余信息会占用上下文窗口降低执行准确率。4.3 测试与迭代怎么知道 skill 写得好不好写完第一版之后别急着分享。先自己用一周记录每次触发的情况。我通常会关注三个指标触发准确率该用的时候有没有用、执行正确率步骤有没有跑偏、输出可用率结果能不能直接用。如果触发不准调整 trigger 的关键词。如果执行跑偏检查步骤是不是有歧义。如果输出不可用把输出格式写得更具体最好给一个示例。迭代的时候建议保留版本记录。我习惯在 SKILL.md 底部加一个简单的变更日志## 变更记录 - v1.0 初始版本 - v1.1 增加对 PostgreSQL 的支持 - v1.2 修复 trigger 误触发问题这样团队协作或者分享出去的时候别人能快速了解这个 skill 的演进过程。5. 常见问题与排查技巧实录5.1 装了 skill 但模型不调用怎么查这是最高频的问题。排查顺序我一般是这样确认目录对不对。运行ls ~/.claude/skills/看看文件夹在不在。确认 SKILL.md 格式对不对。frontmatter 必须以---开头和结尾中间不能有空行错误。确认 trigger 是否匹配。你说话的方式和 trigger 里写的差太远模型可能识别不到。试着用 trigger 里的原话去触发。确认工具版本支持。有些老版本根本不读 skills 目录升级到最新版再试。看日志。如果工具支持 verbose 模式打开后能看到 skill 加载的详细过程。5.2 skill 执行到一半卡住或报错这种情况通常是脚本依赖或路径问题。先看报错信息里有没有“file not found”或“permission denied”。如果是脚本问题手动在终端里跑一遍那个脚本看能不能独立执行。如果是路径问题把 SKILL.md 里的相对路径改成绝对路径试试。还有一个隐蔽的坑脚本里的 shebang 行。如果脚本第一行是#!/usr/bin/env python3但你的系统里 python3 不在这个路径就会执行失败。用which python3确认实际路径。5.3 多个 skills 冲突怎么办当你装了很多 skills可能会出现两个 skill 都觉得自己该被调用的情况。这时候模型可能会选错或者把两个 skill 的步骤混在一起。解决办法有两个一是把 trigger 写得更精确减少重叠二是给 skill 加优先级标记在 description 里写明“仅当用户明确要求 X 时使用”。我自己的习惯是同类任务只保留一个 skill。比如代码审查要么用社区版要么用自己的不要同时装两个功能重叠的。5.4 常见问题速查表现象可能原因解决方法装了没反应目录错误检查~/.claude/skills或项目内路径触发不准确trigger 太宽/太窄调整关键词增加同义表达执行报错脚本依赖缺失手动运行脚本安装缺失依赖输出格式乱输出描述不清晰在 SKILL.md 中给出明确示例多个 skill 打架功能重叠合并或禁用其中一个Windows 路径问题分隔符或权限用 WSL 或统一用正斜杠提示每次修改 SKILL.md 后最好重启一下工具确保新配置被加载。有些工具会缓存 skill 列表不重启可能看不到变化。6. 进阶玩法把 skills 用出组合拳6.1 数学建模场景下的 skills 组合数学建模比赛是 skills 应用的一个典型场景。我见过有人把“数据预处理”“模型选择”“论文排版”分别做成三个 skill比赛时按流程依次调用。数据预处理 skill 负责清洗和归一化模型选择 skill 根据问题类型推荐算法论文排版 skill 按竞赛模板生成文档。这种组合能把重复劳动压缩到最低把时间留给真正的建模思考。具体操作上你可以在项目目录下建一个.claude/skills文件夹把三个 skill 都放进去。然后在对话里说“先做数据预处理再选模型最后按模板排版”模型会依次触发对应的 skill。关键是每个 skill 的输入输出要能衔接上比如预处理 skill 的输出格式要能被模型选择 skill 直接读取。6.2 内容创作与 AI 漫剧的 skills 实践最近 AI 漫剧很火有人用 skills 来管理角色设定、分镜脚本和台词风格。比如建一个“角色一致性”skill里面定义每个角色的说话习惯、外貌特征、背景故事。每次生成新剧情时模型会自动加载这个 skill确保角色不会“串味”。另一个“分镜格式”skill 负责把剧本转成标准的分镜表格方便后续制作。这种用法的核心思路是把创作规范从人脑里搬到文件里。以前这些设定可能散落在各种笔记和聊天记录里现在集中在一个 SKILL.md 中模型每次都能读到最新版本减少了前后不一致的问题。6.3 团队协作中的 skills 管理如果是团队使用skills 的版本管理就很重要。我建议把 skills 目录纳入 Git 仓库和代码一起管理。每个人都可以提交新的 skill 或修改现有的通过 PR 流程审核。这样既能保证质量又能让知识沉淀下来。另外团队内部可以约定一套命名规范比如team-前缀表示内部专用ext-前缀表示外部引入。这样一眼就能看出 skill 的来源和维护责任。7. 我踩过的坑和最后分享几个实用技巧第一个坑是贪多。刚开始我装了十几个 skills结果模型经常选错反而降低了效率。后来精简到五个常用的准确率明显提升。所以别追求数量先把一两个用到极致。第二个坑是SKILL.md 写得太长。我一开始把各种边界情况都写进去结果模型执行时反而抓不住重点。后来学会把详细参考放到references目录SKILL.md 只保留核心步骤和触发条件效果好很多。第三个坑是忽略版本更新。有些社区 skill 更新后改了目录结构或依赖我直接覆盖安装导致旧配置丢失。现在我会先备份再更新或者用 git 管理方便回滚。最后分享一个小技巧给 skill 加一个“自检”步骤。在 SKILL.md 的最后写一句“执行完成后检查输出是否满足以下条件……”。模型会自己验证一遍减少低级错误。这个技巧在代码审查和文档生成类 skill 里特别管用。还有一个实用建议如果你不确定某个任务适不适合做成 skill先用普通对话跑几遍把有效的提示词记录下来再整理成 SKILL.md。这样写出来的 skill 更接地气也更容易一次跑通。
