当前位置：首页 > news >正文

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

news 2026/4/15 2:12:54

新手入门AI Skill最头疼的问题：不知道从哪下手、写的代码跑不起来、不清楚各个文件的作用。今天就用“餐厅服务员”的通俗类比，手把手带大家写2个可直接运行的AI Skill，还会补充CSDN博主常用的规范目录结构，新手也能零门槛上手，看完就能复刻！

先给大家划重点：AI Skill的核心是“分工明确”，就像餐厅的运营逻辑一样，每个环节都有对应的角色，缺一不可。先搞懂这个类比，后面的实操会轻松10倍！另外补充关键要点：多个Skill的核心格式（规范目录）需统一，同时需搭建“统一调度器”，避免每个Skill单独调度，提升复用性和维护性（这是新手开发多Skill的核心误区）。

一、通俗类比：搞懂AI Skill的3个核心角色（多Skill适配版）

你去餐厅吃饭，离不开3个关键角色：服务员（带菜单）、厨师（做菜品）、传菜员（传订单、送菜品）。AI世界里的Skill开发，和这个逻辑完全对应；如果有多个Skill（比如查天气、加法计算、查快递），就相当于餐厅有多个“菜品”，需要一个“总传菜员”（统一调度器），一个“统一菜单”（多Skill说明），咱们一一对应看，瞬间就懂：

单个Skill（规范目录下的SKILL.md+scripts）= 单个菜品的“专属说明+专属厨师”：每个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="成都"# 临时执行函数，验证可用性result=query_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. 临时调用函数result=query_weather(city)# 4. 输出结果print(f"用户提问：{user_question}")print(f"AI回复：{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.py）defadd(a,b):""" 计算两个数字的和 :param a: 第一个数字（整数/小数） :param b: 第二个数字（整数/小数） :return: 加法计算结果（字符串） """# 参数校验：确保传入的是数字ifnotisinstance(a,(int,float))ornotisinstance(b,(int,float)):return"参数错误，请传入有效的数字（整数或小数）"returnf"{a}+{b}={a+b}"

第三步：暂不单独写调度器（和第一个Skill保持一致）

和查天气Skill一样，不单独编写调度器，后续由统一调度器统一管理，避免重复开发，保证多Skill结构统一。

第四步：测试闭环+临时调用演示

同样做内部自测和临时外部调用，验证Skill可用性，且格式和查天气Skill完全统一：

子步骤1：内部自测（add-calculator/scripts/test.py）

新建test.py文件，复制下面的代码粘贴进去：

# 从skills.py导入加法计算函数（临时自测）fromskillsimportadd# 模拟AI传入的参数a=10b=20# 临时执行函数，验证可用性result=add(a,b)print("AI最终回答用户：",result)

✅ 预期运行结果：AI最终回答用户：10 + 20 = 30

如果传入小数，比如a=1.5、b=2.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的结果"a=10b=20# 临时调用函数result=add(a,b)# 输出结果print(f"用户提问：{user_question}")print(f"AI回复：{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_name=ai_order["name"]params=ai_order["params"]exceptKeyError:return"错误：AI输出的订单格式不正确，请遵循统一调用格式！"# 找到对应的Skill执行函数（厨师）skill_func=SKILL_MAP.get(skill_name)ifnotskill_func:returnf"抱歉，没有【{skill_name}】这个功能哦～"# 执行函数，返回结果try:result=skill_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生成统一格式的订单（适配所有Skill）user_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):result=run_skill(order)print(f"用户提问：{question}")print(f"AI回复：{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及以上）。