最近在折腾 Claude Code、Codex 还有 OpenClaw 这类 Agent 工具的时候我发现一个现象大家讨论的重心已经从“这个模型强不强”慢慢转移到“怎么让 Agent 稳定地帮我干活”上。而“Skill”这个词就是绕不开的下一站。Skill 说白了就是给 Agent 准备的一套“可复用技能包”——你告诉它某个任务该按什么流程做、需要哪些脚本和模板、中间要避开哪些坑它就能在下次遇到同类任务时直接调用而不是每次从头理解你的废话。而 Skill Creator字面意思是“技能创建器”但它不是某个单一软件的名字而是一类工作流和工具的总称可以由对话式 AI 生成也可以在 Agent 里自举式创建核心目标都一样——把人脑子里那些“我知道该怎么做”的经验翻译成 Agent 能读懂的标准化技能包。这篇文章我想用做技术方案的心态把 Skill Creator 从思想到落地拆个彻底包括我踩过的坑、测试过的方法、还有一份可以直接抄的实战案例。无论你是想给自己的 Claude Code 加两个顺手技能还是打算在团队里推广 Agent 提效这篇都能给你一套落地方案。1. 为什么需要 Skill Creator手写 Skill 的四个坑1.1 先聊清楚Skill 到底是什么你可能已经在不同的 Agent 工具里见过这个东西Claude Code 的 Skills、Codex 的 skill 插件、OpenClaw 的 skill 机制甚至 Spring AI 这类框架里也出现了 skill 的概念。名字一样底层思路也大同小异。一个标准化 Skill 包通常是这么个结构my-skill/ ├── SKILL.md # 技能说明书Agent 优先读这个 ├── scripts/ # 可执行的脚本、工具代码 └── assets/ # 模板、样例、静态资源其中 SKILL.md 是灵魂。它不是给你看的 README而是给 LLM 看的“操作手册”。一个合格的 SKILL.md 至少要写清楚三件事这个技能在什么场景下触发、执行时按什么步骤走、每一步的输入输出是什么。我在实际使用中最大的感受是Skill 不是“教 AI 一个新知识”而是“把稳定流程沉淀下来”。知识类和流程类要分开——知识类用普通上下文传一下就行流程类才值得做成 Skill。1.2 手写 Skill 的四个坑按理说这东西结构也不复杂直接手写 SKILL.md 貌似就行我最初也是这么干的结果连着踩了四个坑每一个都很浪费时间。第一个坑是“人话和机器话打架”。我自己写说明的时候下意识会用给同事看的口吻“把数据整理一下生成一个好看的报告”。这话人听得懂但 LLM 在解析时往往会自由发挥每次生成的格式都不一样。后来我才意识到SKILL.md 的每一句指令都应该有明确的动词、对象、判断标准比如“读取 scripts/collect_data.py 输出的 JSON 文件按 assets/report_template.md 的模板结构生成 Markdown 报告”。这不是写作文是写契约。第二个坑是“描述写得太泛或者太窄”。description 字段是 Agent 判断“要不要调用这个技能”的唯一依据。写得太泛Agent 把啥任务都往这个技能上套结果不匹配写得太窄又永远触发不了。这个平衡特别难拿捏我调整过的次数自己都数不清。第三个坑是“格式不对工具不认”。不同平台的 skill 格式虽然相似但细节上各有各的性格有的要求 front matter 里必须有 name有的要求 version有的对 SKILL.md 编码敏感。你在一套环境里写好换个工具就不加载排查半天发现是格式细节问题。第四个坑是“测试成本高”。一个技能写好了得反复起 Agent 会话验证效果每次都要重新加载上下文来回烧 token。没有一套系统化的测试方法光靠手动跑几次根本不知道稳不稳定。这四个坑叠加在一起就是为什么需要 Skill Creator 的核心原因它能把你脑袋里那套隐性的操作流程半自动地变成一份结构完整、格式合规、可以被反复调用的技能包。2. Skill Creator 的核心工作流从想法到技能包2.1 第一步需求解析说清楚“做什么、不做什么”无论你用哪种方式去做 Skill Creator后面我会具体讲几种第一步永远是需求解析。这一步的输入是你对某个任务的模糊描述输出是一份“技能边界说明书”。我现在习惯用一个固定的提示词框架来做这件事大概长这样我想创建一个 Skill功能是【一句话描述】。 - 输入用户会提供哪些信息 - 输出应该产出什么格式的结果 - 流程核心处理步骤有哪些 - 边界哪些情况不应该处理 - 依赖需要哪些外部工具/脚本别小看这个框架真是踩了多次坑之后总结出来的。以前我直接说“帮我做一个周报 skill”AI 给出来的东西五花八门因为它不知道我想要的周报是基于 git 提交记录还是基于禅道任务也不知道输出是 Markdown 还是 Excel。你先把上面的问题答一遍生成出来的 Skill 才是“你自己的技能”而不是一个通用模板。这一步还有两个细节值得注意。一是边界条件非常重要。比如你做“代码审查”的 skill你必须告诉它“只审逻辑问题不审格式问题”否则 Agent 会把 stylelint 该干的活也拦过来输出一堆噪音。二是依赖声明要前置。你打算让 skill 调用 Python 脚本就得说明运行环境是 Python 3.11、需要哪些第三方库。不写清楚的话Agent 在用户机器上跑脚本时会心一横直接 pip install 全局安装这绝对是灾难。2.2 第二步结构生成骨架比内容更重要需求聊清楚之后Skill Creator 要干的事就是把需求翻译成文件架构。这一步有点像程序员画类图先不管内部逻辑把目录、文件、职责边界先定下来。一个规范的技能包骨架至少包含三个部分SKILL.md技能说明文件通常带 YAML front matter后面接正文scripts/放可执行的脚本比如数据采集、文本处理、API 调用assets/放静态模板让输出格式保持稳定这里 Give 大家一个很关键的判断标准如果你的技能里包含“读取数据→处理→格式化输出”这种确定性操作那一定要拆出一个脚本来做而不是指望 Agent 在现场临场发挥。Agent 写代码的水平时高时低但已经封装好的脚本是稳定的你越少让 Agent“自由发挥”技能的稳定性越高。相反如果这个技能主要靠 LLM 的推理能力比如“分析这段代码的潜在 bug”那就别硬塞脚本老老实实写好 prompt 流程就行。一句话总结能脚本化的逻辑尽量脚本化纯推理类内容才留给模型。2.3 第三步内容填充与校验AI 帮你写的部分和你要检查的部分骨架出来之后填充内容是重头戏。当前的 Skill Creator 类工具不管是 ChatGPT 的对话生成、Claude 的 Project 里写、还是 Codex 的 skill 生成器都能帮你起草 SKILL.md 的正文、脚本逻辑、模板样例。但这里面有一条铁律AI 帮你初稿校验必须你自己来。我第一次用 Skill Creator 生成一个操作数据库的技能包时AI 生成的脚本逻辑正确率很高但有个问题——它没有考虑数据库连接失败时怎么办。结果 skill 上线之后一旦数据库连不上Agent 会卡在那儿反复重试日志刷屏用户体验极差。后来我的校验清单长这样front matter 里 name 是否全局唯一、description 是否精准正文步骤是否足够原子化每一步只做一件事不要一个步骤三件事每个步骤有没有明确的完成判断标准脚本有没有考虑异常分支和边界输入模板文件是否独立存放在 assets/ 而不是塞在正文里有没有注明“什么时候不应该使用本技能”这份清单我建议你直接存下来每次生成 skill 后逐条过一遍。说直白一点Skill Creator 是你的副驾驶但方向盘必须时刻在你手里。2.4 常见的 Skill Creator 形态选哪种看你的场景市面上能完成“Skill 创建”这件事的路径我实测下来主要有三种。第一种是“对话式生成”就是你开着 ChatGPT、Claude 这类通用对话工具用我上面给的那个提示词框架让它先出方案、再补细节。适合一次性创建少量技能用完即走不需要额外装任何东西。第二种是“Agent 自举式生成”这是我最喜欢的方式。比如你已经在用 Codex 或 Claude Code你可以直接让 Agent 读一下它自己的 skill 机制说明系统提示词里通常有然后命令它“帮我创建一个技能包结构按标准来功能是这样……”它会在工作区里直接生成目录和文件你只需要 review。这种方式的好处是 Agent 本身就是目标运行环境它对格式的理解不会跑偏生成的东西基本可以直接用。第三种是“项目模板式生成”适合团队批量生产技能。你先手工打造一个标杆 skill把目录结构、代码规范、描述风格定下来然后把这个标杆作为模板分发出去让团队成员用统一的模板去改。这个方式在维护统一性上最强但前期成本高。我的建议是个人用选第二种团队用选第三种偶尔用一次选第一种。别一上来就追求全自动先把流程跑通再说。3. 实战演示5 分钟做一个“周报生成”Skill3.1 需求定义先把这个技能说清楚光讲理论没意思我直接拿一个真实能用的案例走一遍全流程。这个案例是给研发团队做的“周报生成”技能目标很明确读取本周 git 提交记录按固定模板生成一份中文周报方便团队成员直接贴到公司周报系统里。打开你的代码仓库目录先跑一下我之前给的需求解析框架输入仓库路径、本周起止时间默认是最近 7 天输出一份 Markdown 周报包含本周完成、进行中、风险与阻塞、下周计划四个小节流程解析 git log → 按提交信息关键词分类 → 填充到模板边界不处理没有 git 仓库的目录不自动推送周报只生成文件依赖git 命令行、Python 3.9脚本用3.2 用 Agent 生成技能包实际操作记录我在 Claude Code 环境里直接输入了这样一段命令帮我创建一个 skill命名为 weekly-report。功能是读取当前 git 仓库最近 7 天的提交记录按模板生成中文周报。 - 存放在 .claude/skills/weekly-report/ 目录 - SKILL.md 里的 description 要能准确触发当用户提到“周报”“weekly report”“本周总结”时使用 - 需要一个 Python 脚本解析 git log按“fix/feat/refactor/test”等关键词分类提交 - 需要一个 Markdown 模板文件放在 assets/ 里 - 脚本要处理“本周没有提交”的边界情况Agent 花了几秒钟给出了完整结构然后自动写了 SKILL.md、脚本和模板。下面是对应的文件内容我把它精简后贴出来。SKILL.md 的 front matter 部分大概是这样的--- name: weekly-report description: 当用户需要生成周报、本周总结、weekly report、git 提交汇总时使用。 从当前 git 仓库读取最近 7 天提交记录按提交类型分类生成中文 Markdown 周报。 ---正文部分它会按步骤写清楚# weekly-report 使用说明 ## 触发条件 - 用户要求生成周报、本周总结、工作报告 - 用户提供时间范围如“过去三天”“本周一到现在” ## 执行步骤 1. 运行 python3 scripts/collect_git_stats.py --start 起始日期 --end 结束日期 2. 读取脚本输出的 JSON 结果检查 commits 数组是否为空 3. 若为空直接返回“本周无提交记录”不生成文件 4. 若不为空按类型字段分组填入 assets/weekly_template.md 对应小节 5. 在仓库根目录输出 WEEKLY_REPORT.md并告知用户文件路径3.3 脚本逻辑一个合格的“采集器”应该怎么写那个 collect_git_stats.py 脚本我后来反复改过几版核心逻辑其实不复杂#!/usr/bin/env python3 解析 git log 并按类型聚合提交信息。 import subprocess import json import argparse from collections import defaultdict def git_log(since, until): cmd [ git, log, f--since{since}, f--until{until}, --prettyformat:%s ] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: raise RuntimeError(fgit log 执行失败: {result.stderr}) return [line for line in result.stdout.splitlines() if line.strip()] def classify(message): prefix message.split(:)[0].strip().lower() mapping { feat: 本周完成, fix: 本周完成, refactor: 进行中, test: 进行中, docs: 进行中, } return mapping.get(prefix, 其他) def main(): parser argparse.ArgumentParser() parser.add_argument(--start, requiredTrue) parser.add_argument(--end, requiredTrue) args parser.parse_args() commits git_log(args.start, args.end) if not commits: print(json.dumps({commits: []}, ensure_asciiFalse)) return grouped defaultdict(list) for msg in commits: grouped[classify(msg)].append(msg) print(json.dumps({commits: grouped}, ensure_asciiFalse, indent2)) if __name__ __main__: main()注意几个细节脚本通过 stdin/stdout 和 Agent 通信输出是标准 JSON这样 Agent 后续怎么填充模板都不容易跑偏。错误处理也做了git log 失败不会静默吞掉而是把 stderr 抛给上层。脚本不写死日期而是接受参数传入——这是为了让 Skill 在不同场景下都能复用。这个脚本生成的过程Agent 几乎是一气呵成的。我后续只做了一处修改把分类逻辑从“按提交信息里的 emoji 分类”改成“按 prefix 冒号分类”。因为实际团队里没人写 emoji 提交都在用 Conventional Commits 风格我这个小团队也不例外。这个细节说明啥AI 生成的东西要贴近你自己团队的真实习惯不能拿来就用得做小调整。3.4 安装与实测验证这个 Skill 到底能不能干活接下来是把生成的技能包装进 Agent 里。不同工具位置不一样Claude Code 是放.claude/skills/目录Codex 这类也有自己约定但基本思路都一样一个技能包对应一个文件夹。装好后重启会话让新技能被索引然后用触发词测试帮我生成上周的周报时间范围 2024-03-11 到 2024-03-17。实测下来Agent 会在流程里自动找到并加载这个技能你会在它的输出里看到类似 loading skill 的提示然后调用脚本读取 JSON 结果最后按模板生成文件。整个过程大约十几秒比我手动去 git log 里扒记录再复制粘贴到周报系统效率翻了几倍不只。之后我又试了几个变体触发方式“这周干了啥给我整理个报告”“帮我拉下本周的 git 工作总结”都能稳定触发。如果你在测试时发现触发不了八成是 description 写得太窄了后面我会讲怎么调。4. Skill 和 Agent 到底有什么区别4.1 从“员工与工具箱”的比喻说起热榜上一直有人在问 skill 和 agent 的区别。我的理解其实一句话Agent 是执行主体Skill 是它手里可复用的“技能模块”和“操作手册”。你可以把 Agent 想象成一个新人员工他有理解指令、拆解任务、调用工具的能力但他不知道怎么把一件事干得又快又稳定——这些“干活的套路”就是 Skill。员工可以没有工具箱裸奔但效率和质量全看临场发挥你把标准操作流程写进工具箱他照着做就可以稳定输出。举一个更具体的例子一个“代码审查 Agent”负责审查 Pull Request 的全部环节。它需要有阅读理解代码的能力这是模型自带的需要能运行测试这是工具调用但它还需要知道按什么标准来审查这是技能包。你的团队规定“先看变更范围、再逐文件审逻辑、然后看有没有测试覆盖、最后再提意见”这套流程如果每次都靠让 Agent 临时猜那每次审查质量都看运气。放进 Skill 里它就是稳定可复用的底部流程。4.2 架构上的边界谁决策谁执行从架构上看Skill 和 Agent 的边界非常清晰。Agent 负责“决策循环”理解用户目标 → 拆解子任务 → 选择调用哪个技能 → 检查输出 → 决定是否重试 → 输出最终结果。它掌握的是“什么时候做什么”的判断力。Skill 负责“执行细节”在 Agent 决定调用它的那一刻开始它定义“这件事具体怎么做”。里面可以包含 prompt 指导、脚本、模板、示例但 Skill 本身不会做跨步骤的决策。它像一个高度聚焦的函数给定输入环境按既定流程产出结果。这两层是配合关系不是替代关系。你把 Agent 换成另一个品牌的 AgentSkill 大概率还能复用你把 Skill 拆了换成几个零散提示词Agent 也还能干活但稳定性就掉下来了。4.3 实践里的平衡别把 Skill 做成了 Agent 的敌人我见过一种错误做法想把 Skill 往大而全的方向做恨不得把一个 Agent 的整套智能全塞进一个技能包。结果就是一个超大的 SKILL.md、十几个脚本、几百条规则加载一次上下文就要吃掉大量 tokenAgent 还没开始干活先忍受了半天的“技能包加载仪式”。这是典型的“功能膨胀”问题。正确思路是拆小一个 Skill 对应一个明确的工作流别做万金油。比如上面那个周报生成技能功能就极其单一——读取 git 记录、生成周报完事。你不要尝试把“自动分析优化建议”也塞进去一旦加了技能边界就模糊了Agent 每次都得判断“这次要不要顺带做分析”不可控性直线上升。Skill 的本质是被 Agent 调用的工具不是 Agent 的平替。你把每个 Skill 做得短小精悍、职责明确Agent 反而更容易在恰当的时机调用它们。5. 常见问题与排查技巧实录5.1 触发不了、格式跑偏、脚本报错三个高频现象这段时间帮朋友排查过不少 Skill 相关问题我把最常出现的问题整理成了一张速查表希望对你有用。现象可能原因解决思路Agent 完全不调用这个 skilldescription 覆盖场景太窄或者和别的 skill 描述重叠用不同说法描述触发场景加入“当用户想要 xxx 时使用”检查是否和别的 skill 冲突触发了但输出格式和预期差别很大正文步骤不够原子化template 文件没有被显式引用把“参考 assets/xxx 模板”写进步骤减少每一步的职责范围脚本报错或被静默跳过脚本没有处理边界情况或依赖未声明检查 Agent 是否能看到脚本报错日志在 SKILL.md 里写清楚运行环境与依赖skill 加载后 token 消耗暴增SKILL.md 写得过长或塞了太多不需要的内容精简正文到一屏以内大段示例放进 assets 而不是正文换了 Agent 工具之后不工作目录结构或 front matter 格式不兼容查目标工具的 skill 规范文档按格式调整不要假设通用我特别想单独说下“描述冲突”的坑。有一次我同时装了“代码评审”和“代码复查”两个 skilldescription 高度相似结果 Agent 每次只能随机命中一个行为完全不可控。后来我把两个 skills 合并或者把其中一个 description 改成非常具体的使用范围问题才解决。原则就是同一批技能里的描述要互斥边界要清晰。5.2 调试技巧与其猜不如让 Agent 告诉你它看到了什么当技能行为不对时我的第一反应不是改内容而是先确认 Agent 的“加载视角”。很多 Agent 工具都有调试模式能显示当前会话加载了哪些 skill、系统提示词是什么、上下文里被注入了什么内容。开启调试模式后我可以直接看到它到底加载了哪个版本的 SKILL.md是没能触发还是触发了但执行步骤出错只要定位到是哪一步出了问题修复就变得很快。这比在正常会话里反复试错“你为什么不调用这个技能”效率高得多。另一个狠一点但同样有效的调试方法用一个全新的会话设置一个干净的测试仓库只保留被测 skill排除其他因素干扰。我实测下来发现很多“技能失效”其实是环境干扰——别的技能 descriptions 抢了触发权或者某个插件注入了冲突指令。单独隔离一测真相就出来了。5.3 避坑清单写给每一个想批量做 Skill 的人最后把这段时间积累的避坑建议整理成清单都是拿真金白银的 token 换来的创建技能包一定要纳入版本管理。你一定会改 SKILL.md改着改着就可能把以前能用的版本改坏。有 git 历史回滚一条命令的事。不要直接在 SKILL.md 里写绝对路径。用户机器上的仓库路径千差万别技能应该工作在“当前工作目录”里。description字段里的细节要围绕“触发时机的描述”不是“技能功能的描述”。这俩差别很大前者是“当用户提到周报时”后者是“一个生成周报的工具”。前者才有触发效果。依赖声明宁可多写不能少写。脚本用到requests就在 SKILL.md 里写明pip install requests。不要指望用户环境里已经装好一切。每次生成完技能先给一个最小测试用例再做复杂度扩展。我的习惯是“先让 Agent 用我准备的种子数据跑通一次流程再考虑接入真实数据”。我见过不少人做 Skill 做到一半就弃坑原因无一例外都是“做出来的东西不稳定感觉不如手动干”。但说实话不稳定多半是设计阶段没想清楚不是 Skill 这条路有问题。你把上面这张清单过一遍大部分问题都能在写第一版的时候避开。6. 写在后面Skill Creator 让我重新思考“表达经验”用 Skill Creator 做了一段时间的技能沉淀我越来越觉得它真正的价值不只是让 Agent 干活更稳定而是逼着我把脑子里的隐性经验显性化。以前带新人我常说“这个报告你照着上次那个写就行”“这个 bug 你先这样查再那样查”对方听得一脸懵以为是天赋问题。直到用 Skill Creator 整理流程我才发现自己很多所谓的经验其实根本没有被拆解到“可执行”的粒度。工具问你要“输入是什么、输出是什么、边界在哪”这一问很多含糊的地方就露馅了。所以我建议你第一次尝试时别贪功能多就挑一个你每周都在做的重复性工作——日报周报、日志排查、用例生成、PPT 目录整理都行。用我上面的流程把它做成 skill测到稳定。你会发现这个动作会同时提升两条线Agent 以后不再是“随机发挥的实习生”而你对自己工作流的理解也比以前清楚多了。这个方向后续能扩展的东西也很多比如把技能包放进团队共享仓库做维护、给行业常见的 skill 写统一的质量标准、甚至把测试方法论固化到 Skill Creator 里。但眼下最值得做的是先把第一个真正属于你自己的技能做出来跑通了再谈其他。