说实话，我第一眼见“Skills”这个词，是在 Matt Pocock 的视频和仓库里。当时心里想的和很多人一样：这不就是“技能”的英文复数嘛，八成又是 AI 圈包装出来的新概念。直到我真的把一个社区技能装进 Claude Code，又照着同样的思路给团队写了个“周报生成器”，才意识到这套机制不是花架子。它把 AI 对话里一次性的提示词，变成了一份可复用、可审查、可版本管理的工程文件。这篇文章我会把我验证过的用法完整写出来，包括 Skills 的底层逻辑、手动安装的方法、从零写一份 SKILL.md 的具体步骤，以及数学建模、AI 漫剧、前端开发里真正落地的玩法。不管你是第一次听说，还是已经在用 superpower skills 这类合集，读完应该都能建立一套自己的技能库管理方式。
1. 核心思路拆解：Skill 到底是什么，Matt Pocock 为什么绕不开
1.1 它不是“贴提示词”，而是一份给 AI 的工作手册
普通提示词只能用在一段对话里，换会话就失效。Skill 则是一整套文件结构：一个技能目录里放着SKILL.md，里面有对模型的要求和说明，旁边还可以挂脚本、素材和配置文件。当用户提出需求时，AI 会通过description做语义匹配，把和当前意图相关的技能加载进来。这相当于从冰箱门上贴一张“做红烧肉”的便签，升级到直接递给 AI 一本写满主料、配料、火候和摆盘标准的菜谱。技能可以在不改动主提示词的情况下反复调用，还能跨项目共享，这一点看起来没什么，实际解决了“每次都要重新灌上下文”的老大难问题。
Matt Pocock 在聊技能设计时反复强调一个词：typesafe。他长期做 TypeScript 教育，习惯给变量定类型、给函数定边界，于是把同样的严谨带到了 AI 技能领域。一份写得到位的 SKILL.md，会明确告诉 AI：你负责什么、不负责什么、输入应该长什么样、输出按什么格式来。这等于给提示词加了一层“类型约束”，让 AI 不容易在自由发挥时跑偏。这个思路对我后续所有技能设计影响都特别大，完全可以当成第一原则来用。
1.2 为什么是 Matt Pocock 把这股风潮带到了主流
有人会质疑：Skills 又不是 Matt 发明的，为什么总提他。技能规范由 Anthropic 提出，后来 Codex、OpenCode 等生态也陆续跟上，这一点确凿。但把这些技术细节讲得最贴近开发者日常、最能让前端工程师快速上手的，Matt Pocock 的课程和开源仓库确实功不可没。他自己的背景是 TypeScript 教育，常年写高质量编程教学内容。当他把话题转向 AI 开发时，展示“怎么写一个技能的 SKILL.md”“技能里要不要放脚本”“技能怎么配合类型检查”，受众可以直接把这套东西用来解决 React 组件生成、单元测试编写、类型定义维护等日常任务。
从他的动手路线里，我学到的核心一点是：技能应该描述“能力”，而不是描述“命令”。比如不要写成“当用户说 VRTS 时执行 XXX”，而要写成“根据需求生成 Vite + React 项目骨架，包含组件目录、路由配置、TypeScript 类型声明”。前者是死板的命令，后者是有迁移能力的推理边界。这个差异，和过去那种几百条 if-else 型提示词相比，完全是两个时代的东西。
1.3 主流工具怎么组织 Skill 文件
先看支持情况。以我实际在用的 Claude Code 为例，它会在两类位置查找技能：用户级目录~/.claude/skills/，以及项目级目录.claude/skills/。Codex 生态里常见的路径是~/.codex/skills/，OpenCode 也能注册类似模式。社区包大多向 Claude 的 Agent Skills 规范对齐，所以同一份SKILL.md往往能在多个工具间复用。这个特点对安装很重要：从 GitHub 下载技能时，不要只盯着工具名字，先看目录里有没有SKILL.md，有的话大概率通用。
我把几个常用环境整理成了表格，方便对照：
| 工具 | 用户级目录 | 项目级目录 | 说明 |
|---|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ | 技能规范事实标准，支持资源目录 |
| Codex | ~/.codex/skills/ | .codex/skills/ | 社区包大多兼容 Agent Skills 格式 |
| OpenCode | 通过配置文件注册 | 项目配置 | 部分版本支持直接读取 SKILL.md |
其实不用死记路径，只要记住“技能是目录加 SKILL.md”就够了。接下来的安装步骤，我会以 Claude Code 为例，其他工具替换路径前缀就行。
2. 安装落地：手动装配 GitHub 上的 Skill
2.1 用户级目录与项目级目录怎么选
动手安装之前，先决定放哪。用户级目录适合每天都要用的通用技能，比如写周报、生成代码注释、整理 commit message；项目级目录适合和业务强绑定的技能，比如某个后端框架的代码生成规则、某条数据管道的检查步骤。全局目录的优点是随手可用，缺点也很明显：技能太多时，AI 每次做意图匹配都要扫一圈，响应时长和上下文占用都会增加。项目级目录只在特定仓库生效，干净精准。
我的建议是：工作里能反复使用的基础能力，统统放全局；跟着某个项目生命周期走的，放项目里。团队协作时，项目级技能随仓库一起被克隆，天然适合做团队规范，比如“本项目的代码风格要求”和“提交 PR 前的自检清单”。这里有个注意点：在 Claude Code 中，项目规则真正对成员生效的通常是 AGENTS.md，Skills 的定位是“对话里可以被主动调用的能力”，两者不要混成一个文件，否则职责会乱。
2.2 手动安装的标准流程
先从 GitHub 找到技能仓库。常见做法是在 GitHub 上搜关键词加skills，比如awesome-claude-skills、superpower skills、mathematical modeling skills。找到仓库后，不要把整个仓库直接扔进技能目录，而是先看清目录结构，把包含SKILL.md的某个文件夹复制进去。标准流程是这样的：
# 1. 克隆仓库到临时位置 git clone https://github.com/example/skills-repo.git cd skills-repo # 2. 确认技能目录里确实有 SKILL.md find . -name "SKILL.md" -maxdepth 3 # 3. 创建用户级技能目录（若不存在） mkdir -p ~/.claude/skills # 4. 把目标技能整个目录复制进去 cp -r skills/weekly-report ~/.claude/skills/cp复制的是“整个技能目录”，因为SKILL.md旁边可能挂着 assets 或 scripts，缺了文件技能就用不全。装完以后，重新打开交互对话，或者在会话里输入技能列表命令（比如 Claude Code 的/skills），确认能看到新技能。如果列表里没有，大概率是 frontmatter 写错了，或者描述字段没有被正确读取，排查方法放到第 5 章详细说。
2.3 用符号链接维护一套技能库
手动复制最大的坑是版本管理。今天复制一份，明天仓库更新，你又得重新下载。我自己坚持的做法是建一个技能库 Git 仓库，统一维护所有技能，然后用符号链接把技能指到 Claude Code 的目录：
# 把技能库克隆到本地开发目录 git clone https://github.com/my-hand/skills.git ~/dev/skills # 建立软链接，相当于把技能“挂载”进来 ln -s ~/dev/skills/weekly-report ~/.claude/skills/weekly-report符号链接的好处是：修改源代码就等于修改生效文件，不需要来回复制；技能仓库里还能放 README、更新日志和测试脚本。多人团队把技能库接到一个仓库，成员各自建立软链，所有技能更新只需要一次 pull。缺点则是系统重装后链接容易失效，所以我会放一个install.sh脚本，把需要链接的技能一次性建好，避免手工维护一堆软链。每次重装新环境，跑一遍脚本就能恢复整套技能栈，非常省事。
2.4 装完怎么验证与触发
验证是否生效有两个维度。第一，打开工具自带的技能列表，能看到技能名称，说明目录结构没问题。第二，用一个贴近描述的真实问题去触发。比如装好的技能描述是“生成结构化周报”，那么直接对它说“根据我下面的记录写一份本周周报”，观察 AI 是否主动采用技能里的规则。如果 AI 总是忽略，不一定代表没装上，更多是 description 和实际触发场景不匹配。
这里还要提醒一句，测试时不要用“帮我干点活”“你好”这种抽象表述。意图模糊的时候，AI 不应该也不可能把某个特定技能翻出来。给对方一个清晰场景，顺便也能检验自己写的 description 是否合格。毕竟技能描述的本质，就是告诉 AI“这个功能什么时候拿出来用”。
3. 从零写一个自己的 Skill：周报助手实战
3.1 SKILL.md 的骨架与核心字段
写技能踩过最深的一个坑，是以为SKILL.md就是一篇自由发挥的 Markdown。实际上它前半部分必须带 YAML frontmatter，至少得包含name和description两个字段；更完善的技能还会定义allowed-tools，声明允许调用的工具。人手一份技能时，这几个点一定要盯住：
name：技能的唯一标识，一般用小写加短横线，比如weekly-report。description：一行到几行的摘要，AI 用它决定何时调用技能。必须说清楚“什么场景用、解决什么问题”，最好把触发条件和上下文限制一起写进去。- 正文部分：以
# 技能名开头的 Markdown 说明，里面是执行步骤、输入输出格式和错误处理方式。 - 可选目录：
assets/放静态材料，scripts/放辅助脚本。
用代码视角来比喻：name是函数名，description是 JSDoc，正文是函数体，assets和scripts是外部引用模块。你的任务就是花最小成本，让模型遇到真实问题时能稳稳调用这个“函数”。
3.2 一个可以直接照抄的周报 Skill 示例
我自己写了不少技能，最好上手的就是周报生成器。完整文件如下。
--- name: weekly-report description: 当用户提供本周工作要点，或要求生成周报时使用。尤其适合团队周报场景，输入可以是零散的工作记录。 --- # 周报生成器 你是行政助理。请按照以下规则处理用户的工作记录： 1. 将内容分为“本周完成”“下周计划”“风险与求助”三块。 2. 每条事项以动词开头，概括为一个短句。 3. 对信息不足的地方，主动向用户提问，不要自行编造。 4. 最终输出 Markdown 格式，标题为《XX 周周报》。保存路径是~/.claude/skills/weekly-report/SKILL.md。这个文件非常简短，但已经具备完整触发链路：用户说“写周报”，description让它被识别，正文约束输出格式。我实测过，哪怕把当周记录写得极散，它也会按三块结构整理，不会反问“你想写什么风格”。这就是技能的确定性来源。
真实业务会比这复杂得多。比如希望它读 Git 提交记录，那就要在正文里写“当用户没有提供内容时，默认执行git log --since=\"7 days\"获取最近提交，再整理成周报”，同时配上scripts/目录下的可执行脚本。技能的核心价值，是把重复流程固化，而不是指望每次对话重新交代一遍。
3.3 进阶结构：规范、脚本与资源
当技能需要处理文件时，就得用上资源目录。比如给一批图片统一缩放，或者解析一份 PDF，规律非常明确：在SKILL.md正文里描述“要调用哪个脚本、传什么参数、输出放哪里”，脚本本身放在scripts/下面，模型会按说明去做。
假设技能里带一个scripts/parse_logs.py，正文可以写成：
# 日志解析技能 当用户提供日志文件时： 1. 调用 `python scripts/parse_logs.py <input.log>` 2. 脚本会输出 `summary.json` 3. 基于 summary.json 生成人话版分析报告写这种正文，步骤应该从用户可见的目标出发，而不是描述底层实现细节。AI 擅长推理，它只需要知道目标和标准，具体执行顺序会在运行时根据环境自动调整。写太多“必须怎么做”反而会让它在环境变化时卡死。
3.4 调试与迭代：让 description 更会“接客”
调试技能七成功夫都在description上。如果技能一直不触发，先别怀疑工具坏了，试试改描述：把使用场景前置，把适用对象写具体。比如不要写“这是处理日志的”，而要写“当用户提供一个或多个日志文件，需要清洗、查错或生成摘要时，使用本技能”。AI 做的是意图匹配，描述越接近真实用户话术，命中率越高。
还要养成一个多轮迭代的习惯：观察 AI 的行为，如果用了技能但输出不合预期，就去改正文；如果压根不用，就去改description。不要一次同时改两处，否则既无法定位问题，也分辨不出哪次改动起了效果。这个方法特别笨，但非常管用，每次写新技能我都会用它来逼近理想状态。
4. 场景化实践：数学建模、AI 漫剧与前端开发
4.1 数学建模比赛里的 Skills 配置思路
先说一个典型场景：华为杯这类建模比赛。比赛时间紧，参赛者往往要在有限时间内完成问题分析、模型建立、代码求解和论文排版。如果把解题流程设计成技能包，效率会高很多。常见的数学建模 skills 有几块内容：对题目做结构化拆解的模板、常用算法的 Python 代码脚手架（比如线性规划、插值、神经网络），以及论文写作和公式排版规范。
以 Codex 为例，可以在它的技能目录里放一个math-modeling技能，正文写明“拿到赛题后先输出问题背景、约束条件、评价指标，再按数据情况推荐模型，最后调用脚本生成报告图表”。这样每次进比赛，不用反复粘贴背景知识，模型也能用统一套路快速进入状态。不过有一点必须提醒：比赛要求参赛者真正理解模型，技能只能帮你更快地整理信息和生成模板，不能替代你对模型合理性的判断。这个边界写不写进技能都行，但心里要清楚。
4.2 AI 漫剧和短视频团队怎么组合技能
再来看一个和“打代码”离得比较远的场景：AI 漫剧，也就是用 AI 生成漫画分镜、角色立绘、语音和剪辑的短视频项目。这类项目同样能用 skills 管理。团队可以把“角色一致性设定”“分镜脚本生成”“配音提示词”“后期检查清单”分别做成技能，放在项目级目录里。需要哪一步，就让 AI 调用哪一个，而不是让一个大模型一口气干完所有事。
我见过比较有效的做法是：把角色外貌描述放在assets/role.yaml里，把画面风格规范写在SKILL.md正文中，分镜脚本技能读取这两个文件后统一生成，这样每集人物形象不容易崩。这里体现的核心思想还是职责单一：一个技能只做一件事，描述越窄，越不容易被误触发，也越容易在团队内部维护。
4.3 常用技能源：GitHub 仓库、Awesome 清单与网页版
关于“去哪找技能”，我现在常用的渠道有三类。第一类是 GitHub 的集合仓库，搜awesome-claude-skills或typesafe-ai skills能看到大量社区维护列表。第二类就是直接打包好的技能仓库，比如你可能见过的 Superpowers 相关项目，复制进技能目录就能用。第三类是部分平台做出来的网页版技能市场，能在线搜索、一键复制指令，适合不太习惯命令行的人快速上手。
但网上搜到的信息需要甄别。知名作者和高 Star 仓库通常更有质量保证，但小仓库也可能正好解决你的特定需求。我下载前必看两样东西：SKILL.md的 frontmatter 是不是规范，正文里有没有诱导执行危险命令的语言。技能本质上是可执行的指令包，把不可信的技能装进全局目录，等于给工具开了一扇不小的权限口，这一点放在第 5 章还会展开。
4.4 清理方法论：技能真的越多越好吗
网上 tibo 这类博主分享的清理方法里，“定期删技能”几乎是核心建议。我刚入坑时攒了几十个技能，结果发现 AI 经常匹配到错误的技能，上下文也被消耗得很厉害。后来我总结出一套自己的清理流程：季度检查使用记录，找出从未被触发的技能；按场景分类，只保留描述清晰、职责单一的那些；不常用的技能先挪到~/.claude/skills_archive/这种归档目录而不是直接删除，确认两轮都没用到之后再彻底清理。
清理技能还有个附带好处：逼自己维护一份精简的技能清单。每次想新增技能，我都会先问一句“这是不是全局技能？能不能和现有技能合并？”几十个技能最后被压缩到十几个以内，AI 的匹配准确率反而大幅上升。这大概就是老手常说的“技能数量不是重点，维护才是”。
5. 常见问题与排查技巧实录
5.1 装好了却不触发，问题出在哪
这是出现频率最高的问题。先确认技能确实能在技能列表里看到，再模拟真实意图的对话。如果还是不触发，最常见的两个原因是：描述字段写得太抽象，或者当前对话里有其他更强势的指令覆盖了它。我曾经给一个分析销售数据的技能起名analyst，description 只写了一句“进行高级分析”，结果死活不触发；改成“当用户要求分析 Excel 表格里的销售数据并输出图表时”后，一测一个准。描述具体、具体、再具体，是触发问题的唯一解。
另外，手动安装后一定要把会话重启一遍或重新加载技能。大多数工具在启动时扫描技能目录，如果你在会话中途把文件复制进去，它是不会热更新的。这不算 Bug，是扫描机制决定的。装完新技能后顺手列一下技能列表，确认路径正确，能省掉后面很多无意义的排查时间。
5.2 同名冲突与优先级判断
当系统级和项目级存在同名技能时，多数工具会让更具体的作用域覆盖全局作用域。这里最容易出现的问题：你在全局装了一个通用周报技能，项目里又有一个定制版，结果某天发现 AI 执行了通用版，输出不符合项目要求。与其依赖优先级规则，不如在起名时就避免冲突，比如项目级技能加项目缩写前缀，project-weekly-report这种命名方式最省心。
同时，日常使用也建议不要同时开太多技能。目标越精确，给模型预装的技能越少越好。临时任务第一次用可以让 AI 自己匹配，但如果发现某项工作反反复复被用到，就值得把它固定成正式技能，纳入目录管理。
5.3 安全边界：提示注入、脚本权限与审查
这一段想讲得稍微严肃一点。技能本质上是可执行的指令包，所以最坏情况下，一个恶意技能可能引导 AI 执行高权限操作。下载技能前要像审视依赖库一样审视它：看 frontmatter 是不是只有name和description，看正文有没有“忽略之前指令”“关闭安全限制”“执行来源不明的 shell 命令”这类危险描述，别轻信陌生人给的安装脚本。
在团队里，如果技能库允许成员提交，建议设置 review 环节，至少保证每个人知道自己提交的是什么。还有一点必须强调：不要把 API 密钥直接写进技能文件或 assets 里，密钥应该从环境变量或密钥管理工具加载，SKILL.md里只写参数名。这条细节能帮你避免把秘密随仓库一起发布的风险，吃亏过的人会懂。
最后说句掏心窝的话：把所有技能从“随手抄”变成“自己维护”之后，我对 AI 工具的信任才算真正建立。以前像在和一个记性不好的实习生对话，现在更像给一个执行力很强的同事下发标准化手册。Skills 的坑其实不多，路径搞对、描述写清、定期清理、注意安全，这四件事做到，用起来的体验就会顺很多。希望这篇指南里的实操细节，能帮你少走我走过的那些弯路。
