如果你最近在折腾 Microsoft Agent Framework 的 Skills 机制大概率会遇到同一个困惑模型看着挺聪明描述文件也写了一大堆可真让它干点实事——比如跑个 Python 脚本、调一次命令行工具、处理一批本地文件——它就卡壳了。原因很简单Skill 如果只停留在纯提示词层面那它本质上是“知道”而不是“做到”。真正让 Skill 从“会聊”变成“会干”的恰恰是这堆不太起眼的 Scripts。我最近把一个完整的数据处理流程用 SkillsScripts 搭了出来从能跑通到跑得稳踩了不少坑也总结出一套还算顺手的实战打法这里从头到尾拆给你看。这篇文章适合两类人一类是对 Microsoft Agent Framework 刚上手、想把 Skills 做成真正可用功能模块的开发者另一类是被脚本调用搞得焦头烂额、想搞明白“Skill 和 Scripts 之间到底怎么配合”的踩坑玩家。读完你至少能解决三件事知道怎么组织一个带可执行脚本的 Skill搞清楚 Agent 调用脚本的完整链路和参数传递方式还能直接照抄一份跳过常见坑的排查方案。1. 先把概念理清Skills 和 Scripts 在 Agent Framework 里到底各管什么1.1 Skills 不是“提示词”而是一套可执行的技能包很多人在初学 Microsoft Agent Framework 时容易把 Skills 理解成“给模型的一段额外提示”其实这个理解偏差挺大的。从工程视角看Skill 更像一个“带说明书的可执行工具包”说明书部分是结构化的 Markdown 文件通常是SKILL.md它告诉大模型这个技能在什么场景下用、需要哪些输入参数、能产生什么结果可执行部分是scripts/目录下的真实脚本它们接收参数、调用系统能力、返回结果是真正落地干活的东西。这样拆开设计的价值很明显。纯提示词技能最大的问题是输出不稳定——你让模型“算一下目录大小”它可能给你编一个数也可能决定现场写一段 Python 代码再自己“脑补”运行结果。但当你把“算目录大小”的逻辑下沉到一个脚本里模型的任务就简化成“识别意图 填写参数 发起调用”最终输出的正确性由脚本保证模型的自由度被约束在可控范围内。这在生产环境里是决定能不能用的关键。1.2 Scripts 是让 Skill 具备“手”的那层执行引擎Scripts 在 Agent Framework 里的角色打个比方就是Skill 是大脑里的作战方案Scripts 是士兵手里的枪。方案再完美没有枪也打不了仗。在具体实现上Agent 框架的运行流程大概是这样的用户提需求 → 模型根据SKILL.md的描述判断该不该用这个技能 → 决定使用后填入参数 → 框架通过 harness执行环境把参数传给scripts/下的脚本 → 脚本在目标环境中运行并把 stdout、stderr、退出码返回给模型 → 模型基于结果继续推理或直接回复用户。这里有一个非常关键的设计倾向脚本最好是“无状态、纯执行”的。也就是说脚本只负责根据入参算结果不要内部维护什么会话状态、不要把废话输出到 stdout、更不要偷偷往某个临时目录塞中间文件却不告诉主进程。你越是把脚本做成黑盒式的小工具Agent 在调度它的时候就越不容易出错调试起来也越轻松。1.3 Harness连接模型决策和脚本执行的中间层热词里有个“大模型 skills harness 深入理解”哈ness确实是这套体系的核心腰眼。Harness 说白了就是那层“调度器”它负责解析SKILL.md中的参数 schema把模型的自然语言输出转成结构化的脚本调用参数建立沙箱或子进程环境控制脚本能访问的目录、网络、系统资源捕获脚本输出按约定格式回传再让模型读取。我在实战中发现理解 harness 的最好切入点是“结果回传格式”。因为脚本怎么输出、框架怎么解析直接决定了你能不能写出靠谱的 Skill。如果脚本只是往 stdout 里扔一段普通文本模型还能凑合看但如果你希望模型拿到结果后还能做二次处理比如提取摘要、判断下一步操作那就最好让脚本输出结构化 JSON并遵循固定的字段格式。这一点后面我会详细示范。2. 动手前的准备搭一个能跑 Scripts 的 Skill 项目2.1 环境要求和目录结构先列一下我这边实测可用的环境基线版本太老的话有些特性没跟上排查起来很闹心Node.js 18Agent Framework 的 SDK 和不少脚本工具链依赖它Python 3.10如果你要写的是数据处理类脚本这个版本往上会比较省心包管理器我用的是 npm 11这也是后面一个坑的源头后面细讲Agent Framework SDK 建议用最新稳定版因为 Skills 机制迭代还挺快的。Skill 项目的目录结构我用的是官方推荐风格自己也做了一些扩展skills/ └── exec-python/ ├── SKILL.md ├── scripts/ │ ├── main.py │ └── requirements.txt (可选) ├── assets/ (可选放配套说明、模板等) └── reference.md (可选补充给模型看的上下文)关于目录结构有三点经验。第一每个 Skill 一定要独立成目录不要多个 Skill 的脚本混在一个目录里否则模型在判断调用哪个入口时很容易搞混。第二scripts/子目录是惯例Agent Framework 的 harness 默认会从这个目录找可执行入口特殊设置反而容易出问题。第三assets/和reference.md属于加分项用于给模型提供更详细的参考资料前期可以先不搞等核心跑通了再逐步加上。2.2 核心文件 SKILL.md 怎么写才不会被模型误用SKILL.md是整个 Skill 的说明书它的质量直接决定模型用得好不好。一个常见的误区是描述写得太虚模型根本判断不准什么时候该调。我写描述时遵循三个原则场景要具体写“用于统计CSV文件中各列的空值比例并输出数据质量报告”而不是笼统的“用于数据处理”。参数要写清把每个参数的格式、单位、必填与否都列明白。例如file_path: string (必填, 绝对路径或相对路径)。边界要说明明确指出“不要用于处理图片”或“仅支持UTF-8编码文件”减少模型乱调用。另外SKILL.md顶部的 front-matter 一定要按 YAML 格式写name 和 description 是必需的description 会作为模型判断是否调用该技能的主要依据。顺序上description 要写在 name 之后其他元信息版本号、作者等按需添加即可。2.3 让 Agent 真正加载这个 Skill写好目录和文件还不够你得让 Agent Framework 在启动时扫描到这个 Skill。通常有两种方式在框架的配置文件里指定skills根路径框架启动时会递归扫描该目录下所有含SKILL.md的文件夹。使用命令行工具动态添加比如类似npx skills add这类生态工具的机制把远程或本地的 Skill 注册到当前 Agent 实例上。第一种方式适合固定项目第二种方式适合快速尝试别人写的 Skill。我个人的习惯是本地开发用配置文件集成测试和跨团队复用用命令行注册。另外要提醒一句刚加完 Skill 后如果模型迟迟不主动使用它先检查框架日志里有没有成功加载的提示不要上来就怀疑模型智商。3. 实战核心编写一个真正执行脚本的 Skill3.1 小目标让 Agent 自动运行一个数据分析脚本为了避免空谈我以一个真实例子来演示让 Agent 能够根据用户指令运行我们写好的 Python 脚本把一段 CSV 数据里的空值统计结果返回给用户。先看SKILL.md的完整内容--- name: csv-quality-report description: 分析CSV文件的数据质量统计每个字段的空值数量、空值比例、为唯一值数量。当用户要求检查数据质量、统计空值、评估CSV完整性时使用。 version: 1.0.0 --- # CSV 数据质量检查技能 本技能用于对指定 CSV 文件进行数据质量分析返回结构化报告。 ## 使用场景 - 用户上传或指定一个 CSV 文件路径询问数据是否“干净”。 - 用户要求“检查空值”“评估字段完整性”“统计缺失值”。 - 数据预处理流程中需要快速了解某文件的整体健康度。 ## 调用参数 - file_path (string, 必需): CSV 文件的路径。 - delimiter (string, 可选): 分隔符默认逗号。 ## 返回结果格式 脚本返回 JSON字段如下 | 字段 | 类型 | 说明 | |---|---|---| | columns | array | 字段名列表 | | total_rows | number | 总行数 | | missing_stats | object | 每个字段的空值统计 | | health_score | number | 0-100 的数据健康分 | ## 示例 用户说帮我检查 data/orders.csv 的数据质量。 Agent 填入{file_path: data/orders.csv}接下来是对应的 Python 脚本scripts/main.py#!/usr/bin/env python3 import csv import json import sys def read_csv(file_path, delimiter,): with open(file_path, newline, encodingutf-8) as fp: reader csv.DictReader(fp, delimiterdelimiter) rows list(reader) fieldnames reader.fieldnames or [] return fieldnames, rows def compute_missing_stats(fieldnames, rows): total len(rows) stats {} health_items [] for col in fieldnames: missing sum(1 for row in rows if not row.get(col) or not row[col].strip()) ratio missing / total if total else 0 unique_vals len({row.get(col, ).strip() for row in rows}) stats[col] { missing: missing, missing_ratio: round(ratio, 4), unique_count: unique_vals } health_items.append(1 - ratio) score round(sum(health_items) / len(health_items) * 100, 2) if health_items else 100 return stats, score def main(): args json.loads(sys.argv[1]) if len(sys.argv) 1 else {} file_path args.get(file_path, ) delimiter args.get(delimiter, ,) if not file_path: print(json.dumps({error: file_path is required})) sys.exit(1) try: fieldnames, rows read_csv(file_path, delimiter) stats, score compute_missing_stats(fieldnames, rows) result { columns: fieldnames, total_rows: len(rows), missing_stats: stats, health_score: score } print(json.dumps(result, ensure_asciiFalse)) except Exception as exc: print(json.dumps({error: str(exc)})) sys.exit(1) if __name__ __main__: main()这里的两个设计细节值得展开。第一脚本把“参数”以 JSON 字符串的形式放在sys.argv[1]里而不是用多个命令行参数。这样做的好处是参数结构清晰、不怕空格而且能复用到复杂嵌套参数上。第二输出一定是单行 JSON这是给模型看的“标准答案”。脚本里任何多余的 print 都会污染这个输出导致模型解析失败。3.2 参数从模型到脚本的完整流转路径很多人在看完上面的示例后有一个疑问Agent 是怎么知道把模型的“帮我检查文件”翻译成{file_path: data/orders.csv}的呢过程大致分三步模型读取SKILL.md通过 description 判断是否调用本技能模型按照“调用参数”部分的 schema从用户对话里抽取file_path、delimiter等字段harness 拿到这个 JSON 参数后执行python3 scripts/main.py {file_path: data/orders.csv}并把 stdout 拿回给模型。这个链路决定了你在SKILL.md里对参数的描述必须相当精确。我在参数描述上有个习惯会写明“绝对路径优先相对路径基于当前工作区解析”避免 Agent 在相对路径和绝对路径之间瞎猜。另外如果某个参数存在默认值最好在描述里直接写“默认是X用户没提就按X处理”这样模型就不会反复追问用户。3.3 进阶在 Skill 里执行前端构建类脚本热词里频繁出现 esbuild、vue 这类前端关键词其实这揭示了一个非常典型的业务场景让 Agent 直接帮你执行前端工程的构建任务。举个例子我做过一个“前端产物打包助手”的 Skill核心脚本干的事情就是读取package.json确认项目里存在build脚本调用npm run build执行构建捕获并截断输出把“构建成功/失败 耗时 产物路径”返回给模型。这类 Skill 和数据分析类有个显著区别脚本调的不是自己的业务逻辑而是外部命令。这种“脚本里再包一层子进程”的写法要注意三个坑环境变量必须显式传递给子进程特别是PATH否则 Node、npm 往往找不到会报奇怪的 “command not found”超时机制必须有我给你推荐一个 30 秒的默认值。构建任务经常因网络、缓存等问题卡死没有超时的话 Agent 会傻等输出要截断构建日志可能几千行全塞给模型既浪费 token 又干扰判断我习惯只保留最后 30 行并在返回字段里加一个truncated: true标记。用脚本包命令的方式能大幅扩大 Skill 的适用范围你以后几乎可以把任何命令行工具“包”成一个 Agent 可以调用的技能。4. 高频问题排查踩过的坑与解决实录4.1 让人血压升高的 npm warn install-scripts 系列在给 Skill 装依赖时很多人在终端看到过类似的打印npm warn install-scripts 1 package has install scripts not yet covered by allowlist Ignored build scripts: cpu-features0.0.10, esbuild0.21.5, ssh21.17.0第一次碰到时我差点以为是包损坏了后来才搞明白这跟 Agent Framework 本身无关而是新版 npm 出于供应链安全考虑改进了依赖安装策略对于某些包含install/postinstall/build脚本的包默认不会自动执行而是先忽略。被忽略的通常正是那些需要编译原生扩展的包比如cpu-featuresCPU指令集检测的原生模块、esbuild需要下载/生成平台二进制、ssh2涉及 OpenSSL 绑定。处理办法按优先级排列确认当前是不是真需要这类包。如果你的 Skill 只是做纯数据分析和文件操作esbuild、ssh2 压根没被用到那这条警告可以直接无视不用处理。本地需要构建时再显式触发。例如npm rebuild esbuild让 npm 单独把 esbuild 的二进制构建脚本补跑一遍看到 Build succeeded 后再使用。全局放开脚本执行仅限信任项目。把ignore-scriptsfalse写进项目的.npmrc就能彻底恢复旧版行为但副作用是项目里所有依赖的安装脚本都会执行安全性需要你自己权衡。把信任的包名加入允许名单。新版 npm 提供 allowlist 机制你可以只放行指定的那几个包其他包仍然禁止执行安装脚本这是我最推荐的折中方案。无论选哪种提醒一句在 CI/CD 环境里这类警告可能因为构建环境不一致而表现得时有时无最好在流水线里固定 npm 版本和.npmrc配置避免“本地没事一跑流水线就崩”。4.2 环境变量缺失导致脚本调用了错误的命令在上面“前端构建助手”里我提过环境变量的问题这里展开说一个真实案例。Skill 脚本用subprocess调用npm run build放到 Agent Framework 里跑的时候怎么都报 “npm: command not found”。在命令行里手动执行同一个脚本却一切正常。排查后发现原因Agent Framework 的 harness 启动时通过系统的 launchd/systemd 服务拉起服务环境里的PATH变量和用户终端里的不太一样只有默认的系统路径不包含 Node 的安装目录。解决方法是在脚本开头显式加载用户的 shell 环境我用的方案是import os import subprocess def run_cmd(cmd): if os.name posix: load_env source ~/.profile 2/dev/null || true full_cmd f{load_env} {cmd} else: full_cmd cmd result subprocess.run(full_cmd, shellTrue, capture_outputTrue, textTrue, timeout30) return result这样把用户的PATH和其他环境变量重新加载进来问题立刻解决。这不是 Agent Framework 的 bug而是服务进程和交互终端的固有差异任何跑脚本的框架都会遇到。4.3 脚本执行超时或白屏如何设计输出和日志策略Skill 脚本的输出如果处理不好最常见的就是模型拿着几百行原始日志开始“胡言乱语”或者因为等待时间过长直接判定技能失败。我的两个固定做法输出日志分级脚本跑批处理时把详细进度写到日志文件里写进 stdout 的只有一个结构化摘要。模型需要的从来不是细节而是“结论少量上下文”。设置双重超时脚本内部对每个子进程设置超时比如 30 秒同时 harness 层也要配置单次技能调用的最大执行时间比如 60 秒。一旦超时返回一个明确的 JSON 错误而不是让调用方干等。自动化脚本就是这样宁可失败得干脆也不要悬挂得暧昧。悬挂会给模型一个错误预期让它以为还在执行中从而重复发起调用浪费 token 和时间。4.4 权限模型Skill 脚本到底能碰什么脚本越强大风险控制就越重要。尤其当你的 Agent 要接入企业数据或者生产环境时Skill 脚本的权限边界要提前想清楚。我的经验性配置如下运行用户用低权限账号不要用 root能只读就不要让脚本有写权限网络访问默认禁止除非 Skill 明确需要拉取远程数据给每个 Skill 配独立的临时目录用完自动清空记录审计日志谁在什么时间调了什么脚本、传了什么参数。这几条听起来基础但能挡住绝大多数“手滑”事故。我见过有人在 Puppeteer 类 Skill 里忘了限制无头浏览器访问内网地址结果脚本扫了一整片内网端口还好是测试环境。权限这种东西前置设好是几分钟的事出事后再补往往就晚了。5. 生态和效率把 SkillsScripts 玩得更顺手的几个技巧5.1 别重复造轮子先看看 superpower skills 这类仓库热词里出现了“superpower skills”和“npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y”这类用法说明 Skills 生态现在已经相当繁荣。我的建议是动手写之前先去开源社区逛一圈很多常见需求数据分析、内容生成、搜索整理、前端开发已经有成熟的 Skill 实现。不过照搬前要重点确认两件事一是这个 Skill 依赖的脚本运行环境你这边是否满足比如是不是必须用某个特定版本的 Python 库二是它对模型描述文件里的措辞是否友好有些开源 Skill 的SKILL.md写得比较敷衍装完模型根本不会主动调用需要自己调一调 description。5.2 用命令行工具快速注册和管理 Skill类似npx skills add 仓库地址 --agent 目标agent这类工具本质上是把“下载 Skill → 放到正确路径 → 注册进 Agent”这条链路自动化了。就拿--agent claude-code来说说明 Skill 机制已经超越了单一框架在不同 Agent 之间是可以复用的。在 Microsoft Agent Framework 里我习惯的做法是SKILL.md这种描述文件保持通用的 Markdown 格式脚本保持纯命令行风格这样同一个 Skill 既能给 Agent Framework 用也能快速移植到其他 Agent 环境团队协作时大家不用重复实现。5.3 一套适合团队推广的 Skills 开发模板最后分享一套我在团队内部推的开发模板按这个结构写 Skill后续维护成本会低很多1. 先写 SKILL.md再写脚本 描述文件先定清楚参数和返回格式脚本才不容易跑偏。 2. 脚本必须能独立运行 不依赖 Agent 框架的特定逻辑任何环境下都能手动执行验证。 3. 输入输出必须 JSON 化 入参统一用 JSON 字符串出库统一用规范 JSON方便调试和迁移。 4. 必带一个 smoke test 脚本 用一个最小的输入样本验证 Skill 能跑通团队里所有人都能一键回归。举个例子我团队现在每个 Skill 目录下都会额外放一个tests/smoke.sh里面就干一件事用固定参数执行脚本并断言结果。 Agent 每天在跑脚本也会更新没有冒烟测试的 Skill 迟早会静默腐烂。5.4 日志是命根子给 Skill 加上运行时日志做 Agent 类项目最痛苦的是模型自主行为的不确定性它可能只调用了一次脚本也可能连着调了十几次。如果你不记日志出了问题根本复盘不了。我现在的标准做法是每个 Skill 脚本启动时把收到的入参脱敏后写进一个带时间戳的运行日志文件脚本结束前把退出码和耗时也追加进去日志路径固定写在每个 Skill 自己的logs/目录下按天滚动。这套简单方案帮我解决过好几个线上问题最典型的是“模型为什么总是传错 file_path”——翻日志发现它对相对路径的理解和预期不一致。不记日志根本看不到这一层。写在最后的个人体会坦白讲Microsoft Agent Framework 的 Skills 机制并不算复杂真正决定一个 Skill 是“能用”还是“好用”的还是脚本工程的质量。我在把 Scripts 接入这套框架的过程中最大的感受是越是想让 Agent 自由发挥越要在脚本层把边界定扎实。结构化的参数、严格的输出、明确的权限、完整的日志这四样做到位模型就天然不会再“自由发挥”出奇怪的结果这四样缺一样你可能就要花几倍时间去排查那些“看似偶然”的问题。最后再分享一个小技巧当我新写一个 Skill 时一定先把脚本单独在终端里跑通再用 Agent 去调它。只要脚本本身足够稳Agent 那层出问题的概率其实很低。希望这份实战记录能帮你少踩几个坑如果后面在脚本权限、参数传递或者 npm 构建脚本上遇到更刁钻的问题欢迎顺着这套思路再去深挖底层逻辑基本是通用的。 Microsoft Agent Framework实战：Skills+Scripts让大模型真正动手干活
如果你最近在折腾 Microsoft Agent Framework 的 Skills 机制大概率会遇到同一个困惑模型看着挺聪明描述文件也写了一大堆可真让它干点实事——比如跑个 Python 脚本、调一次命令行工具、处理一批本地文件——它就卡壳了。原因很简单Skill 如果只停留在纯提示词层面那它本质上是“知道”而不是“做到”。真正让 Skill 从“会聊”变成“会干”的恰恰是这堆不太起眼的 Scripts。我最近把一个完整的数据处理流程用 SkillsScripts 搭了出来从能跑通到跑得稳踩了不少坑也总结出一套还算顺手的实战打法这里从头到尾拆给你看。这篇文章适合两类人一类是对 Microsoft Agent Framework 刚上手、想把 Skills 做成真正可用功能模块的开发者另一类是被脚本调用搞得焦头烂额、想搞明白“Skill 和 Scripts 之间到底怎么配合”的踩坑玩家。读完你至少能解决三件事知道怎么组织一个带可执行脚本的 Skill搞清楚 Agent 调用脚本的完整链路和参数传递方式还能直接照抄一份跳过常见坑的排查方案。1. 先把概念理清Skills 和 Scripts 在 Agent Framework 里到底各管什么1.1 Skills 不是“提示词”而是一套可执行的技能包很多人在初学 Microsoft Agent Framework 时容易把 Skills 理解成“给模型的一段额外提示”其实这个理解偏差挺大的。从工程视角看Skill 更像一个“带说明书的可执行工具包”说明书部分是结构化的 Markdown 文件通常是SKILL.md它告诉大模型这个技能在什么场景下用、需要哪些输入参数、能产生什么结果可执行部分是scripts/目录下的真实脚本它们接收参数、调用系统能力、返回结果是真正落地干活的东西。这样拆开设计的价值很明显。纯提示词技能最大的问题是输出不稳定——你让模型“算一下目录大小”它可能给你编一个数也可能决定现场写一段 Python 代码再自己“脑补”运行结果。但当你把“算目录大小”的逻辑下沉到一个脚本里模型的任务就简化成“识别意图 填写参数 发起调用”最终输出的正确性由脚本保证模型的自由度被约束在可控范围内。这在生产环境里是决定能不能用的关键。1.2 Scripts 是让 Skill 具备“手”的那层执行引擎Scripts 在 Agent Framework 里的角色打个比方就是Skill 是大脑里的作战方案Scripts 是士兵手里的枪。方案再完美没有枪也打不了仗。在具体实现上Agent 框架的运行流程大概是这样的用户提需求 → 模型根据SKILL.md的描述判断该不该用这个技能 → 决定使用后填入参数 → 框架通过 harness执行环境把参数传给scripts/下的脚本 → 脚本在目标环境中运行并把 stdout、stderr、退出码返回给模型 → 模型基于结果继续推理或直接回复用户。这里有一个非常关键的设计倾向脚本最好是“无状态、纯执行”的。也就是说脚本只负责根据入参算结果不要内部维护什么会话状态、不要把废话输出到 stdout、更不要偷偷往某个临时目录塞中间文件却不告诉主进程。你越是把脚本做成黑盒式的小工具Agent 在调度它的时候就越不容易出错调试起来也越轻松。1.3 Harness连接模型决策和脚本执行的中间层热词里有个“大模型 skills harness 深入理解”哈ness确实是这套体系的核心腰眼。Harness 说白了就是那层“调度器”它负责解析SKILL.md中的参数 schema把模型的自然语言输出转成结构化的脚本调用参数建立沙箱或子进程环境控制脚本能访问的目录、网络、系统资源捕获脚本输出按约定格式回传再让模型读取。我在实战中发现理解 harness 的最好切入点是“结果回传格式”。因为脚本怎么输出、框架怎么解析直接决定了你能不能写出靠谱的 Skill。如果脚本只是往 stdout 里扔一段普通文本模型还能凑合看但如果你希望模型拿到结果后还能做二次处理比如提取摘要、判断下一步操作那就最好让脚本输出结构化 JSON并遵循固定的字段格式。这一点后面我会详细示范。2. 动手前的准备搭一个能跑 Scripts 的 Skill 项目2.1 环境要求和目录结构先列一下我这边实测可用的环境基线版本太老的话有些特性没跟上排查起来很闹心Node.js 18Agent Framework 的 SDK 和不少脚本工具链依赖它Python 3.10如果你要写的是数据处理类脚本这个版本往上会比较省心包管理器我用的是 npm 11这也是后面一个坑的源头后面细讲Agent Framework SDK 建议用最新稳定版因为 Skills 机制迭代还挺快的。Skill 项目的目录结构我用的是官方推荐风格自己也做了一些扩展skills/ └── exec-python/ ├── SKILL.md ├── scripts/ │ ├── main.py │ └── requirements.txt (可选) ├── assets/ (可选放配套说明、模板等) └── reference.md (可选补充给模型看的上下文)关于目录结构有三点经验。第一每个 Skill 一定要独立成目录不要多个 Skill 的脚本混在一个目录里否则模型在判断调用哪个入口时很容易搞混。第二scripts/子目录是惯例Agent Framework 的 harness 默认会从这个目录找可执行入口特殊设置反而容易出问题。第三assets/和reference.md属于加分项用于给模型提供更详细的参考资料前期可以先不搞等核心跑通了再逐步加上。2.2 核心文件 SKILL.md 怎么写才不会被模型误用SKILL.md是整个 Skill 的说明书它的质量直接决定模型用得好不好。一个常见的误区是描述写得太虚模型根本判断不准什么时候该调。我写描述时遵循三个原则场景要具体写“用于统计CSV文件中各列的空值比例并输出数据质量报告”而不是笼统的“用于数据处理”。参数要写清把每个参数的格式、单位、必填与否都列明白。例如file_path: string (必填, 绝对路径或相对路径)。边界要说明明确指出“不要用于处理图片”或“仅支持UTF-8编码文件”减少模型乱调用。另外SKILL.md顶部的 front-matter 一定要按 YAML 格式写name 和 description 是必需的description 会作为模型判断是否调用该技能的主要依据。顺序上description 要写在 name 之后其他元信息版本号、作者等按需添加即可。2.3 让 Agent 真正加载这个 Skill写好目录和文件还不够你得让 Agent Framework 在启动时扫描到这个 Skill。通常有两种方式在框架的配置文件里指定skills根路径框架启动时会递归扫描该目录下所有含SKILL.md的文件夹。使用命令行工具动态添加比如类似npx skills add这类生态工具的机制把远程或本地的 Skill 注册到当前 Agent 实例上。第一种方式适合固定项目第二种方式适合快速尝试别人写的 Skill。我个人的习惯是本地开发用配置文件集成测试和跨团队复用用命令行注册。另外要提醒一句刚加完 Skill 后如果模型迟迟不主动使用它先检查框架日志里有没有成功加载的提示不要上来就怀疑模型智商。3. 实战核心编写一个真正执行脚本的 Skill3.1 小目标让 Agent 自动运行一个数据分析脚本为了避免空谈我以一个真实例子来演示让 Agent 能够根据用户指令运行我们写好的 Python 脚本把一段 CSV 数据里的空值统计结果返回给用户。先看SKILL.md的完整内容--- name: csv-quality-report description: 分析CSV文件的数据质量统计每个字段的空值数量、空值比例、为唯一值数量。当用户要求检查数据质量、统计空值、评估CSV完整性时使用。 version: 1.0.0 --- # CSV 数据质量检查技能 本技能用于对指定 CSV 文件进行数据质量分析返回结构化报告。 ## 使用场景 - 用户上传或指定一个 CSV 文件路径询问数据是否“干净”。 - 用户要求“检查空值”“评估字段完整性”“统计缺失值”。 - 数据预处理流程中需要快速了解某文件的整体健康度。 ## 调用参数 - file_path (string, 必需): CSV 文件的路径。 - delimiter (string, 可选): 分隔符默认逗号。 ## 返回结果格式 脚本返回 JSON字段如下 | 字段 | 类型 | 说明 | |---|---|---| | columns | array | 字段名列表 | | total_rows | number | 总行数 | | missing_stats | object | 每个字段的空值统计 | | health_score | number | 0-100 的数据健康分 | ## 示例 用户说帮我检查 data/orders.csv 的数据质量。 Agent 填入{file_path: data/orders.csv}接下来是对应的 Python 脚本scripts/main.py#!/usr/bin/env python3 import csv import json import sys def read_csv(file_path, delimiter,): with open(file_path, newline, encodingutf-8) as fp: reader csv.DictReader(fp, delimiterdelimiter) rows list(reader) fieldnames reader.fieldnames or [] return fieldnames, rows def compute_missing_stats(fieldnames, rows): total len(rows) stats {} health_items [] for col in fieldnames: missing sum(1 for row in rows if not row.get(col) or not row[col].strip()) ratio missing / total if total else 0 unique_vals len({row.get(col, ).strip() for row in rows}) stats[col] { missing: missing, missing_ratio: round(ratio, 4), unique_count: unique_vals } health_items.append(1 - ratio) score round(sum(health_items) / len(health_items) * 100, 2) if health_items else 100 return stats, score def main(): args json.loads(sys.argv[1]) if len(sys.argv) 1 else {} file_path args.get(file_path, ) delimiter args.get(delimiter, ,) if not file_path: print(json.dumps({error: file_path is required})) sys.exit(1) try: fieldnames, rows read_csv(file_path, delimiter) stats, score compute_missing_stats(fieldnames, rows) result { columns: fieldnames, total_rows: len(rows), missing_stats: stats, health_score: score } print(json.dumps(result, ensure_asciiFalse)) except Exception as exc: print(json.dumps({error: str(exc)})) sys.exit(1) if __name__ __main__: main()这里的两个设计细节值得展开。第一脚本把“参数”以 JSON 字符串的形式放在sys.argv[1]里而不是用多个命令行参数。这样做的好处是参数结构清晰、不怕空格而且能复用到复杂嵌套参数上。第二输出一定是单行 JSON这是给模型看的“标准答案”。脚本里任何多余的 print 都会污染这个输出导致模型解析失败。3.2 参数从模型到脚本的完整流转路径很多人在看完上面的示例后有一个疑问Agent 是怎么知道把模型的“帮我检查文件”翻译成{file_path: data/orders.csv}的呢过程大致分三步模型读取SKILL.md通过 description 判断是否调用本技能模型按照“调用参数”部分的 schema从用户对话里抽取file_path、delimiter等字段harness 拿到这个 JSON 参数后执行python3 scripts/main.py {file_path: data/orders.csv}并把 stdout 拿回给模型。这个链路决定了你在SKILL.md里对参数的描述必须相当精确。我在参数描述上有个习惯会写明“绝对路径优先相对路径基于当前工作区解析”避免 Agent 在相对路径和绝对路径之间瞎猜。另外如果某个参数存在默认值最好在描述里直接写“默认是X用户没提就按X处理”这样模型就不会反复追问用户。3.3 进阶在 Skill 里执行前端构建类脚本热词里频繁出现 esbuild、vue 这类前端关键词其实这揭示了一个非常典型的业务场景让 Agent 直接帮你执行前端工程的构建任务。举个例子我做过一个“前端产物打包助手”的 Skill核心脚本干的事情就是读取package.json确认项目里存在build脚本调用npm run build执行构建捕获并截断输出把“构建成功/失败 耗时 产物路径”返回给模型。这类 Skill 和数据分析类有个显著区别脚本调的不是自己的业务逻辑而是外部命令。这种“脚本里再包一层子进程”的写法要注意三个坑环境变量必须显式传递给子进程特别是PATH否则 Node、npm 往往找不到会报奇怪的 “command not found”超时机制必须有我给你推荐一个 30 秒的默认值。构建任务经常因网络、缓存等问题卡死没有超时的话 Agent 会傻等输出要截断构建日志可能几千行全塞给模型既浪费 token 又干扰判断我习惯只保留最后 30 行并在返回字段里加一个truncated: true标记。用脚本包命令的方式能大幅扩大 Skill 的适用范围你以后几乎可以把任何命令行工具“包”成一个 Agent 可以调用的技能。4. 高频问题排查踩过的坑与解决实录4.1 让人血压升高的 npm warn install-scripts 系列在给 Skill 装依赖时很多人在终端看到过类似的打印npm warn install-scripts 1 package has install scripts not yet covered by allowlist Ignored build scripts: cpu-features0.0.10, esbuild0.21.5, ssh21.17.0第一次碰到时我差点以为是包损坏了后来才搞明白这跟 Agent Framework 本身无关而是新版 npm 出于供应链安全考虑改进了依赖安装策略对于某些包含install/postinstall/build脚本的包默认不会自动执行而是先忽略。被忽略的通常正是那些需要编译原生扩展的包比如cpu-featuresCPU指令集检测的原生模块、esbuild需要下载/生成平台二进制、ssh2涉及 OpenSSL 绑定。处理办法按优先级排列确认当前是不是真需要这类包。如果你的 Skill 只是做纯数据分析和文件操作esbuild、ssh2 压根没被用到那这条警告可以直接无视不用处理。本地需要构建时再显式触发。例如npm rebuild esbuild让 npm 单独把 esbuild 的二进制构建脚本补跑一遍看到 Build succeeded 后再使用。全局放开脚本执行仅限信任项目。把ignore-scriptsfalse写进项目的.npmrc就能彻底恢复旧版行为但副作用是项目里所有依赖的安装脚本都会执行安全性需要你自己权衡。把信任的包名加入允许名单。新版 npm 提供 allowlist 机制你可以只放行指定的那几个包其他包仍然禁止执行安装脚本这是我最推荐的折中方案。无论选哪种提醒一句在 CI/CD 环境里这类警告可能因为构建环境不一致而表现得时有时无最好在流水线里固定 npm 版本和.npmrc配置避免“本地没事一跑流水线就崩”。4.2 环境变量缺失导致脚本调用了错误的命令在上面“前端构建助手”里我提过环境变量的问题这里展开说一个真实案例。Skill 脚本用subprocess调用npm run build放到 Agent Framework 里跑的时候怎么都报 “npm: command not found”。在命令行里手动执行同一个脚本却一切正常。排查后发现原因Agent Framework 的 harness 启动时通过系统的 launchd/systemd 服务拉起服务环境里的PATH变量和用户终端里的不太一样只有默认的系统路径不包含 Node 的安装目录。解决方法是在脚本开头显式加载用户的 shell 环境我用的方案是import os import subprocess def run_cmd(cmd): if os.name posix: load_env source ~/.profile 2/dev/null || true full_cmd f{load_env} {cmd} else: full_cmd cmd result subprocess.run(full_cmd, shellTrue, capture_outputTrue, textTrue, timeout30) return result这样把用户的PATH和其他环境变量重新加载进来问题立刻解决。这不是 Agent Framework 的 bug而是服务进程和交互终端的固有差异任何跑脚本的框架都会遇到。4.3 脚本执行超时或白屏如何设计输出和日志策略Skill 脚本的输出如果处理不好最常见的就是模型拿着几百行原始日志开始“胡言乱语”或者因为等待时间过长直接判定技能失败。我的两个固定做法输出日志分级脚本跑批处理时把详细进度写到日志文件里写进 stdout 的只有一个结构化摘要。模型需要的从来不是细节而是“结论少量上下文”。设置双重超时脚本内部对每个子进程设置超时比如 30 秒同时 harness 层也要配置单次技能调用的最大执行时间比如 60 秒。一旦超时返回一个明确的 JSON 错误而不是让调用方干等。自动化脚本就是这样宁可失败得干脆也不要悬挂得暧昧。悬挂会给模型一个错误预期让它以为还在执行中从而重复发起调用浪费 token 和时间。4.4 权限模型Skill 脚本到底能碰什么脚本越强大风险控制就越重要。尤其当你的 Agent 要接入企业数据或者生产环境时Skill 脚本的权限边界要提前想清楚。我的经验性配置如下运行用户用低权限账号不要用 root能只读就不要让脚本有写权限网络访问默认禁止除非 Skill 明确需要拉取远程数据给每个 Skill 配独立的临时目录用完自动清空记录审计日志谁在什么时间调了什么脚本、传了什么参数。这几条听起来基础但能挡住绝大多数“手滑”事故。我见过有人在 Puppeteer 类 Skill 里忘了限制无头浏览器访问内网地址结果脚本扫了一整片内网端口还好是测试环境。权限这种东西前置设好是几分钟的事出事后再补往往就晚了。5. 生态和效率把 SkillsScripts 玩得更顺手的几个技巧5.1 别重复造轮子先看看 superpower skills 这类仓库热词里出现了“superpower skills”和“npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y”这类用法说明 Skills 生态现在已经相当繁荣。我的建议是动手写之前先去开源社区逛一圈很多常见需求数据分析、内容生成、搜索整理、前端开发已经有成熟的 Skill 实现。不过照搬前要重点确认两件事一是这个 Skill 依赖的脚本运行环境你这边是否满足比如是不是必须用某个特定版本的 Python 库二是它对模型描述文件里的措辞是否友好有些开源 Skill 的SKILL.md写得比较敷衍装完模型根本不会主动调用需要自己调一调 description。5.2 用命令行工具快速注册和管理 Skill类似npx skills add 仓库地址 --agent 目标agent这类工具本质上是把“下载 Skill → 放到正确路径 → 注册进 Agent”这条链路自动化了。就拿--agent claude-code来说说明 Skill 机制已经超越了单一框架在不同 Agent 之间是可以复用的。在 Microsoft Agent Framework 里我习惯的做法是SKILL.md这种描述文件保持通用的 Markdown 格式脚本保持纯命令行风格这样同一个 Skill 既能给 Agent Framework 用也能快速移植到其他 Agent 环境团队协作时大家不用重复实现。5.3 一套适合团队推广的 Skills 开发模板最后分享一套我在团队内部推的开发模板按这个结构写 Skill后续维护成本会低很多1. 先写 SKILL.md再写脚本 描述文件先定清楚参数和返回格式脚本才不容易跑偏。 2. 脚本必须能独立运行 不依赖 Agent 框架的特定逻辑任何环境下都能手动执行验证。 3. 输入输出必须 JSON 化 入参统一用 JSON 字符串出库统一用规范 JSON方便调试和迁移。 4. 必带一个 smoke test 脚本 用一个最小的输入样本验证 Skill 能跑通团队里所有人都能一键回归。举个例子我团队现在每个 Skill 目录下都会额外放一个tests/smoke.sh里面就干一件事用固定参数执行脚本并断言结果。 Agent 每天在跑脚本也会更新没有冒烟测试的 Skill 迟早会静默腐烂。5.4 日志是命根子给 Skill 加上运行时日志做 Agent 类项目最痛苦的是模型自主行为的不确定性它可能只调用了一次脚本也可能连着调了十几次。如果你不记日志出了问题根本复盘不了。我现在的标准做法是每个 Skill 脚本启动时把收到的入参脱敏后写进一个带时间戳的运行日志文件脚本结束前把退出码和耗时也追加进去日志路径固定写在每个 Skill 自己的logs/目录下按天滚动。这套简单方案帮我解决过好几个线上问题最典型的是“模型为什么总是传错 file_path”——翻日志发现它对相对路径的理解和预期不一致。不记日志根本看不到这一层。写在最后的个人体会坦白讲Microsoft Agent Framework 的 Skills 机制并不算复杂真正决定一个 Skill 是“能用”还是“好用”的还是脚本工程的质量。我在把 Scripts 接入这套框架的过程中最大的感受是越是想让 Agent 自由发挥越要在脚本层把边界定扎实。结构化的参数、严格的输出、明确的权限、完整的日志这四样做到位模型就天然不会再“自由发挥”出奇怪的结果这四样缺一样你可能就要花几倍时间去排查那些“看似偶然”的问题。最后再分享一个小技巧当我新写一个 Skill 时一定先把脚本单独在终端里跑通再用 Agent 去调它。只要脚本本身足够稳Agent 那层出问题的概率其实很低。希望这份实战记录能帮你少踩几个坑如果后面在脚本权限、参数传递或者 npm 构建脚本上遇到更刁钻的问题欢迎顺着这套思路再去深挖底层逻辑基本是通用的。