1. 从skills这个热词说起它到底是什么为什么突然火了如果你最近在技术社区、AI 工具群或者开发者论坛里频繁看到skills这个词不用怀疑它说的不是传统意义上的技能泛称而是特指Agent Skills——一种让 AI 编程助手尤其是 Claude Code、Codex 这类 CLI Agent获得可复用、可组合、可版本管理的能力模块的机制。你可以把它理解成给 AI 助手装的插件包或者技能卡一个 skill 通常就是一个目录里面放着一份SKILL.md说明文件外加若干脚本、模板、参考资料AI 在遇到对应任务时会自动加载并按照里面的指引干活。我最早接触这个概念是在折腾 Claude Code 的时候。当时我的感受是Claude Code 本身已经很强了能读代码、改文件、跑命令但每次让它做特定领域的事情比如按团队规范生成 commit message、按固定模板写周报、按某种格式解析日志都得在对话里反复交代背景效率很低。后来发现 skills 机制之后我把这些重复的交代固化成了一个个 skillAI 一遇到相关任务就自动按我的规范来省了大量口舌。这就是 skills 的核心价值把隐性的、口头的、一次性的指令变成显性的、文件化的、可复用的能力资产。为什么它现在火我觉得有三个原因。第一Claude Code、Codex 这类 CLI Agent 的普及让AI 直接操作你的项目文件成为常态而 skills 正好解决了如何让 AI 按我的项目规范操作这个痛点。第二SKILL.md这种纯文本、纯 Markdown 的格式门槛极低不需要写复杂代码会写文档就能写 skill前端、后端、数据、建模、写作各类人群都能上手。第三社区开始沉淀skills 推荐skills 技能库大家发现这东西可以像 npm 包一样分享和复用于是形成了正反馈。这篇文章适合谁看如果你是刚听说 skills、想搞清楚它到底是什么的新手我会从零讲清楚它的结构和工作原理如果你已经在用 Claude Code 或 Codex但只会用内置能力、不知道怎么自己写 skill我会给你完整的SKILL.md写法、目录组织、调试方法如果你关心skills 推荐数学建模 skills前端开发 skills这类具体场景我也会结合常见实践给出可抄作业的模板。全文基于我自己的实操经验和社区常见做法整理涉及具体参数和步骤的地方我会说明依据方便你复现。2. skills 的整体设计与核心思路拆解2.1 为什么是文件化 按需加载这套设计要理解 skills 的设计先要理解它要解决的问题。AI 编程助手面临一个根本矛盾上下文窗口有限但项目知识和规范是无限的。你不可能把所有团队规范、所有领域知识都塞进系统提示词里那样既浪费 token又会稀释 AI 对当前任务的注意力。skills 的解法很聪明把知识拆成一个个独立模块平时不加载只在 AI 判断当前任务相关时才读取。这就像你办公室里有一整面书架的参考书你不需要全部背下来遇到具体问题时去抽对应的那本翻一翻就行。SKILL.md里的 frontmatter元数据负责告诉 AI我是干什么的、什么时候该用我正文则负责具体怎么做。这种设计带来几个直接好处。第一可扩展性你可以往 skills 目录里丢几十上百个 skill不会拖垮日常对话因为只有相关的才会被读进来。第二可维护性每个 skill 是独立文件改一个不影响其他还能用 git 做版本管理。第三可组合性一个复杂任务可以触发多个 skill 协同比如写一个带测试的 API 接口可能同时触发代码规范 skill和测试模板 skill。我实测下来这套机制最舒服的地方在于它把提示词工程从对话里搬到了文件里。以前你调 AI 靠的是临场措辞现在你调 AI 靠的是维护好一组 skill 文件。前者不可复用、不可传承后者可以沉淀、可以 review、可以分享给同事。2.2 skill 的目录结构与 SKILL.md 的角色一个标准的 skill 通常长这样my-skill/ ├── SKILL.md # 必需技能说明与元数据 ├── scripts/ # 可选辅助脚本 │ └── helper.py ├── templates/ # 可选模板文件 │ └── report.md └── references/ # 可选参考资料 └── spec.md核心是SKILL.md。它一般分两部分frontmatter和正文。frontmatter 用 YAML 写声明这个 skill 的名字、描述、触发条件等元信息正文用 Markdown 写是给 AI 看的操作手册。为什么元数据这么关键因为 AI 决定要不要用这个 skill靠的就是 frontmatter 里的描述。描述写得含糊AI 就不知道该在什么时候调用描述写得精准AI 一遇到匹配场景就会自动加载。这是很多人写 skill 时最容易忽略、也最影响效果的一点。2.3 和传统提示词模板自定义指令的区别有人会问这不就是高级点的提示词模板吗我的理解是区别在于触发机制和组织方式。传统提示词模板需要你手动粘贴、手动调用skills 是 AI 根据任务自动判断、自动加载。传统自定义指令往往是全局的、一坨的skills 是模块化的、按需的。还有一个关键区别是可执行性。skill 目录里可以放脚本AI 可以调用这些脚本来完成确定性任务比如格式化、计算、调用 API而不是全靠模型脑补。这就把AI 的灵活性和脚本的确定性结合起来了是我认为 skills 设计里最有价值的一点。3. 核心细节解析与实操要点3.1 SKILL.md 的 frontmatter 怎么写才有效frontmatter 是 skill 的身份证。一个典型的写法如下--- name: commit-message-writer description: 当用户需要生成符合团队规范的 git commit message 时使用。适用于提交代码前、整理变更记录等场景。 ---这里name是唯一标识建议用短横线连接的英文小写方便引用。description是最重要的字段它直接决定 AI 会不会在正确时机调用这个 skill。我踩过的坑是一开始把 description 写得太笼统比如帮助写代码结果 AI 几乎从不主动调用因为它判断不出什么时候该用。后来改成当用户需要按 Conventional Commits 规范生成 commit message 时使用命中率立刻上来了。写 description 的经验是用当……时使用的句式把触发场景写具体。可以包含任务类型、输入特征、典型场景关键词。如果这个 skill 有明确的排除场景也可以补一句不适用于……减少误触发。3.2 正文部分给 AI 看的操作手册该怎么写正文是 skill 的灵魂。它不是写给人看的文档而是写给 AI 看的指令。所以写法上要直接、具体、可执行避免模糊的形容词。我总结的正文结构一般是目标说明一句话说清这个 skill 要达成什么。前置检查执行前需要确认什么比如文件是否存在、参数是否齐全。操作步骤分步骤写清楚每步做什么、用什么工具、产出什么。输出格式明确最终产出的格式最好给一个示例。边界与禁忌什么情况下不要这么做哪些操作要谨慎。举个例子一个日志分析 skill的正文可能这样写## 目标 解析用户提供的应用日志提取错误类型、发生时间、影响范围输出结构化报告。 ## 步骤 1. 读取日志文件按行扫描识别包含 ERROR、WARN 关键字的行。 2. 对每条错误提取时间戳、错误码、错误消息。 3. 按错误码聚合统计出现次数。 4. 按出现次数降序排列输出 Markdown 表格。 ## 输出格式 | 错误码 | 错误消息 | 出现次数 | 首次出现时间 | |--------|----------|----------|--------------| ## 注意 - 日志文件超过 100MB 时先提示用户分段处理。 - 不要修改原始日志文件。这种写法 AI 执行起来非常稳因为它每一步都有明确的动作和产出。反过来如果你写分析一下日志看看有什么问题AI 就会自由发挥结果不可控。3.3 脚本与模板让 skill 从会说到会做skill 真正强大的地方在于可以带脚本。比如一个图片批量压缩 skill正文里写调用 scripts/compress.py 处理AI 就会去执行这个脚本而不是试图用模型能力去想象压缩过程。这样既快又准。脚本的写法没有强制要求Python、Shell、Node 都行关键是输入输出要清晰最好支持命令行参数方便 AI 调用。我一般会在正文里明确写清楚脚本的调用方式比如python scripts/compress.py --input ./images --output ./compressed --quality 80模板文件则用于需要固定格式的产出比如报告模板、代码骨架。AI 读取模板后填充内容能保证格式统一。这在团队协作场景里特别有用因为大家产出的东西长得一样review 起来省心。3.4 存放位置与加载机制skills 放哪里不同工具略有差异但常见做法是放在项目根目录的.claude/skills/或用户主目录的~/.claude/skills/下。项目级的 skill 只对当前项目生效用户级的对所有项目生效。我的建议是团队规范类放项目级个人习惯类放用户级。加载机制上AI 启动时会扫描 skills 目录读取每个SKILL.md的 frontmatter建立索引。当任务发生时AI 根据 description 匹配匹配到就读取对应 skill 的正文和资源。所以 frontmatter 写得准不准直接决定匹配效果。注意skill 目录名和 frontmatter 里的 name 最好保持一致避免引用混乱。我见过有人目录叫commit-helpername 写git-commit结果自己都记混了。4. 实操过程与核心环节实现4.1 从零写第一个 skill完整流程假设我要写一个周报生成 skill帮我把一周的 git commit 整理成周报。完整流程如下。第一步建目录。在项目根目录执行mkdir -p .claude/skills/weekly-report/scripts第二步写 SKILL.md。内容如下--- name: weekly-report description: 当用户需要根据 git 提交记录生成周报时使用。适用于周五总结、项目进度汇报等场景。 --- ## 目标 读取指定时间范围内的 git commit按模块归类生成结构化周报。 ## 步骤 1. 运行 scripts/collect_commits.sh 收集最近 7 天的 commit。 2. 按 commit message 前缀feat/fix/docs/refactor分类。 3. 每类下按时间排序提取核心变更。 4. 生成 Markdown 周报包含本周完成进行中下周计划三部分。 ## 输出格式 ### 本周完成 - [模块] 变更描述 ### 进行中 - [模块] 变更描述 ### 下周计划 - 计划项 ## 注意 - 忽略 merge commit。 - 提交信息不清晰时标注待补充而不是编造。第三步写收集脚本。scripts/collect_commits.sh#!/bin/bash # 收集最近 7 天的 commit git log --since7 days ago --no-merges --prettyformat:%h|%ad|%s --dateshort第四步测试。在 Claude Code 里说帮我生成本周周报观察它是否自动加载了这个 skill、是否正确执行了脚本、输出格式是否符合预期。我第一次测试时发现它没触发排查后发现是 description 写得太泛原来写的是生成报告改成根据 git 提交记录生成周报后就正常触发了。这个调试过程很典型skill 不生效八成是 description 的问题。4.2 参数计算与选择以代码审查 skill为例再举一个稍复杂的例子说明参数选择背后的逻辑。假设写一个代码审查 skill需要决定审查的严格程度。我设计了三个档位档位检查项适用场景宽松只看明显 bug 和安全问题快速迭代、原型阶段标准bug 安全 命名规范 注释日常开发严格标准 复杂度 重复代码 测试覆盖核心模块、上线前为什么这么分因为审查严格度和开发效率是矛盾的。原型阶段卡太严会拖慢进度核心模块放太松会埋雷。让 skill 支持档位参数AI 就能根据场景灵活选择。正文里我会写清楚默认使用标准档用户明确要求时才切换避免 AI 自作主张。调用方式上我在正文里约定用户说严格审查就用严格档说快速看一下就用宽松档没说就用标准档。这种自然语言映射到参数的写法比让用户记命令友好得多。4.3 多 skill 协同一个真实场景实际工作中一个任务往往触发多个 skill。比如给这个模块加一个新接口可能同时触发api-designskill按团队 RESTful 规范设计接口。test-templateskill生成对应的单元测试骨架。doc-writerskill更新 API 文档。这三个 skill 各自独立但协同完成一个任务。我实测下来只要每个 skill 的 description 写得准AI 能自动把它们串起来。这里的关键是skill 之间不要职责重叠否则 AI 会纠结用哪个。我的原则是一个 skill 只干一件事干好一件事。如果两个 skill 确实有交叉我会在 description 里明确边界比如本 skill 只负责接口设计不负责测试生成测试请用 test-template。4.4 版本管理与团队协作skills 是文件天然适合 git 管理。我的做法是项目级 skills 直接进项目仓库团队共享个人级 skills 单独建一个仓库方便在多台机器同步。团队协作时我会在 README 里写清楚每个 skill 的用途和触发方式新人 clone 下来就能用。这比写一堆开发规范文档有效得多因为规范文档没人看但 skill 是 AI 强制执行。我带的项目里新人第一周就能产出符合规范的代码很大程度靠的就是这套 skill。提示skill 更新后建议在 commit message 里写清楚改了什么、为什么改方便回溯。我踩过的坑是改了 description 导致触发行为变化但没记录后来排查了半天。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。排查顺序我一般这样走检查目录位置skill 是否放在了正确的 skills 目录下项目级和用户级别放混。检查 frontmatter 格式YAML 对缩进敏感---必须成对出现字段名别拼错。检查 description这是重灾区。描述是否具体是否包含触发场景关键词我建议把 description 读给一个不了解背景的人听如果他能判断出什么时候该用那 AI 大概率也能。检查 name 冲突有没有两个 skill 名字一样会导致加载混乱。重启会话有些工具在会话启动时扫描 skills改完文件需要新开会话才生效。我遇到过一次特别隐蔽的问题SKILL.md文件编码是 GBK 而不是 UTF-8导致 frontmatter 解析失败skill 静默不加载。后来统一用 UTF-8 就再没出过。5.2 skill 触发了但执行不对如果 skill 被加载了但 AI 没按你写的步骤做通常是正文的问题。常见原因步骤太抽象AI 只能猜。解决方法是把每步写成动词 对象 产出。缺少输出示例AI 不知道你要什么格式。补一个示例效果立竿见影。约束没写清比如不要修改原文件这种禁忌不写 AI 就可能改。我的经验是正文写得像给一个聪明但完全不了解你项目的实习生看的操作手册就对了。5.3 常见问题速查表现象可能原因解决方法skill 完全不触发目录位置错 / frontmatter 格式错检查路径与 YAML 语法偶尔触发偶尔不触发description 模糊补充具体触发场景关键词触发后不按步骤执行正文太抽象步骤具体化加输出示例多个 skill 抢触发职责重叠明确边界拆分或合并改了 skill 没生效会话未重启新开会话或重载脚本执行报错路径/权限/依赖问题检查脚本可执行权限与依赖5.4 几个独家避坑心得第一description 里别写帮助辅助这类虚词。AI 匹配靠的是具体场景词虚词只会稀释信号。我现在的 description 模板是当用户需要【具体任务】时使用适用于【具体场景】输入通常是【输入特征】。第二skill 别贪大。一个 skill 塞太多功能AI 反而不知道什么时候用。宁可拆成三个小 skill也不要写一个万能 skill。第三脚本要幂等。如果 skill 里的脚本会被重复执行一定要保证重复执行不出错。我写过一个初始化项目结构的脚本第一次跑没问题第二次跑因为目录已存在直接报错导致 AI 以为任务失败。后来加了mkdir -p和存在性检查就好了。第四给 skill 写测试。我会准备几个典型输入每次改完 skill 都跑一遍看输出是否符合预期。这跟写代码要写测试是一个道理能避免改 A 坏 B。第五善用社区 skills。网上有不少现成的 skills 推荐和技能库比如数学建模、前端开发、文档写作等场景都有沉淀。我的做法是先找现成的用用着不顺手再改改着改着就形成自己的了。但要注意引入别人的 skill 前一定要读一遍正文确认没有你不想要的行为尤其是涉及文件操作和命令执行的。6. 不同场景下的 skills 实践建议6.1 前端开发场景前端开发用 skills 收益很明显。我常用的几个组件生成 skill按团队规范生成 React/Vue 组件骨架、样式规范 skill统一 CSS 命名和结构、接口联调 skill根据后端接口文档生成请求封装。前端的特点是模板化程度高所以 skill 里放模板文件特别合适。比如组件模板## 组件模板 - 文件名PascalCase - 必须包含props 类型定义、默认导出、样式引入 - 禁止内联样式、any 类型AI 按这个生成产出一致性很高review 成本大幅下降。6.2 数学建模与数据分析场景数学建模比赛里skills 能帮你固化解题套路。比如一个数据预处理 skill规定缺失值怎么填、异常值怎么处理、标准化用哪种方法一个模型评估 skill规定用哪些指标、怎么画图、报告怎么写。比赛时间紧有这套 skill 能省下大量重复劳动。我建议把常用的算法模板、绘图脚本都放进 skill 目录比赛时直接调用。数据分析场景类似把数据清洗特征工程可视化拆成独立 skill每个 skill 里放对应的脚本和规范分析流程会顺畅很多。6.3 文档写作与知识管理场景写作类 skill 的核心是风格约束。比如一个技术文档 skill规定标题层级、代码块标注、术语统一一个周报 skill规定结构和小标题。这类 skill 不需要脚本纯靠正文约束就能显著提升产出质量。我自己的知识管理里把读书笔记模板会议纪要模板都做成了 skillAI 一遇到对应任务就按模板来省心。6.4 如何持续积累自己的 skills 库我的建议是从痛点出发别为了写而写。每次你在对话里重复交代同一件事超过两次就该考虑把它固化成 skill 了。积累节奏上一周加一两个几个月下来就是一套很趁手的工具库。维护上我会定期回顾哪些 skill 从来没用过可能 description 有问题或场景不匹配哪些经常用但效果一般需要优化正文。把 skills 库当成一个活的项目来经营而不是写完就扔。7. 我个人的一些实操体会折腾 skills 这段时间最大的感受是它改变了我跟 AI 协作的方式。以前我是每次重新教 AI 做事现在是一次教好长期复用。这个转变带来的效率提升比我换任何模型都明显。另一个体会是写 skill 的过程其实是在梳理自己的方法论。你得先想清楚这件事到底该怎么做才能写成 skill。很多时候写着写着我发现自己以前的做法其实不规范正好借这个机会理顺了。最后分享一个小技巧如果你不确定一个 skill 该怎么写可以先在对话里手动做一遍把有效的指令记下来再整理成SKILL.md。这种先跑通再固化的路径比对着空白文件硬憋要高效得多。skills 这东西用起来比看起来简单关键是迈出写第一个的那一步。