最近在几个开发者群里总有人拿着各种 Agent 项目问我同一个问题AI Skill 到底是怎么写出来的能不能给一套能直接跑起来的问的人一多我干脆把这套东西完整整理出来顺便把我自己踩过的坑一并交代。这篇不玩虚的。先用大白话讲清楚 AI Skill 解决什么问题再给一套可以直接套用的规范目录然后从零写一个能运行的文件归类 Skill最后把接入 Agent 和排错的实战经验也讲透。读完你不仅能照着写还能理解每一步设计背后的理由下次做复杂功能也不会两眼一抹黑。1. AI Skill到底是什么先搞懂它解决什么问题1.1 它和普通脚本的最大区别很多人第一次接触 AI Skill 时第一反应是这不就是个 Python 脚本吗确实逻辑层面它就是一个脚本但真正让它变成AI Skill的不是代码本身而是外面包的那层说明和契约。普通脚本是这样工作的你自己知道什么时候双击运行、输入什么参数、输出结果有什么用。但放到 Agent 场景里就不一样了。你面对的是一个只会理解意图的大模型它根本不知道你电脑里有个 main.py也不知道这个 main.py 是干嘛的。你直接跟模型说帮我写个整理文件的代码它只能自己临时发挥你没法把自己精心调试好的逻辑稳定复用它。Skill 就是来解决这个问题的。它把一段已经写好的、可靠的能力封装成一个标准模块同时附带一份大模型能看懂的说明书告诉模型这个工具是干什么的、什么情况下该用它、参数怎么填、边界在哪里。模型只要读到这份说明书就能在合适的时机把工具调起来。说白了普通脚本是人指挥机器AI Skill 是大模型指挥现成的机器。代码只是它的手SKILL.md 才是它的脑子。1.2 三个核心部件声明、逻辑、调用契约一个标准的 AI Skill 通常由三部分组成缺一不可核心部件承担职责通俗类比元信息声明通常是 SKILL.md描述名称、触发条件、参数、限制外卖包装上的说明标签执行逻辑通常是 main.py真正完成任务的代码后厨里的厨子调用契约函数签名或命令行参数让大模型生成的参数能正确传进来取餐窗口的编号规则这三者的关系可以这样理解大模型是调度员它看到用户说我的桌面太乱了就从一堆 Skill 的说明标签里找到最匹配的那个把桌面路径这个参数按窗口规则递进去后厨出菜调度员把结果端给用户。所以新手最容易犯的错就是把全部精力放在写逻辑代码上SKILL.md 随便糊弄两句话。逻辑写得再好模型看不懂、不会调、调不对这个 Skill 就废了。1.3 什么场景才值得写一个Skill不是所有事情都值得做成 Skill。我自己的判断标准有三个规则明确的事值得做。比如文件归类、格式化文本、定时提醒、查询特定接口、批量重命名这些逻辑稳定、步骤清晰、结果可验证。大模型虽然能说个大概但真让它精确操作文件和接口它很容易出错这种精确活就应该交给代码。重复性高的事值得做。如果你发现自己半年内三次让大模型按某个模板处理数据每次都重新描述需求、重新给示例、重新纠正它犯过的错那就该把它固化成 Skill。下次一句话就能触发稳定输出不用再陪着模型反复试。需要权限或副作用的事必须做。读写本地文件、发送网络请求、操作外部系统这些动作在大模型对话里只能模拟在现实里必须有一段可信代码来兜底。Skill 就是那个兜底的执行者。反过来说闲聊、观点表达、开放性创作、简单常识问答这些大模型自己就能干得很好你硬套一个 Skill 反而画蛇添足。还有一类常见误区是拿 Skill 去包装提示词里面根本没有可执行的逻辑只是写了一段请按以下规则回答。这种本质上还是普通提示词不是 Skill别被概念绕晕。2. 规范目录一个Skill该怎么搭骨架2.1 标准目录长什么样我见过不少自己折腾的 Skill目录结构五花八门有把所有内容塞进一个 md 文件的也有把代码铺得乱七八糟的。等你维护到第三周就会明白规范目录不是强迫症而是让这套东西能被加载器识别、能被其他人接手、能被未来的自己快速理解。一套比较通用的规范目录长这样my_skill/ ├── SKILL.md # 技能说明与调用入口最重要 ├── config.yaml # 可选参数配置便于非程序员调整 ├── requirements.txt # 依赖锁定 ├── main.py # 主逻辑入口 ├── core/ # 逻辑拆分层逻辑复杂时使用 │ ├── __init__.py │ ├── parser.py │ └── executor.py ├── templates/ # 模板资产可选 │ └── report_template.md ├── assets/ # 静态资源可选 └── tests/ └── test_main.py # 冒烟测试看完这个目录一个没看过代码的人也能大致猜出项目结构SKILL.md 负责声明main.py 是入口config 做配置core 放核心逻辑tests 管质量。这种见名知意的价值在团队协作和长期维护里会被放大很多倍。当然演示用的 Skill 不需要这么重逻辑也就几十行单文件完全可以。后面我给示例会采用精简结构但你心里得知道一旦逻辑超过两三百行就该拆包管理别硬塞进一个文件里。2.2 每个文件在项目中承担什么职责我把每个文件的定位和必要性整理成一张表方便你对照文件是否必填作用与说明SKILL.md必填声明技能名称、触发描述、参数格式是 Agent 决定何时调用该 Skill 的依据main.py强烈建议提供可执行入口保证任何模式都能通过一条命令运行requirements.txt强烈建议锁定 Python 依赖避免换台机器就报 ModuleNotFoundErrorconfig.yaml选填把可变参数从代码里抽离改行为不用动代码tests/推荐验证核心函数行为防止重构时悄悄改坏功能templates/assets选填存放非代码资源让目录结构更整洁这里有两个设计逻辑值得多说一句。第一为什么 SKILL.md 是必填因为在常见的 Agent 加载机制里框架扫到一个目录后首先要读的就是 SKILL.md通过里面的字段决定要不要注册、怎么注册。你把它改成 readme.txt框架就不认了。这就是约定优于配置大家都按同一个约定来工具链才能通用。第二为什么把参数放到 config.yaml 而不是写死在代码里我见过太多需求变更的场景分类规则变了、目标目录换了、阈值调了如果都写在代码里改的人就得懂逻辑、小心改完不破坏别处。抽到 YAML 后一个不懂代码的同事也能照着注释改分类风险小很多。这个习惯在很多工程领域都适用。2.3 SKILL.md怎么写才不会让模型看不懂SKILL.md 是整个 Skill 的灵魂但很多人恰恰在这一步翻车。翻车的原因很简单把 description 写成了功能说明书而不是触发条件。举个例子一个文件归类工具新手可能会写一个文件整理工具。这句话没有任何问题但对大模型来说帮助几乎为零。它不知道什么时候该用、什么情况不该用、参数怎么填。模型选工具靠语义匹配你给的信息越模糊它就越容易在错误的时候调错工具。我更推荐这样组织 SKILL.md 的开头元信息--- name: tidy_folder description: 将指定目录下的文件按类型自动归类到对应子文件夹。当用户要求整理下载目录、桌面等文件或表达太乱了想分分类时使用。注意仅用于文件归类不用于查找文件、不用于删除文件。 version: 1.0.0 tags: [文件管理, 效率工具] arguments: target_dir: type: string description: 要整理的目录路径可省略默认使用配置中的 target_dir required: false ---注意 description 的写法我做了三件事写清楚它是什么。不是一个工具而是将指定目录下的文件按类型自动归类。写清楚什么时候触发。用户说整理下载文件夹桌面太乱了这些典型表达直接给出来模型一看就能把用户意图和这个 Skill 挂钩。写清楚什么时候不触发。明确不用于查找文件、不用于删除文件这能大幅降低误调用率。模型选错工具很多时候不是因为笨而是因为你没给它排除选项。arguments 部分也很关键。它告诉模型如果你想调用这个函数需要提供哪些参数、参数是什么类型、是否必须。模型看到这个结构才能把用户话里的下载文件夹自动提取成 target_dir 的值。没有这个声明模型就算想调用也不知道怎么传参。3. 从0写出可运行代码文件自动归类Skill完整实现3.1 为什么选文件自动归类做首个Skill我教过不少人写第一个 Skill选来选去文件自动归类这个方向最合适原因有四层。第一规则清晰。文件按扩展名分类逻辑直白不需要复杂的算法和外部服务。第二见效快。跑一次就能看到文件被整理得整整齐齐成就感特别强。第三适合讲安全设计。移动文件是有副作用的操作如果不小心可能把用户文件弄乱这正好用来引入预览模式这种工程思维。第四容易扩展。你改一下 config 就能适配图片整理、项目代码归类、素材库归档等场景学一个能顶好几个。3.2 完整可运行代码这个示例我尽量保持精简但保留了关键的工程习惯默认预览、冲突自动改名、配置外置。目录结构如下tidy_folder/ ├── SKILL.md ├── config.yaml ├── requirements.txt └── main.py先看依赖文件只有一个# requirements.txt PyYAML6.0然后看配置分类规则全部放在这里# config.yaml target_dir: ~/Downloads rules: 图片: [.jpg, .jpeg, .png, .gif, .webp, .bmp] 文档: [.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .md, .txt] 压缩包: [.zip, .rar, .7z, .tar, .gz] 视频: [.mp4, .avi, .mkv, .mov, .flv] 音频: [.mp3, .wav, .flac, .aac] 代码: [.py, .js, .ts, .java, .c, .cpp, .go, .rs] 安装包: [.dmg, .exe, .msi, .pkg]再看主逻辑这份代码可以直接复制运行 tidy_folder - 文件自动归类 Skill 主逻辑 用法: python main.py --dir ~/Downloads # 预览模式只打印不移动 python main.py --dir ~/Downloads --apply # 实际执行移动 import argparse import shutil from pathlib import Path import yaml def load_config(path: str config.yaml) - dict: 读取 YAML 配置配置错误时直接抛异常方便定位。 with open(path, r, encodingutf-8) as f: return yaml.safe_load(f) def classify_file(filename: str, rules: dict) - str: 根据扩展名返回文件分类未知类型统一归入其他。 ext Path(filename).suffix.lower() for category, exts in rules.items(): if ext in exts: return category return 其他 def tidy_folder(target_dir: str, rules: dict, apply: bool) - dict: 扫描目录按规则移动到分类子目录。返回统计信息。 target Path(target_dir).expanduser() if not target.is_dir(): raise FileNotFoundError(f目录不存在: {target}) stats {moved: 0, skipped: 0, details: {}} for item in target.iterdir(): # 跳过子目录不进分类范围 if item.is_dir(): stats[skipped] 1 continue category classify_file(item.name, rules) if not apply: stats[details].setdefault(category, []).append(f[预览] {item.name} - {category}/) else: category_dir target / category category_dir.mkdir(exist_okTrue) dest category_dir / item.name counter 1 while dest.exists(): dest category_dir / f{item.stem}_{counter}{item.suffix} counter 1 shutil.move(str(item), str(dest)) stats[details].setdefault(category, []).append(f已移动: {item.name} - {category}/{dest.name}) stats[moved] 1 stats[total] stats[moved] stats[skipped] return stats def main() - None: parser argparse.ArgumentParser(description文件自动归类 Skill) parser.add_argument(--dir, defaultNone, help要整理的目录默认读取 config.yaml) parser.add_argument(--apply, actionstore_true, help实际执行移动默认只预览) args parser.parse_args() config load_config() target_dir args.dir or config.get(target_dir, ~/Downloads) rules config.get(rules, {}) print(f目标目录: {target_dir}) print(模式: 预览不会移动任何文件 if not args.apply else 模式: 实际执行) stats tidy_folder(target_dir, rules, applyargs.apply) for category, items in stats[details].items(): print(f[{category}]) for line in items: print(f {line}) print(f\n共扫描 {stats[total]} 项忽略目录 {stats[skipped]} 项处理文件 {stats[moved]} 个) if __name__ __main__: main()最后是 SKILL.md核心元信息我们前面已经拆解过完整版如下--- name: tidy_folder description: 将指定目录下的文件按类型自动归类到对应子文件夹。当用户要求整理下载目录、桌面等文件或表达太乱了想分分类时使用。注意仅用于文件归类不用于查找文件、不用于删除文件。 version: 1.0.0 tags: [文件管理, 效率工具] arguments: target_dir: type: string description: 要整理的目录路径可省略默认使用配置中的 target_dir required: false --- # tidy_folder 文件归类 把目录下散落的文件按扩展名移动到对应分类子目录。 ## 使用场景 - 用户说整理我的下载文件夹 - 用户说桌面太乱了帮我分分类 - 用户给出一个目录希望按文件类型归档 ## 注意事项 - 默认只做预览只有传入 applytrue 时才真正移动文件 - 同名文件会自动追加 _1、_2 序号避免覆盖 - 子目录不会被移动3.3 代码设计的5个关键细节这份代码看起来简单但有几个细节是真实场景里最容易出问题的点值得单独拆开讲。第一个是预览模式。命令行默认不移动任何文件只有显式加上--apply才真正执行。这个设计对 AI 调用尤其重要。你想想大模型自动调用的时候它可不会像人一样先确认再动手。如果 Skill 一被调用就移动文件一旦规则配置错了或者用户本来只想看看却误触发了执行后果就是文件被挪得乱七八糟。预览模式等于给所有副作用操作加了一道保险这是我强烈建议保留的习惯。第二个是同名冲突处理。shutil.move遇到目标文件已存在时会直接覆盖这是非常危险的。所以我在移动前判断dest.exists()存在就自动追加_1、_2这样的序号。代码里用了一个 while 循环来保证文件重名到多少都能找到可用名字。别小看这几行实际用起来用户目录里同名文件出现的频率远超你想象。第三个是 pathlib 而不是 os.path。Path对象天然兼容 Windows、macOS、Linux 的路径风格处理中文文件名也更可靠。你在自己机器上跑没问题但 Skill 可能被别人拿到别的操作系统上用这种跨平台细节提前处理好能省很多事。第四个是配置外置。分类规则全部在 config.yaml 里代码里只留了一套读取和执行的逻辑。以后想增加视频分类改一行 YAML 就行不用动代码。这个思路对非程序员使用者特别友好。第五个是防御式入口。tidy_folder第一件事就是确认目录存在不存在直接抛FileNotFoundError。别觉得多余目录路径错误是这类工具最常见的调用失败原因。早失败、大声失败比静默跑完给一个空结果好用得多。4. 把Skill跑起来并接入Agent从本地测试到实际调用4.1 本地运行三步走代码写完先别急着接 Agent先在本地把整套流程跑通。我建议按三步走。第一步准备环境。在项目目录下创建虚拟环境并安装依赖cd tidy_folder python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt这里有个容易忽略的坑如果你不激活虚拟环境直接执行 main.py系统用的是全局 PythonPyYAML 可能没装就会报ModuleNotFoundError。很多人遇到这个问题第一反应是重复安装依赖其实只是没激活环境。第二步建一个测试目录。我通常会在项目下建一个demo/在里面放几个不同格式的文件比如a.jpg、b.pdf、c.py、d.zip。然后先跑预览模式python main.py --dir ./demo输出应该是每个文件要去哪里的清单但实际文件没有任何变动。这一步是为了确认分类规则符合预期。第三步确认没问题后真正执行一次python main.py --dir ./demo --apply再去 demo 目录里看应该多出了图片、文档、代码、压缩包等子目录文件分别进了各自该进的地方。我把预期结果整理成了表格操作预期结果预览模式只打印分类计划文件位置不变apply 执行一次生成分类子目录文件进入对应目录apply 重复执行不会报错同名文件自动加 _1、_2 后缀传入不存在的目录抛出目录不存在异常不静默退出跑通这三个场景这个 Skill 的基本可靠性就算验证过了。4.2 接入Agent的两种方式本地验证通过后下一步是把 Skill 接到你的 Agent 上。不管用哪种框架思路基本归为两类。方式一目录扫描式。大部分现成的 Agent 框架都会约定一个 skills 目录你只要把tidy_folder/整个文件夹丢进去框架启动时会自动扫描到 SKILL.md解析元信息注册成可调用工具。这种方式最省事社区生态也比较统一。前提是你严格按规范写好了 SKILL.md字段名和结构都要对得上。方式二函数注册式。如果你用的是自己写的调度系统或者框架没有目录扫描能力就需要手动把核心逻辑包装成一个可被调用的函数。关键是让输入输出尽量保持 JSON 兼容方便模型调度。我一般会加一个薄薄的包装层RULES load_config().get(rules, {}) def call_skill(raw_args: dict, context: dict) - dict: target_dir raw_args.get(target_dir, ~/Downloads) apply raw_args.get(apply, False) try: stats tidy_folder(target_dir, RULES, applyapply) return {status: ok, stats: stats} except Exception as exc: return {status: error, message: str(exc)}这个包装函数的价值在于它把大模型可能传入的杂乱参数统一成raw_args字典再在内部做提取和校验出错时返回结构化的错误信息而不是让 Agent 直接看到一堆堆栈。接入时只需要把这个函数注册到工具列表里同时把 SKILL.md 里的 arguments 描述给到框架模型就知道怎么填参了。4.3 日志与异常定位接入 Agent 之后你会发现问题从代码能不能跑变成了模型到底有没有正确调用。这时候最需要的是日志和定位手段。我的建议是第一版先别上复杂日志框架print 就够用。在 main() 里把目标目录、运行模式、分类结果全部打印出来本地看得见就行。跑通之后如果 Skill 要在后台长期运行再把 print 替换成标准库 logging输出到文件方便回溯。遇到模型调用失败优先查两个地方。第一SKILL.md 的 description 是否足够精确。模型没触发、误触发八成问题出在这。第二参数对齐是否正常。模型可能把路径传成target_dir也可能漏传还可能把apply理解成字符串true而不是布尔值。我的经验是在包装层里做一层宽松解析遇到字符串true也按 True 处理别让模型的小失误直接击穿整个调用。5. 新手避坑常见问题与排查方法5.1 高频问题速查表在实际使用和帮人调试的过程中新手遇到的坑高度集中。我把最典型的几类整理成了速查表建议直接收藏现象可能原因解决方案Agent 从不调用这个 Skilldescription 写得像功能说明书模型不知道何时触发改成触发条件 否定条件报 ModuleNotFoundError依赖未安装或虚拟环境未激活激活 .venv 后执行 pip install -r requirements.txt中文文件名乱码文件读写编码不一致统一使用 open(…, encodingutf-8) 和 pathlib移动后文件丢失同名文件冲突被覆盖移动前检查目标存在自动追加序号AI 传参错误参数声明不清晰模型瞎填SKILL.md 中给每个参数写明类型、示例、是否必填目录不存在但执行成功前置校验缺失入口函数先检查目录存在性再继续执行修改 config 后不生效加载配置的路径写错或缓存了旧配置确认 load_config 指向项目内真实路径同一个 Skill 在不同环境行为不一致依赖版本未锁定requirements.txt 写死主版本号如 PyYAML6.0这八个问题覆盖了我见过的绝大多数翻车现场。其中Agent 从不调用和同名文件覆盖是最多发的两类前者是设计问题后者是代码问题都很值得在写第一个 Skill 时提前想清楚。5.2 三个反复被验证的实操心法除了上面的问题清单我还有三个从实际项目里总结出来的习惯每次都帮我少踩不少坑。第一任何会动用户数据的 Skill必须默认预览。不只是文件移动包括批量重命名、批量修改内容、发消息、删记录都属于有副作用的操作。默认预览、二次确认用户能接受反过来一旦误操作造成数据损失信任就很难重建了。第二description 里一定要写不适用条件。这个技巧对降低误调用率效果出奇地好。比如我们的 tidy_folder明确写了不用于查找文件、不用于删除文件模型就很少在用户想要找出所有 pdf这个场景里去调用它。语义匹配是概率问题你每排除一个歧义误调用概率就降一截。第三SKILL.md 里写清楚版本号。你可能觉得一个个人用的小工具不需要版本管理但当你维护了三四个 Skill又恰好换了 Agent 框架或调整了参数格式之后你就会明白版本号、变更记录、参数兼容说明这些东西不是给 AI 看的是给三周后的自己看的。还有一个容易被忽略的细节技能命名要全局唯一。将来你的 Agent 可能挂载十几个 Skill如果两个技能都叫report框架的注册环节直接冲突你自己排查起来也非常痛苦。名称里带点业务特征比如weekly_report_generator、tidy_folder一眼就能知道它是什么。我在实际写 Skill 的过程中越来越深的一个体会是砖块本身不值钱值钱的是让砖块各就各位的那套秩序。代码你可以让大模型帮你生成目录结构你可以照抄别人的模板但什么时候该加预览开关、description 该怎么排除歧义、参数契约要怎么定义这些细节只能在动手实践里慢慢长成肌肉记忆。这个示例 Skill 后面还可以扩展的地方非常多比如把分类规则做得更智能不只按扩展名还能按文件名关键词归到自定义项目目录或者加一个--undo参数记录每次移动操作让用户能一键回滚再或者做成定时任务每天凌晨自动整理一次。基础框架已经立住了剩下就是往里面加你想加的能力。最后再交代一句特别重要的话第一次在你的真实工作目录上跑这个 Skill 之前务必先跑一遍预览模式确认分类规则没问题再上--apply。文件这东西挪错了想找回来可比写十行代码麻烦多了。