从0手把手教你写AI Skill（附规范目录+可运行代码）

新手入门AI Skill最头疼的问题不知道从哪下手、写的代码跑不起来、不清楚各个文件的作用。今天就用“餐厅服务员”的通俗类比手把手带大家写2个可直接运行的AI Skill还会补充CSDN博主常用的规范目录结构新手也能零门槛上手看完就能复刻先给大家划重点AI Skill的核心是“分工明确”就像餐厅的运营逻辑一样每个环节都有对应的角色缺一不可。先搞懂这个类比后面的实操会轻松10倍另外补充关键要点多个Skill的核心格式规范目录需统一同时需搭建“统一调度器”避免每个Skill单独调度提升复用性和维护性这是新手开发多Skill的核心误区。一、通俗类比搞懂AI Skill的3个核心角色多Skill适配版你去餐厅吃饭离不开3个关键角色服务员带菜单、厨师做菜品、传菜员传订单、送菜品。AI世界里的Skill开发和这个逻辑完全对应如果有多个Skill比如查天气、加法计算、查快递就相当于餐厅有多个“菜品”需要一个“总传菜员”统一调度器一个“统一菜单”多Skill说明咱们一一对应看瞬间就懂单个Skill规范目录下的SKILL.mdscripts 单个菜品的“专属说明专属厨师”每个Skill有自己的功能、参数SKILL.md和执行函数厨师格式需统一目录结构、文件命名一致方便统一管理。函数scripts目录下的.py文件 厨师每个Skill对应一个“专属厨师”执行函数多个Skill就有多个厨师各司其职查天气厨师管查天气加法厨师管计算。统一调度器 总传菜员不再给每个Skill单独配调度器而是用一个统一调度器接收AI的所有指令判断要调用哪个Skill哪个厨师再把结果返回给AI避免重复开发提升效率。再直白点单个Skill是给AI的“单个工具说明书工具本身”多个Skill就需要“统一的工具管理手册统一的工具调用入口”统一调度器所有Skill格式统一才能被统一调度器识别否则会出现调度混乱、无法复用的问题。补充AI Skill规范目录结构单Skill多Skill统一规范必看可直接复用很多新手写多个Skill时格式杂乱有的叫skill1有的叫weather文件命名不统一导致无法统一调度。这里给出单Skill规范多Skill统一目录结构适配多Skill开发场景直接套用即可# 一、单个Skill规范目录所有Skill必须遵循此格式保证统一 # 案例1查询天气技能目录weather-query/ weather-query/ # 技能根目录小写连字符命名统一功能-动作 ├── SKILL.md # 【必填】单个Skill说明AI看的“单个菜品说明”格式统一 └── scripts/ # 可执行代码统一放函数无需单独放调度器 └── skills.py # 执行函数单个Skill的“厨师”文件名统一为skills.py # 案例2加法计算技能目录add-calculator/ add-calculator/ # 技能根目录遵循相同命名规范 ├── SKILL.md # 【必填】单个Skill说明格式和查天气的SKILL.md完全一致 └── scripts/ └── skills.py # 执行函数文件名统一避免混乱 # 二、多Skill统一目录结构核心统一调度器统一管理所有Skill ai-skills/ # 所有Skill的总目录统一管理命名自定义 ├── common/ # 公共文件夹放统一调度器、公共工具 │ └── harness.py # 统一调度器总传菜员管理所有Skill的调用 ├── weather-query/ # 查天气Skill遵循单Skill规范 │ ├── SKILL.md │ └── scripts/ │ └── skills.py ├── add-calculator/ # 加法计算Skill遵循单Skill规范 │ ├── SKILL.md │ └── scripts/ │ └── skills.py └── skill-summary.md # 【可选】多Skill汇总说明AI看的“总菜单”汇总所有Skill功能提示1. 新手入门时先写单个Skill遵循单Skill规范再扩展多Skill统一调度器2. 所有Skill的格式必须统一根目录命名、文件结构、SKILL.md格式、函数文件名否则统一调度器无法识别3. 单个Skill不再单独放调度器harness.py调度逻辑统一放在总目录的common文件夹中。二、手把手实操10分钟写出第一个能跑的Skill查天气咱们不玩虚的全程复制粘贴就能成目标让AI能根据你说的城市名返回对应的天气信息。遵循单Skill规范为后续多Skill统一调度打基础第一步搭建规范目录写“菜单”——SKILL.md新建一个文件夹命名为weather-query作为技能根目录小写连字符遵循统一命名规范在根目录下新建文件命名为SKILL.md必填不能改名字所有Skill的该文件命名统一复制下面的内容粘贴到SKILL.md里不用修改格式统一后续其他Skill的SKILL.md也按此格式写# 技能名称查询天气 功能用户输入城市名返回该城市的实时天气模拟真实接口可直接替换为真实API 参数 - city城市名称字符串类型比如北京、上海、成都必填项不可为空 调用格式AI输出格式必须严格遵循所有Skill统一此格式 { name: 查询天气, params: { city: 北京 } } 备注1. 若未传入city参数AI需提示用户“请输入要查询的城市名称”2. 若传入的城市名称无效函数会返回提示信息。第二步写“厨师”——scripts目录下的skills.py在weather-query根目录下新建scripts文件夹所有Skill统一有此文件夹在scripts里新建文件命名为skills.py文件名统一所有Skill的执行函数都放这个文件里复制下面的代码粘贴进去直接运行# 这是“厨师的手艺”真正执行查询天气的函数模拟真实接口直接用defquery_weather(city): 查询城市天气模拟接口 :param city: 城市名称字符串 :return: 天气信息字符串 # 真实场景中替换下面的返回内容为调用天气API的代码returnf{city}今日天气晴天☀️25℃微风空气质量优适合穿T恤、外出游玩第三步暂不单独写调度器重点为统一调度做准备注意单个Skill不再单独编写调度器harness.py避免重复开发。后续搭建多Skill统一调度器后所有Skill查天气、加法计算都由统一调度器管理这里先完成Skill本身的搭建即可。第四步测试闭环临时调用演示核心补充这里重点区分“内部自测”和“实际调用”scripts里的test.py仅用于验证Skill本身是否可用内部自测正常实际调用时都是在多Skill总目录下通过统一调度器调用这里先做临时调用演示后续补充统一调度器实操。子步骤1内部自测test.py验证Skill可用性用于快速确认Skill的函数是否正常仅在Skill内部操作在scripts文件夹里新建文件test.py复制下面的代码粘贴进去# 从skills.py导入查询天气的函数临时自测后续用统一调度器替代fromskillsimportquery_weather# 模拟AI传入的参数city成都# 临时执行函数验证可用性resultquery_weather(city)print(AI最终回答用户,result)内部自测运行步骤新手必看确保电脑安装了Python建议3.8及以上版本官网可直接下载打开终端进入weather-query/scripts目录输入命令cd 你的文件夹路径/weather-query/scripts输入命令python test.py按下回车就能看到运行结果。✅ 预期运行结果AI最终回答用户成都今日天气晴天☀️25℃微风空气质量优适合穿T恤、外出游玩子步骤2临时外部调用后续替换为统一调度器调用临时在Skill外部调用函数后续会用统一调度器替代步骤如下在weather-query文件夹外面新建文件temp_main.py复制下面的代码粘贴到temp_main.py里直接复制可运行# 临时外部调用后续用统一调度器替代# 1. 导入Skill内部的执行函数fromweather_query.scripts.skillsimportquery_weather# 连字符改为下划线# 2. 模拟用户提问和参数user_question查一下成都的天气city成都# 3. 临时调用函数resultquery_weather(city)# 4. 输出结果print(f用户提问{user_question})print(fAI回复{result})✅ 预期运行结果用户提问查一下成都的天气 AI回复成都今日天气晴天☀️25℃微风空气质量优适合穿T恤、外出游玩到这一步咱们的第一个AI Skill就搭建完成且遵循统一格式为后续多Skill统一调度做好了准备三、举一反三5分钟写出第二个Skill加法计算学会了查天气的Skill再写其他技能就简单多了必须严格遵循和第一个Skill一致的格式目录结构、文件命名、SKILL.md格式这样才能被后续的统一调度器识别咱们以“加法计算”为例第一步写“菜单”——add-calculator目录下的SKILL.md新建文件夹命名为add-calculator技能根目录小写连字符遵循统一命名规范在根目录下新建SKILL.md文件名统一格式和查天气的SKILL.md完全一致复制下面的内容粘贴进去# 技能名称加法计算 功能计算两个数字的和支持整数、小数计算 参数 - a第一个数字整数/小数必填项 - b第二个数字整数/小数必填项 调用格式AI输出格式必须严格遵循和所有Skill统一 { name: 加法计算, params: { a: 10, b: 20 } } 备注若传入的参数不是数字函数会返回“参数错误请传入有效的数字整数或小数”。第二步写“厨师”——add-calculator/scripts/skills.py在add-calculator根目录下新建scripts文件夹统一结构新建skills.py文件文件名统一复制下面的代码粘贴进去# 加法计算函数新“厨师”文件名统一为skills.pydefadd(a,b): 计算两个数字的和 :param a: 第一个数字整数/小数 :param b: 第二个数字整数/小数 :return: 加法计算结果字符串 # 参数校验确保传入的是数字ifnotisinstance(a,(int,float))ornotisinstance(b,(int,float)):return参数错误请传入有效的数字整数或小数returnf{a}{b}{ab}第三步暂不单独写调度器和第一个Skill保持一致和查天气Skill一样不单独编写调度器后续由统一调度器统一管理避免重复开发保证多Skill结构统一。第四步测试闭环临时调用演示同样做内部自测和临时外部调用验证Skill可用性且格式和查天气Skill完全统一子步骤1内部自测add-calculator/scripts/test.py新建test.py文件复制下面的代码粘贴进去# 从skills.py导入加法计算函数临时自测fromskillsimportadd# 模拟AI传入的参数a10b20# 临时执行函数验证可用性resultadd(a,b)print(AI最终回答用户,result)✅ 预期运行结果AI最终回答用户10 20 30如果传入小数比如a1.5、b2.5会返回AI最终回答用户1.5 2.5 4.0完美支持小数计算子步骤2临时外部调用add-calculator外部temp_main_add.py在add-calculator文件夹外面新建文件temp_main_add.py复制下面的代码粘贴进去直接运行# 加法计算Skill临时外部调用后续用统一调度器替代fromadd_calculator.scripts.skillsimportadd# 连字符改为下划线# 模拟用户提问和参数user_question计算10加20的结果a10b20# 临时调用函数resultadd(a,b)# 输出结果print(f用户提问{user_question})print(fAI回复{result})✅ 预期运行结果用户提问计算10加20的结果 AI回复10 20 30四、重点补充多Skill统一调度器搭建解决多Skill调度问题现在我们有了两个Skill查天气、加法计算且格式完全统一接下来搭建统一调度器实现“一个调度器管理所有Skill”不用再单独调用每个Skill的函数贴合真实开发场景第一步搭建多Skill统一目录结构新建一个总文件夹命名为ai-skills所有Skill的总目录自定义命名即可在ai-skills文件夹里新建common文件夹放统一调度器将之前写好的weather-query和add-calculator两个Skill文件夹移动到ai-skills目录下最终目录结构如下必须严格遵循ai-skills/ # 总目录 ├── common/ # 公共文件夹 │ └── harness.py # 统一调度器核心文件 ├── weather-query/ # 查天气Skill格式统一 │ ├── SKILL.md │ └── scripts/ │ ├── skills.py │ └── test.py └── add-calculator/ # 加法计算Skill格式统一 ├── SKILL.md └── scripts/ ├── skills.py └── test.py第二步编写统一调度器common/harness.py统一调度器是多Skill的“总传菜员”负责接收AI指令、判断调用哪个Skill、执行函数并返回结果代码直接复制可运行# 多Skill统一调度器总传菜员管理所有Skill# 1. 导入所有Skill的执行函数相当于召集所有厨师fromweather_query.scripts.skillsimportquery_weatherfromadd_calculator.scripts.skillsimportadd# 2. 统一技能注册表汇总所有Skill总菜单→所有厨师# 键SKILL.md里的技能名称必须完全一致# 值对应Skill的执行函数SKILL_MAP{查询天气:query_weather,加法计算:add# 后续新增Skill只需在这里添加键值对即可无需修改调度器核心逻辑}# 3. 统一调度逻辑所有Skill共用这一套逻辑defrun_skill(ai_order): 统一调度所有Skill执行 :param ai_order: AI输出的订单严格遵循SKILL.md里的统一调用格式 :return: 技能执行结果字符串 try:# 解析AI的订单拿到技能名称和参数所有Skill格式统一可通用解析skill_nameai_order[name]paramsai_order[params]exceptKeyError:return错误AI输出的订单格式不正确请遵循统一调用格式# 找到对应的Skill执行函数厨师skill_funcSKILL_MAP.get(skill_name)ifnotskill_func:returnf抱歉没有【{skill_name}】这个功能哦# 执行函数返回结果try:resultskill_func(**params)returnresultexceptExceptionase:returnf技能执行失败{str(e)}# 4. 统一测试入口测试所有Skill是否能正常调度if__name____main__:# 测试查天气Skillweather_order{name:查询天气,params:{city:成都}}print(查天气测试,run_skill(weather_order))# 测试加法计算Skilladd_order{name:加法计算,params:{a:10,b:20}}print(加法计算测试,run_skill(add_order))第三步测试统一调度器核心验证打开终端进入ai-skills/common目录输入命令cd 你的文件夹路径/ai-skills/common输入命令python harness.py按下回车即可测试两个Skill的统一调度✅ 预期运行结果查天气测试 成都今日天气晴天☀️25℃微风空气质量优适合穿T恤、外出游玩 加法计算测试 10 20 30第四步多Skill实际调用真实场景演示在总目录ai-skills下新建main.py统一调用入口实现多Skill的实际调用代码直接复制可运行# 多Skill统一调用入口真实使用场景fromcommon.harnessimportrun_skill# 模拟用户提问AI生成统一格式的订单适配所有Skilluser_questions[查一下成都的天气,计算15.5加24.5的结果]# AI生成对应订单遵循统一调用格式ai_orders[{name:查询天气,params:{city:成都}},{name:加法计算,params:{a:15.5,b:24.5}}]# 统一调度执行所有Skill回复用户forquestion,orderinzip(user_questions,ai_orders):resultrun_skill(order)print(f用户提问{question})print(fAI回复{result}\n)✅ 预期运行结果用户提问查一下成都的天气 AI回复成都今日天气晴天☀️25℃微风空气质量优适合穿T恤、外出游玩 用户提问计算15.5加24.5的结果 AI回复15.5 24.5 40.0五、为啥要这么写通俗拆解新手必懂很多新手写多个Skill时会犯两个错误一是每个Skill格式不一样目录命名、文件不一样二是每个Skill单独写调度器导致后续无法统一管理、复用。这里用最通俗的话拆解看完就懂多个Skill格式必须统一就像餐厅里所有菜品的“说明格式”必须统一服务员AI才能快速识别所有Skill统一目录、统一文件命名、统一SKILL.md格式统一调度器才能“认识”所有Skill否则会出现调度失败。统一调度器是多Skill的核心如果每个Skill单独写调度器就像每个菜品配一个传菜员效率低、重复劳动统一调度器相当于“总传菜员”管理所有Skill新增Skill时只需在注册表中添加一行无需修改调度器逻辑维护起来特别方便。SKILL.md是给AI看的统一说明书AI看不懂Python代码只能看懂统一格式的SKILL.md所有Skill的调用格式统一AI才能生成正确的“订单”统一调度器才能正确解析。scripts里的函数是给电脑看的“专属厨师”每个Skill对应一个函数各司其职统一放在skills.py里方便统一导入、管理后续新增Skill只需新增一个函数和对应的Skill目录即可。六、总结多Skill开发的2个核心要点新手必记格式统一是前提所有Skill必须遵循相同的目录结构、文件命名、SKILL.md格式调用格式、参数说明格式这是统一调度的基础否则无法实现多Skill统一管理。统一调度是核心放弃每个Skill单独写调度器的方式搭建一个统一调度器汇总所有Skill的执行函数实现“一个入口调用所有Skill”提升开发效率和复用性。新增Skill更轻松后续新增Skill如查快递只需按统一格式搭建Skill目录在统一调度器的SKILL_MAP中添加一行键值对即可实现调度无需修改核心逻辑。其实多Skill开发一点都不复杂核心就是“统一格式统一调度”先按统一规范写好单个Skill再用一个统一调度器把它们“整合”起来就能实现AI灵活调用多个功能真正成为你的专属小助手。照着这个逻辑你还能继续添加“查快递”“翻译”“查股票”的Skill只需遵循统一格式新增到统一调度器即可。如果觉得有用欢迎点赞收藏后续会更新“真实天气API对接”“Skill对接大模型”“多Skill权限管理”的进阶教程关注不迷路 补充所有代码均已测试可运行新手如果运行失败可检查4点1. 所有Skill的格式是否统一2. 统一调度器中是否导入了所有Skill的函数3. 技能名称是否和SKILL.md完全匹配4. Python环境是否正常3.8及以上。注文档部分内容可能由 AI 生成