先说个我最近的真实感触过去一年里我调模型的方式变了很多。以前拿到一个任务第一反应是“怎么把 prompt 写得再长一点、再细一点”后来发现提示词写一万个字模型该不会的还是不会——它只是听懂了你在说什么并不知道该怎么一步步把事做完。直到我开始系统性接触 Agent Skills 这套思路之后一个很明显的转变是我不再“教模型说人话”而是直接给模型一套可以执行的工具流和方法论。项目标题里的“skills”不是什么玄学也不是单纯的“能力提升清单”而是大模型编程和智能体时代里一个正在快速成为标配的工程单元把高频任务沉淀成可复用的技能包让模型拿到任务后直接调用而不是每次从零开始摸索。这篇文章想把这件事讲透skills 到底是什么、为什么现在所有主流 Agent 工程都在往这个方向走、一个合格的技能包长什么样以及怎么从零开发、安装、调试一套自己的 skills。我会尽量用自己的实操过程说明白而不是甩概念。适合正在用 Claude Code、Codex、OpenCode 这类工具做开发或者想把自己手里的重复性工作“技能化”的人参考。1. 项目整体设计与思路拆解1.1 “skills”到底是什么不是提示词而是一个可执行的工作单元先做个比喻。普通 prompt 相当于你给实习生口头交代了一句“把这个表格整理好”实习生怎么做、按什么标准做、遇到格式问题怎么办全靠他自己的悟性。而 skills 相当于你直接甩给他一本 SOP 手册里面写了整理表格的每一步流程、用什么工具、输出成什么格式、中间遇到异常怎么兜底。模型拿到 skill 之后不是在“理解”你的意图而是在“执行”一套已经被验证过的方法论。所以核心差异在于prompt 是指令skills 是能力封装。一个 skill 往往包含一套规定好的目录结构里面既有给模型读的指导文档通常叫 SKILL.md 或类似命名也有可以直接执行的小脚本、参考模板、示例数据。模型在对话中一旦判断当前任务命中了某个 skill 的描述范围就会自动把这个技能包“加载”进来按里面的流程走而不是自由发挥。这就能解释为什么“superpower skills”“mattpocook skills”这些开源仓库会火——它们本质上不是一堆提示词模板而是把“如何做技术方案评审”“如何做代码重构”“如何做流程图绘制”这类高频动作固化成了模型可以反复调用、一致性极高的技能模块。你装上之后相当于给模型加了一堆“职业技能证书”它遇到对应场景就知道按专业套路出牌。1.2 为什么提示词正在让位给技能包从“说清楚”到“教它做”我这两年最深的体会是模型的上下文窗口再大也扛不住你把所有方法论塞进一次对话里。如果每次任务都要在 prompt 里把行业规范、操作步骤、输出格式写一遍第一是 prompt 本身会变得巨长浪费 token第二是模型很容易“记了后面忘前面”尤其是步骤一多、规则一细执行起来就开始走样。skills 解决的正是这个问题把方法论从上下文里剥离出来沉淀成独立文件。模型需要的时候再去读不需要的时候完全不占用上下文而且同一套方法论可以被反复加载保证每次执行的标准一致。说白了这是把“经验”变成了“代码资产”而不是靠聊天记录维系。另外还有一个很现实的点提示词是“私有”的很难分享。你写了一个特别牛的 prompt发到群里别人复制过去效果可能大打折扣因为每个人对话时的状态、模型版本、上下文都不一样。但技能包不一样它自带完整目录、脚本和说明只要是同一套 Agent 工具装上去就能复现相同能力。这也是为什么 GitHub 上 skills 仓库的 star 涨得飞快——因为它们天然适合做开源生态。1.3 主流生态盘点不同 Agent 里的 skills 有什么差异现在几乎每个主流 Agent 编程工具都在做自己的技能体系但底层逻辑是相通的目录 描述文件 可执行资源。我用下来几个热门的生态差异主要在于安装方式和可自定义程度工具技能目录默认位置安装方式特点Claude Code~/.claude/skills/手动放置或npx skills add生态起步早社区仓库多对 workflow 类技能支持好Codex~/.codex/skills/手动放置或对应 CLI 命令偏代码生成与仓库分析适合做工程类技能OpenCode项目级.opencode/skills/手动放置轻量灵活适合把技能跟仓库绑定Cursor / Windsurf插件或项目级目录插件市场或手动更偏向编辑器内交互对 UI 操作类技能友好就我自己的使用习惯来说如果只是日常编码分析Claude Code 的 skills 体系最成熟如果是要在开源项目里共享技能包用仓库目录方式比如.claude/skills跟着项目走是最不容易踩坑的选择因为技能跟代码放在一起人换了、机器换了也不会丢。2. 技能包的核心结构与实操细节2.1 一个标准技能包的目录长什么样如果你没打开过真实的 skills 仓库很容易以为它就是一个 Markdown 文件。实际上一个合格技能包的目录结构大致是这样的my-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_structure.py │ └── analyze.py ├── assets/ │ ├── template_report.md │ └── example.json └── requirements.txt其中 SKILL.md 是技能包的大脑scripts 里放的是可执行脚本assets 里是参考素材。之所以建议这样拆是因为模型在大多数情况下只需要先读 SKILL.md 就能判断“这个技能适不适用于当前任务”只有当确定要执行时才去调用脚本和模板这样既省 token 又保证响应快。SKILL.md 本身的格式业内比较通行的做法是带 YAML frontmatter--- name: structure-diagram description: 根据用户提供的文档或代码仓库生成结构化的架构图/思维导图。仅在用户需要梳理结构、画图时使用。 ---name 字段是技能的唯一标识description 字段是模型判断“要不要调用这个技能”的核心依据。很多人写 description 时容易写得特别宽泛比如“帮助用户解决各种问题”这等于没写。好的描述应该包含触发场景、使用条件和明显的排除条件。2.2 SKILL.md 正文怎么写才能让模型真正执行正文部分是技能的“操作手册”可以分为几个小节先讲前置条件再讲操作步骤最后给一个可参考的输入输出示例。我常用的一个模板结构是目标说明这个技能用来完成什么任务产出什么结果。前置检查执行前需要确认哪些信息缺了怎么办。执行步骤按序号彻底写明每一步操作不要省略中间的判断逻辑。输出格式明确最终交付物的格式比如 Markdown 报告、JSON 文件或代码仓库结构。示例给一个完整的输入到输出示例模型会照着这个示例调整自己的执行方式。这里有个实操细节不要只在文档里写“自动生成图表”这种命令式描述而要写“先读取输入文件的目录结构提取主要模块再按模块关系输出为 mermaid 代码块最后整理成层级清单”。模型对“具体怎么做”的遵循程度远高于对“结果是什么”的遵循程度。每一步越细执行偏差越小。2.3 脚本与资源给模型装上一双“能干活的手”很多 skill 牛逼的地方不只是文档写得好而是配套脚本真的能落地执行。比如一个“代码仓库分析”技能SKILL.md 只负责告诉模型分析思路真正统计函数数量、圈复杂度、依赖关系的工作则由 scripts/analyze.py 完成。模型只需运行脚本、读输出结果再结合 SKILL.md 里的分析框架生成报告。这种“文档决策 脚本执行”的组合就是我理解中“superpower skills”特别像超能力的原因模型本身不能直接数代码行数但给它一个 Python 脚本它就能瞬间完成数万行代码的统计和分析。技能包本质上是在给模型扩展感知和操作能力而不是仅仅教它思考。写脚本时有三点建议。第一脚本入口最好用命令行参数接收输入路径避免硬编码第二脚本输出尽量用 JSON 或结构化文本方便模型直接读取引用第三如果是 Python 脚本在 requirements.txt 里固定依赖版本避免不同环境执行结果不一致。2.4 技能的安装与激活让 Agent 知道“什么时候拿出来用”技能的安装方式因工具而异但原则上有两种一种是放到全局用户目录比如 Claude Code 的~/.claude/skills/这样所有项目都能用另一种是放到项目目录下的隐藏文件夹里比如.claude/skills/这样只有进入这个项目才会激活相关技能。用全局目录还是项目目录取决于技能的通用程度。像“生成流程图”“做代码审查”这类通用技能放全局目录比较省事像“处理本公司特定数据格式”“梳理某个老项目的模块关系”这类强项目绑定的技能放项目目录更合理避免其他项目误触发。安装命令方面社区比较流行的是通过npx skills add 作者名/仓库名的方式一键安装比如npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这样的命令-g表示全局安装-y表示跳过确认。如果某个仓库不支持 npx 方式也可以直接git clone之后手动把目录复制到技能目录下两种方式本质一样区别只是自动 vs 手动。这里要提醒一个我踩过的坑安装后如果发现模型完全无视新装的技能首先检查目录层级是不是多套了一层。很多仓库 clone 下来之后是skills/xxx/SKILL.md结构你要把xxx这个技能目录整体复制到技能根目录而不是把skills整个文件夹复制过去。目录层级不对Agent 是识别不到技能的。3. 从零开发并发布一个自己的技能包3.1 选题什么样的任务值得被做成技能不是所有任务都值得做技能包太简单的不需要太复杂的又不好固化。我一般用三个标准衡量第一这个任务你或你的团队每周都会遇到至少一次第二任务的执行流程相对稳定中间步骤可标准化第三任务里有一部分“机械性操作”可以交给脚本比如读取文件、统计结果、生成模板。举个例子我最近做了一个“技术方案评审”技能。触发场景是每次开完需求会都要对新方案做一轮完整的评估。以前这个工作全靠人肉整理后来我把评估流程固化成了技能先读取方案文档再按架构、性能、安全、可维护性四个维度逐项打分最后生成统一格式的评审报告报告里附上风险项和改进建议。实测下来一个完整方案从阅读到产出报告从原来的半小时缩短到了三分钟而且格式比我自己手写的还统一。3.2 动手写 SKILL.md一个可直接复用的示例直接上一份我实际用过的 SKILL.md 示例目标是“生成文档结构图”--- name: doc-structure-diagram description: 根据项目文档或代码目录生成结构层次的思维导图或架构图。适合用户要求梳理文档/目录结构、画出模块关系图时使用。 --- # 文档结构图生成指南 ## 目标 根据输入的项目路径或文档说明生成一份清晰的层级结构图。 ## 前置检查 1. 确认输入的是一个目录路径或明确的文档清单。 2. 如果输入不明确先询问用户需要梳理的范围。 3. 确认输出格式偏好mermaid、markdown 列表、或图片。 ## 执行步骤 1. 读取指定目录下的所有文件和子目录忽略 .git、node_modules、dist 等依赖目录。 2. 按模块或功能对文件进行分组不按物理路径机械展示。 3. 将分组结果整理为层级树第一层是模块名第二层是子模块第三层是关键文件。 4. 生成 mermaid 代码块格式的 graph TD 图。 5. 如果用户需要再输出一份可复制的 Markdown 层级清单。 ## 输出格式 - mermaid 图以 mermaid 代码块包裹。 - 层级清单使用嵌套无序列表。 ## 示例 输入docs/ 目录 输出 mermaid graph TD A[docs] -- B[架构设计] A -- C[接口文档] B -- D[模块划分.md] C -- E[API列表.md]注意看这里的写法我刻意把“忽略哪些目录”“按什么逻辑分组”“输出成什么格式”都写死了模型执行时不需要自己判断只要跟着流程走就行。这也是技能包和普通 prompt 最大的区别——它把不确定的“意图理解”变成了确定的“流程执行”。 ### 3.3 配套脚本让技能真的能“跑起来” 拿生成结构图这个技能来说如果只靠 SKILL.md模型还是需要自己想办法列目录虽然能完成但在目录很大时容易漏文件。所以我写了一个 Python 脚本做目录扫描 python #!/usr/bin/env python3 import os import sys import json IGNORE_DIRS {.git, node_modules, dist, __pycache__, .next, .venv} def scan(path, prefix, depth0, max_depth5): results [] if depth max_depth: return results try: entries sorted(os.listdir(path)) except PermissionError: return results for entry in entries: full os.path.join(path, entry) if entry in IGNORE_DIRS: continue if os.path.isdir(full): results.append({ name: entry, type: dir, path: full, children: scan(full, depthdepth1) }) else: results.append({name: entry, type: file, path: full}) return results if __name__ __main__: root sys.argv[1] if len(sys.argv) 1 else . output scan(root) print(json.dumps(output, ensure_asciiFalse, indent2))这个脚本输出的是 JSON模型拿到之后可以直接读取再按 SKILL.md 的分析逻辑进行分组和画图。整个过程里模型负担最小重复劳动全部交给脚本即使目录里有上千个文件也能在几秒内扫描完成。这也是我推荐“脚本能干的绝不靠模型生啃”的原因稳定性和速度都高一个量级。3.4 本地调试与发布如何确认技能被正确加载开发完技能后第一件事不是发布而是本地验证。我的习惯是先把技能目录复制到对应工具的全局技能目录然后故意触发一个匹配描述的任务观察模型输出里有没有出现技能相关内容比如它主动读取了 SKILL.md或者脚本被真实调用。实际调试中比较头疼的一类问题是“技能装上了但模型就是不调用”大概率是 description 写得不够具体。比如你写“用于生成结构图”模型遇到用户说“帮我画一下我的项目架构”不一定会联想到这个技能。但如果 description 写成“根据项目文档或代码目录生成结构层次的思维导图或架构图。适合用户要求梳理文档/目录结构、画出模块关系图时使用”命中率就高很多。description 里的触发词要和用户真实表达常见的说法对齐这一点值得反复打磨。发布方面目前最常用的方式是推到 GitHub 仓库然后用npx skills add 你的用户名/仓库名让别人安装。如果你希望技能被更多人搜到仓库根目录要放一份清晰的 README说明技能用途、适用场景、目录结构并截图展示使用前后的效果对比。社区里的好技能包往往还有一个共同特征附上了至少一个实际案例的执行过程这比任何宣传都有说服力。4. 好用的 skills 清单与实践组合4.1 高频推荐的 skills 一览这段时间我陆陆续续试了不少社区里的技能包有些确实称得上“装完回不去”。整理一个简化版的清单按使用频率排序技能包适用场景推荐指数代码仓库分析快速了解陌生项目输出模块划分与依赖关系强烈推荐流程图 / 结构图生成把文档、目录、流程转成可视化图表强烈推荐技术方案评审按多维度评估设计文档并生成评审报告推荐代码审查自动检查 PR 中的潜在问题输出审查意见推荐前端组件文档生成为组件库批量生成说明文档值得一试数据分析报告读取 CSV/表格输出带图表的数据解读值得一试专利交底书初稿从技术方案描述生成交底书框架特定人群适用这些技能包大多不需要额外配置装上即可用但要注意一点不同的技能包之间可能有功能重叠比如“代码仓库分析”和“代码审查”都会读项目代码装多了之后模型可能搞不清该用哪个。我现在的处理方法是只保留一个“主力技能”覆盖同一类需求减少冲突。4.2 组合实践把多个技能串成一条流水线单个技能能解决单点问题但真正体现 skills 威力的是把它们组合起来。举个例子我处理一个陌生的前端项目时会依次做三件事先用“代码仓库分析”技能摸清整体结构再用“流程图画图”技能把关键模块的调用关系画出来最后用“技术方案评审”技能对当前架构做一轮诊断。这么做的好处是每个技能只专注自己最擅长的事模型不需要在一个技能里塞太多目标执行质量会稳定很多。而且技能和技能之间通过结构化文本衔接——分析技能输出 JSON画图技能读取 JSON 画图评审技能读取画图结果和报告模板生成结论——形成了一条完整的数据流。这套组合实践给我的感觉和“大模型 skills harness 深入理解”里提到的思路很像技能不只是单独的原子操作而是要纳入一个统一的调度框架里让 Agent 根据任务自动编排调用顺序。你不用自己在 prompt 里写“先做 A 再做 B”只要把每个技能的 description 写清楚模型在推理时会自动选择合适的技能序列。4.3 技能选择的避坑建议与安全提醒社区里 skills 质量参差不齐选型时我自己的几条原则提供给你参考优先选带脚本的技能纯文档型技能离“可执行”还差口气。看仓库的更新时间和 issue 反馈超过半年没更新的技能很可能已经不适配最新工具版本。先装到一个临时项目里测试确认没问题再放到全局目录。注意技能包的权限有些技能脚本需要执行 shell 命令或访问外部 API安装前扫一眼代码避免给出过高的系统权限。安全方面尤其值得多说一句第三方技能包本质上是一段可执行的代码它被模型调用时是以你的权限运行的。安装来源不明的技能前至少检查一下 scripts 目录里有没有可疑的文件下载、环境变量读取或网络请求逻辑。我一般只在知名作者或高 star 仓库里选择技能包并且定期清理不再使用的技能尽量缩小攻击面。5. 常见问题与排查技巧实录5.1 技能不生效的六大原因技能不生效是新手最容易遇到也最挫败的问题我整理了一张速查表基本都是我踩过的坑症状常见原因解决办法模型完全无视技能描述与用户表达不匹配重写 description加入更多触发词技能装了但反复报错目录层级多套了一层检查技能目录下是否直接就是 SKILL.md脚本运行失败缺少 Python 依赖或 Node 依赖按 skills 自带 requirements.txt 安装依赖每次结果都不一致SKILL.md 步骤不够精细把判断逻辑写成明确的条件分支多个技能相互干扰功能重叠模型选错技能精简技能数量只保留最精准的系统权限不足技能目录放在无权限位置检查目录所有者与读写权限其中目录层级问题出现频率最高我猜是因为很多 GitHub 仓库为了方便展示会把技能统一放在skills/子目录下而安装工具复制时容易搞混。判断方法很简单打开技能目录里面第一层应该是SKILL.md如果看到的是skills/SKILL.md这种结构那一定是多套了一层。5.2 描述不触发与上下文过长的处理心得除了技术性故障技能使用还有两个经常被忽略的调优点一个是描述触发一个是上下文优化。描述触发的问题本质上是“模型怎么判断该不该调用技能”。不要指望模型会主动探索你的技能库它只会根据当前对话和用户意图机械地对比每个技能的 description。所以排查这类问题时把用户原话复制下来放到技能的 description 里看看能不能自然匹配上匹配不上就去改描述而不是去改模型。上下文优化的问题也很典型。技能包加载后SKILL.md 全文会进入模型上下文如果技能文档写得又臭又长反而挤占其他信息的空间。我的经验是 SKILL.md 控制在一千五百字以内把细节尽量放到脚本和 assets 里让模型“按需阅读”而不是“全量背诵”。5.3 踩坑实录一次完整的排查过程记录一次最近的实战排查能帮你更好理解上面这些点。有次我在 Claude Code 里装了某个做数据分析的技能包结果无论怎么问模型都只用普通对话回答完全不触发技能。我先确认了技能目录结构没问题又检查了依赖也齐全排除了环境问题。最后翻开发布者的仓库发现这个技能包最新版本要求的 Agent 版本比我现在的高而更高版本里技能激活机制改成了“当用户明确提到统计、图表等词时才触发”。我升级工具版本后重新测试技能就正常出来了。这件事给我两个启发一是技能包和工具版本之间是有耦合的旧工具跑新技能经常有兼容性问题二是排查问题时别只盯着技能本身多看看工具更新日志。现在很多 Agent 工具迭代得非常快一个月前的技能激活机制一个月后可能就变了。写在最后的个人体会做了这么多技能包之后我最大的感受是skills 这个概念把一个很朴素的想法变成了工程现实——把经验沉淀下来让机器替你执行。以前写技术博客、写文档本质是把经验留给“人”看而技能包把经验写成了“模型”能直接执行的格式这是种完全不同的表达方式更像是在培训一个永不疲倦的实习生。现在我自己处理重复性任务时已经很少写“一次性 prompt”了基本都是打开终端安装或调用对应的技能包让 Agent 按部就班地完成任务。有时候想想未来衡量一个工程师能力的重要标准可能不再是他自己多会写代码而是他能不能把自己的工作流程高效地封装成一套可复用的技能体系。如果你还没有动手做过自己的第一个技能包建议今天就挑一个每周都会遇到的琐碎任务花半小时把它固化成 SKILL.md你会很快感受到这种“把经验变成资产”的乐趣。