说实话我第一眼见“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 上的 Skill2.1 用户级目录与项目级目录怎么选动手安装之前先决定放哪。用户级目录适合每天都要用的通用技能比如写周报、生成代码注释、整理 commit message项目级目录适合和业务强绑定的技能比如某个后端框架的代码生成规则、某条数据管道的检查步骤。全局目录的优点是随手可用缺点也很明显技能太多时AI 每次做意图匹配都要扫一圈响应时长和上下文占用都会增加。项目级目录只在特定仓库生效干净精准。我的建议是工作里能反复使用的基础能力统统放全局跟着某个项目生命周期走的放项目里。团队协作时项目级技能随仓库一起被克隆天然适合做团队规范比如“本项目的代码风格要求”和“提交 PR 前的自检清单”。这里有个注意点在 Claude Code 中项目规则真正对成员生效的通常是 AGENTS.mdSkills 的定位是“对话里可以被主动调用的能力”两者不要混成一个文件否则职责会乱。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 装好了却不触发问题出在哪这是出现频率最高的问题。先确认技能确实能在技能列表里看到再模拟真实意图的对话。如果还是不触发最常见的两个原因是描述字段写得太抽象或者当前对话里有其他更强势的指令覆盖了它。我曾经给一个分析销售数据的技能起名analystdescription 只写了一句“进行高级分析”结果死活不触发改成“当用户要求分析 Excel 表格里的销售数据并输出图表时”后一测一个准。描述具体、具体、再具体是触发问题的唯一解。另外手动安装后一定要把会话重启一遍或重新加载技能。大多数工具在启动时扫描技能目录如果你在会话中途把文件复制进去它是不会热更新的。这不算 Bug是扫描机制决定的。装完新技能后顺手列一下技能列表确认路径正确能省掉后面很多无意义的排查时间。5.2 同名冲突与优先级判断当系统级和项目级存在同名技能时多数工具会让更具体的作用域覆盖全局作用域。这里最容易出现的问题你在全局装了一个通用周报技能项目里又有一个定制版结果某天发现 AI 执行了通用版输出不符合项目要求。与其依赖优先级规则不如在起名时就避免冲突比如项目级技能加项目缩写前缀project-weekly-report这种命名方式最省心。同时日常使用也建议不要同时开太多技能。目标越精确给模型预装的技能越少越好。临时任务第一次用可以让 AI 自己匹配但如果发现某项工作反反复复被用到就值得把它固定成正式技能纳入目录管理。5.3 安全边界提示注入、脚本权限与审查这一段想讲得稍微严肃一点。技能本质上是可执行的指令包所以最坏情况下一个恶意技能可能引导 AI 执行高权限操作。下载技能前要像审视依赖库一样审视它看 frontmatter 是不是只有name和description看正文有没有“忽略之前指令”“关闭安全限制”“执行来源不明的 shell 命令”这类危险描述别轻信陌生人给的安装脚本。在团队里如果技能库允许成员提交建议设置 review 环节至少保证每个人知道自己提交的是什么。还有一点必须强调不要把 API 密钥直接写进技能文件或 assets 里密钥应该从环境变量或密钥管理工具加载SKILL.md里只写参数名。这条细节能帮你避免把秘密随仓库一起发布的风险吃亏过的人会懂。最后说句掏心窝的话把所有技能从“随手抄”变成“自己维护”之后我对 AI 工具的信任才算真正建立。以前像在和一个记性不好的实习生对话现在更像给一个执行力很强的同事下发标准化手册。Skills 的坑其实不多路径搞对、描述写清、定期清理、注意安全这四件事做到用起来的体验就会顺很多。希望这篇指南里的实操细节能帮你少走我走过的那些弯路。