skills 目录怎么就成了 AI Agent 的核心资产如果你这段时间在折腾 AI Agent 或者翻看 GitHub 上那些热门的自动化项目大概率会撞见一个名为skills的文件夹。不少仓库里它的地位甚至高过src、docs一眼看过去像是什么神秘的组织规范但打开之后只有一堆 Markdown 文件和一些脚本。说实话我第一次看到这个结构时也没太当回事直到自己动手把一个 RAG 问答应用改造成带工具调用的 Agent才意识到这个看似朴素的skills目录其实是整套系统里“能力外置”的关键设计直接决定了一个 Agent 是只能动嘴皮子还是真的能帮你把活儿干了。这篇文章我想从实际落地的角度聊聊 skills 目录到底承载了什么、怎么设计才不踩坑、以及我在多轮调试中总结出来的排错套路。无论你是刚接触 Agent 开发还是已经写过一阵子 function calling这篇内容应该都能给你一些可复用的经验。1. skills 目录的本质把“能力”从代码里解放出来1.1 为什么不是写死函数而是建目录很多新手容易陷入一个误区既然 Agent 要执行操作那直接在系统提示词里把操作步骤写清楚或者在代码里写好一堆 tool function 不就行了为什么非要折腾一个skills目录我最早也是这么干的。早期的 demo 里我把所有“技能”写成 Python 函数在代码里手动态注册再用一个大 JSON 描述每个函数的用途和参数。那个阶段一切看起来还挺顺模型会调用函数、能拿到结果、能继续对话。但当功能变多之后问题很快暴露出来。首先是提示词的膨胀。我需要在系统提示词里把所有函数说明、调用规则、注意事项一次性塞进去上下文被占掉一大截。其次是扩展性差——每加一个新功能就要改代码、改注册表、改描述文档、重新部署而且写代码的人和写提示词的人往往是同一拨人但思考逻辑是两套代码要考虑类型、边界、异常提示词要考虑模型怎么理解意图。这两者纠缠在一起维护成本翻倍。skills目录的解法是每个能力自包含以目录为单位存在里面是描述文件、执行脚本、示例、依赖说明。Agent 在运行时不是“全量加载所有函数”而是先扫描系统里有哪几个技能再根据用户请求动态匹配到对应技能的描述文件把描述注入当前上下文只有确实被激活的技能才会占用 token。这种模式把“能力注册”从代码期推迟到了运行期也让能力本身变成了一种可管理、可迭代、甚至可分发的资源。类比一下把 function calling 看成是请了一个全能助手你把所有技能都提前背下来一开口就能接话而 skills 目录更像是给助手一本工作手册他不需要把全部内容背下来而是遇到什么事情翻开对应的章节照着做。后者显然更适合规模化的复杂任务。1.2 skills 与 tools、MCP 的关系如果你用过 OpenAI 的 function/tools 参数或者了解过 MCPModel Context Protocol可能会问这三者有什么区别简单梳理一下。传统的 tools 定义是 API 级的能力暴露每个 tool 是一个函数签名模型根据签名决定“该不该调、传什么参数”。优势是实现直接、平台原生缺点是每个 tool 之间的关联信息、使用前提、输出格式处理都得靠额外的代码去维护。MCP 是一个协议层解决的是“模型怎么连到外部工具/数据源”的标准化问题它把工具、资源、提示词统一成一套可被客户端发现的接口。MCP 适合做“系统级集成”比如让 Agent 能读取数据库、操作文件系统、调用第三方服务。而 skills 目录更偏向“行为级封装”它不仅给出工具接口还给出“怎么用这个工具”的完整语境。一个 skill 可以包含描述、分步操作手册、示例输入输出、若干脚本、模板文件。也就是说同样的一个功能你可以把它做成一个裸 tool也可以做成一个带操作流程指导的 skill 包。后者的决策质量通常更高因为模型不只是“知道有这个函数”而是“知道在什么场景下、按什么顺序、用哪些脚本、产生什么结果”。在实际项目里这三者也不是对立的。我见过不少项目把 skills 目录作为总的编排层内部引用 MCP server 暴露的工具或者直接调用封装好的一批 Python 函数。你可以把 skills 理解为“带说明书的工作站”而 MCP 是“工作站的接口总线”底层 tools 是“具体设备”。这套组合拳打起来Agent 的稳定性和扩展性都比我开头那个“什么都在系统提示词里写死”的版本好太多。2. 设计一个可复用的 skills 目录结构2.1 最小可用目录从 SKILL.md 开始如果你要从零开始建skills/目录我强烈建议先别急着写一堆代码而是先设计一个最小可用结构跑通“模型读取描述 → 执行脚本 → 返回结果”的闭环。一个最小可用的 skill 目录长这样skills/ └── fetch_weather/ ├── SKILL.md └── scripts/ ├── get_weather.py └── requirements.txt这个例子实现一个最简单的“查天气”能力模型接到“北京今天冷不冷”“上海会下雨吗”这类请求时先读到SKILL.md了解这个技能能做什么、怎么用然后按SKILL.md里的指引去调用scripts/get_weather.py由脚本去请求天气 API 并把结构化结果返回给模型最后由模型组装成自然语言回复给用户。SKILL.md是这个目录的核心它不仅是给人看的说明更是给模型看的“操作手册”。我建议你把它当代码来维护——写清楚 yaml frontmatter、步骤要精确、环境要标明、示例要给足。2.2 三种主流 skill 组织模式随着项目变大skills 目录会面临一个很现实的问题几十个技能文件堆在一个文件夹里扫描慢、匹配乱、维护难。结合我观察和实践中接触到的项目目前有三类组织模式第一种是“扁平目录模式”。所有技能平铺在skills/下每个技能一个文件夹互不嵌套。适合技能数量不多比如 10 个以内的项目。优点是扫描逻辑简单、实现成本低缺点是数量上来之后匹配噪声变大容易出现多个技能描述相似导致误触发。第二种是“分类子目录模式”。在skills/下再建content/、analysis/、automation/之类的分类目录。Agent 加载时先按分类过滤候选集再在类别内做匹配。适合技能数量中等、类型差异明显的项目比如有的技能偏内容生成有的偏数据分析。但注意分类粒度不要过细我看到有人分了七八个大类结果每类里只有一个技能反而多了一层 idx 逻辑。第三种是“技能包版本化模式”。每个 skill 不仅包含描述和脚本还带version、dependencies、changelog等元信息甚至整个目录就是一个独立的 git 子仓库。这种模式适合需要跨项目分发技能、或者多人在一个仓里协同维护的场景。技能可以按版本迭代更新时不影响主仓库稳定。我个人最常用的是第二种因为大多数项目很少能超过 20 个技能分类子目录带来的收益通常比额外的复杂度大。如果你在做的是个人实验项目第一种就够——重点是先把闭环跑通组织方式的优化留着后面再说。2.3 SKILL.md 的 frontmatter 与描述设计SKILL.md的 frontmatter 是整个匹配机制的核心。以我常用的一种格式为例--- name: fetch_weather description: 当用户询问天气、气温、降水概率、出门是否带伞等问题时使用。包含实时天气和未来 3 天预报查询。 version: 1.0.0 author: your_name tags: [weather, forecast, public-api] ---这里的name要简短且唯一description切记要写“触发条件 能力范围”两个要素空泛描述则会导致模型该用的时候不用。比如“查询天气”就太弱模型很可能在遇到“今天适合洗车吗”这种间接请求时不知道该不该触发而写清“当用户询问天气、气温、降水概率、出门是否带伞等问题时使用”匹配率会明显提升。SKILL.md正文部分同样是给模型看的操作手册和给开发者看的 README 不一样。我踩过最深的坑就是按人看的习惯把步骤写得太省略比如“调用脚本获取天气”模型因为缺乏经验即使拿到也可能走歪——比如不解析脚本存在的环境问题、不处理超时、不校验返回值。你必须在正文中写明完整的执行链这个脚本接受一个中文城市名作为参数返回 UTF-8 编码的 JSON 字符串。执行前确认已安装依赖见 requirements.txt。如果脚本返回 errors 字段非空直接把错误信息返回给用户不要自行猜测。示例输入北京输出{city:北京,temp_c:21,humidity:48,condition:晴}。3. 实操从零手写一个可用的 skill 包3.1 场景设定与需求拆解空谈设计意义不大我们直接动手做一个完整的技能包。这里我选的场景不是天气因为天气 API 的 key 获取并不普适而是“批量整理下载目录的文件”。这个场景很贴近日常不需要外部服务不依赖云 API用 Python 标准库就能写完门槛最低又能把整个 skills 机制跑通。需求拆解如下用户一句话下达指令比如“把下载文件夹里的图片按月份归档”。Agent 识别是文件整理类任务命中organize_downloads这个 skill。Skill 读取SKILL.md操作说明调用对应脚本。脚本扫描~/Downloads按扩展名分组并按文件修改时间归档到整理后的文件名_年月子目录中。脚本返回一批结构化操作结果移动了多少个文件、跳过了哪些Agent 据此组织成回复。和纯写代码相比最核心的差异在于脚本要负责执行但“要不要执行、怎么组合参数”由模型决定。所以脚本接口要做得既有默认值又能参数化。3.2 目录与文件内容示例先看完整的目录skills/ └── organize_downloads/ ├── SKILL.md └── scripts/ ├── organize_files.py └── README.md注意我这里用README.md给“人”看而SKILL.md是给模型看的。两个文档职责区分开这样开发者维护起来也不会混淆。SKILL.md内容如下--- name: organize_downloads description: 当用户要求整理下载文件夹、Downloads 目录、按类型或日期归类文件、清理杂乱文件时使用。能够按扩展名归类或按年月归档。注意只适用于本地下载目录不适用于项目代码目录。 version: 1.1.0 author: your_name tags: [files, organize, local] --- 这是一个用来整理本地下载目录的自动化技能。它通过执行 Python 脚本把下载目录下散落的文件移动到分类子目录中。 使用前注意 1. 默认扫描路径是用户主目录下的 Downloads 文件夹。 2. 支持两种归档模式按类型图片、文档、视频、压缩包等与按月份年-月。 3. 脚本不会删除任何文件只会移动文件。 4. 如果同名文件已经存在脚本会自动加时间戳后缀不会覆盖。 执行方式 在 Python 3.9 环境中运行 python organize_files.py --mode type 或 python organize_files.py --mode month --dry-run。 建议先执行一次带 --dry-run 的命令确认结果后再正式执行。 脚本返回 JSON 格式的结果包含 moved_count、skipped_count、skipped_files 等字段。如果出现异常返回 errors 字段。 示例 “把下载文件夹里的图片按月份归档” → 执行 python organize_files.py --mode month --extensions .jpg .jpeg .png .gif “整理一下下载目录” → 默认执行 python organize_files.py --mode typeorganize_files.py的核心逻辑部分关键代码import argparse import json import os import shutil from pathlib import Path from datetime import datetime CATEGORY_MAP { images: [.jpg, .jpeg, .png, .gif, .bmp, .webp, .svg], documents: [.pdf, .doc, .docx, .txt, .md, .xls, .xlsx, .ppt, .pptx], videos: [.mp4, .mkv, .mov, .avi, .webm], archives: [.zip, .rar, .7z, .tar, .gz], audio: [.mp3, .wav, .flac, .aac], } def detect_category(ext: str) - str: ext ext.lower() for category, exts in CATEGORY_MAP.items(): if ext in exts: return category return others def safe_move(src: Path, dest_dir: Path) - dict: dest_dir.mkdir(parentsTrue, exist_okTrue) dest dest_dir / src.name if dest.exists(): stamp datetime.now().strftime(%Y%m%d%H%M%S) dest dest_dir / f{src.stem}_{stamp}{src.suffix} shutil.move(str(src), str(dest)) return {src: str(src), dest: str(dest)}3.3 执行链如何被触发从用户请求到脚本运行写完 skill 包只是第一步更关键的是把它接进 Agent 的执行链。以我自己用的一个简易编排器为例核心循环是接收用户消息。扫描skills/下所有SKILL.md读取 frontmatter 的 name 与 description。将这批候选描述拼进“可用技能清单”发送给模型。模型在回复里选择某个技能并可能给出参数如目标目录、归档模式。编排器调用对应脚本/执行器把技能目录中的命令行参数模板填好跑起来。把 stdout 输出塞回模型上下文模型组织最终回答。这段链路里最容易出问题的有两点候选描述的拼接顺序与 token 消耗以及参数提取准确性。候选描述建议只保留 name description “是否需要特殊环境”三件事不要塞正文。等模型确实选中了某个技能再把完整的SKILL.md正文喂给模型。这样既控制了 token也避免了多个技能的完整手册互相干扰。参数提取这块我踩过不少坑。比如模型对着--extensions传了.jpg, .png, .gif脚本用split()解析就崩了或者模型把一个不存在的目录路径直接传给脚本。不要指望模型能精确理解 argparse 的规则。更稳的做法是编排器在调用脚本前做一次“参数清洗”把逗号分隔的扩展名拆成数组把~/Downloads展开成绝对路径给路径不存在的情况补一个默认值。这段清洗逻辑写个 20 行左右的函数就能彻底解决很值得做。3.4 测试和调试技能包写完一个 skill最基本的验证方式是用 dry-run 跑一遍。以我的经验测试技能包不能只看脚本能否运行还要看模型路径是否通畅。所以我会在本地做两层验证。第一层是纯脚本层直接命令行执行python organize_files.py --mode month --dry-run确认输出 JSON 合法、字段完整。这一层只验证“脚本本身可靠”。第二层是编排层不传任何参数用自然语言要求 Agent 去整理文件然后观察中间日志看模型到底有没有选中正确的 skill、提取的参数对不对。这一步我会故意用模糊的措辞来测比如“给下载目录瘦瘦身”“把乱糟糟的文件夹理一理”倒逼描述编写足够健壮。我见过很多第一次写 skill 的新手脚本写得很完善但SKILL.md描述里用的措辞太具象结果任何变体提问都不触发事倍功半。测试还有一个要点务必在隔离的临时下载目录上测别拿真实下载目录当试验田。我第一次测试时图省事直接跑了正式目录结果把所有文件按月份归档完之后才意识到自己在真实环境上做实验本身就不该发生好在没造成损失但那份紧张感至今记忆犹新。正确做法是建一个~/Downloads_test目录把脚本的默认路径通过参数改掉再测。4. 常见问题与排查技巧实录4.1 模型怎么都不触发某个技能这个是我在社区里被问到最多的问题。明明技能包已经放进skills/了脚本也能正常运行但不管怎么问模型就是不去选它。先别急着调提示词按顺序排查扫描逻辑是否把该技能纳入了候选列表检查日志里有没有加载该SKILL.md。description是否覆盖了你测试的那些问法用“图片归档”和“整理下载”这两种不同表述各测一次看有没有一个能触发。如果全都不触发那就是描述里的触发词域太窄。候选列表是否因为 token 限制被截断了技能数量多时排在后面的技能很容易被截断模型根本看不到它。是否存在多个技能 description 冲突比如有一个“通用文件管理”技能把归档的活也揽下来了模型每次被它抢走。这些排查步骤按顺序走一遍大多数问题都能定位。我遇到过的高频原因其实就是第 2 条——描述太书面、太正式模型在口语化问法面前完全无感。4.2 模型选了技能但参数传错典型表现是模型确实选对了 skill但传给脚本的参数乱七八糟。比如归档模式填了monthly而不是month路径带上了中文引号扩展名用空格而不是逗号分隔。这类问题的根源在于模型没见过具体的接口示例。解决办法是在SKILL.md里增加“示例”板块时特意给一个“错误参数”示例一句话说明错在哪。模型在这种正反例的引导下传参准确性提升非常明显。同时调度器侧必须做参数兜底解析失败就返回一个“重试请用如下格式”的报错信息让模型自己修正。用今时今日模型指令遵循的水平给一次修正机会通常就足够比直接中断任务体验好得多。4.3 脚本执行结果不稳定、偶发失败这类问题通常和脚本本身有关和模型无关。有一个高频原因脚本依赖的系统库或 API key 没就绪但脚本没有给出清晰报错。Agent 拿到的是空输出或乱码自然无法组织有效回复。我的经验是任何给模型执行的脚本都要具备三种输出状态成功标准 JSON包含结果摘要和数据明细。业务失败比如目标路径不存在、没有匹配的文件返回带reason字段的 JSON。系统异常脚本崩溃时用traceback.format_exc()捕获完整的错误信息并输出。模型见到“目标路径不存在”这种结构性描述就能组织出合理的自然语言回复而不会抛出 Python 堆栈段子让用户莫名其妙。所以脚本里多做一层异常兜底表面上是“工程洁癖”实际上是给 Agent 的决策提供了必要的信息基础。还有一些细节比如 Windows 路径分隔符、中文路径名、文件被占用导致移动失败等都是脚本层容易踩的坑。在技能脚本里处理路径时坚持用pathlib.Path尽量避免字符串拼接路径这是最有效的防坑习惯。4.4 速查表从报错到根因现象可能原因优先排查方向技能未被触发description 触发域太窄 / 候选被截断检查描述覆盖度与扫描日志技能触发但参数错误SKILL.md 缺少正反例 / 接口不明确补充示例与参数说明脚本执行成功但模型答非所问输出 JSON 字段语义不清晰精简输出字段增加结果摘要脚本偶发失败依赖缺失 / API key 失效 / 路径异常加异常捕获输出结构化错误技能加载占用大量 token候选列表全量载入正文改为按需载入完整 SKILL.md5. 一点经验谈把skills目录玩明白之后我最大的感受是AI Agent 开发的重心正在从“写更聪明的提示词”转向“设计更可靠的能力单元”。你在一个 skill 包里投入的精细度会直接决定模型在关键时刻的表现毕竟模型再聪明也没有一个可以随时打开的操作手册来指导它。我也越来越习惯“让 Agent 先走一遍 dry-run、确认后再落地执行”这类高容错设计。很多人在 agentic 项目里翻车往往不是模型的推理能力不够而是没给模型留“确认”和“回退”的余地。Skills 既然承担了“能力外置”的职责那每个能力是否安全、是否可回滚、是否输出结构化成 JSON也都应该在设计阶段就想清楚。如果你现在正准备为自己的 Agent 项目搭建skills目录我的建议很简单从一个真正的场景开始把一个技能做扎实、测到位比一次性铺开十个半成品有用得多。等你养成了“以能力单元为核心”的迭代习惯再回头去看那些堆满提示词的旧代码会发现原本复杂的事情其实完全可以拆解得更干净。