AI Skill开发规范与实战：从餐厅运营到代码实现

1. AI Skill开发入门：从餐厅运营到代码实现

作为一名在AI领域摸爬滚打多年的开发者，我深知新手入门AI Skill开发时的困惑。很多人一上来就急着写代码，结果发现跑不起来，或者写出来的Skill难以维护和扩展。今天，我想分享一套经过实战检验的AI Skill开发方法，用餐厅运营的类比帮你快速理解核心概念。

1.1 餐厅运营与AI Skill的对应关系

想象一下你去餐厅吃饭的场景，这个过程中涉及三个关键角色：服务员、厨师和传菜员。在AI Skill开发中，这三个角色分别对应着：

• 服务员（带菜单）：相当于每个Skill的SKILL.md文件，它告诉AI这个Skill能做什么、需要什么参数
• 厨师（做菜品）：就是scripts目录下的Python函数，真正执行具体任务的"大厨"
• 传菜员（传订单）：对应统一调度器，负责把用户的请求分发给正确的Skill

这种类比之所以有效，是因为餐厅运营和AI Skill开发都强调"分工明确"。就像餐厅里不会让厨师同时负责点单和上菜一样，AI Skill开发也需要清晰的职责划分。

1.2 为什么需要统一规范？

我见过太多新手开发者的Skill项目，结构混乱得像一锅粥：有的Skill目录叫"weather"，有的叫"query_weather"；有的把函数放在main.py，有的放在handler.py。这种不一致性会导致：

1. 难以维护：每次添加新Skill都要重新理解目录结构
2. 无法扩展：想添加统一功能（如日志、权限）时无从下手
3. 调度困难：每个Skill都有自己的调用方式，无法统一管理

这就是为什么我们要从一开始就建立严格的规范。就像连锁餐厅的标准化操作流程一样，统一的Skill结构能让你的开发效率提升数倍。

2. 规范目录结构详解

2.1 单个Skill的标准结构

让我们先来看一个标准的单个Skill目录结构，以查询天气功能为例：

code复制weather-query/       # 技能根目录（功能-动作格式）
├── SKILL.md         # 技能说明文档
└── scripts/         # 执行代码目录
    └── skills.py    # 技能实现函数

这个结构看似简单，但每个部分都有其特定用途：

1. 根目录命名：采用"功能-动作"的小写连字符格式（如weather-query），这比随意命名更易于理解和搜索
2. SKILL.md：这是AI理解该Skill的"说明书"，必须包含技能名称、功能描述、参数定义和调用格式
3. scripts/skills.py：所有实现函数都放在这里，文件名固定为skills.py以保证一致性

提示：即使你目前只开发一个Skill，也应该遵循这个结构。等到需要添加第二个Skill时，你会感谢现在的自己。

2.2 多Skill项目的目录架构

当你的项目包含多个Skill时，目录结构需要升级为：

code复制ai-skills/            # 项目根目录
├── common/           # 公共组件
│   └── harness.py    # 统一调度器
├── weather-query/    # 天气查询技能
│   ├── SKILL.md
│   └── scripts/
│       └── skills.py
└── add-calculator/   # 加法计算技能
    ├── SKILL.md
    └── scripts/
        └── skills.py

这种结构的优势在于：

1. 清晰的层级关系：所有Skill平级存放，公共组件单独管理
2. 统一的调用入口：通过common/harness.py一个文件管理所有Skill
3. 易于扩展：添加新Skill只需创建标准目录，在调度器中注册即可

2.3 文件命名规范的重要性

你可能觉得文件名无关紧要，但在我参与过的大型AI项目中，不一致的命名导致了无数问题。我们的规范要求：

1. 目录名：全小写，使用连字符连接（如add-calculator）
2. 技能说明文件：必须命名为SKILL.md（全大写）
3. 代码文件：固定为scripts/skills.py
4. Python导入名：连字符替换为下划线（如add_calculator）

这种严格的命名约定虽然初期需要适应，但长期来看能显著降低维护成本。当你的项目有几十个Skill时，统一的命名能让你快速定位到任何功能。

3. 手把手实现第一个AI Skill

3.1 创建查询天气Skill

让我们从最简单的查询天气功能开始，我会带你一步步完成实现。

3.1.1 编写SKILL.md

首先创建weather-query/SKILL.md文件，内容如下：

markdown复制# 技能名称：查询天气
功能：用户输入城市名，返回该城市的实时天气（模拟真实接口，可直接替换为真实API）
参数：
- city：城市名称（字符串类型，比如北京、上海、成都），必填项，不可为空
调用格式（AI输出格式，必须严格遵循，所有Skill统一此格式）：
{
  "name": "查询天气",
  "params": {
    "city": "北京"
  }
}
备注：
1. 若未传入city参数，AI需提示用户"请输入要查询的城市名称"
2. 若传入的城市名称无效，函数会返回提示信息

这个文件有几个关键点：

1. 技能名称：与目录名不同，这是展示给用户的友好名称
2. 参数定义：明确每个参数的类型、是否必填
3. 调用格式：所有Skill必须遵循相同的JSON结构
4. 备注：说明边界情况和错误处理

3.1.2 实现核心函数

接下来是weather-query/scripts/skills.py文件：

python复制def query_weather(city):
    """
    查询城市天气（模拟接口）
    :param city: 城市名称（字符串）
    :return: 天气信息（字符串）
    """
    # 参数校验
    if not isinstance(city, str) or not city.strip():
        return "请输入有效的城市名称"
    
    # 模拟天气查询（实际项目中替换为真实API调用）
    weather_data = {
        "北京": "晴天，20℃，微风",
        "上海": "多云，22℃，东南风3级",
        "广州": "阵雨，25℃，南风2级"
    }
    
    return weather_data.get(city, f"暂未收录{city}的天气信息")

这个实现包含了几个最佳实践：

1. 参数校验：确保city是有效的字符串
2. 模拟数据：使用字典模拟API响应，便于测试
3. 错误处理：对未知城市返回友好提示
4. 文档字符串：清晰说明函数用途和参数

3.1.3 测试你的Skill

创建weather-query/scripts/test.py进行测试：

python复制from skills import query_weather

def test_query_weather():
    # 测试正常情况
    print(query_weather("北京"))  # 预期：晴天，20℃，微风
    print(query_weather("上海"))  # 预期：多云，22℃，东南风3级
    
    # 测试异常情况
    print(query_weather(""))      # 预期：请输入有效的城市名称
    print(query_weather("杭州"))  # 预期：暂未收录杭州的天气信息

if __name__ == "__main__":
    test_query_weather()

运行测试确保功能正常：

bash复制cd weather-query/scripts
python test.py

3.2 创建加法计算Skill

现在你已经完成了第一个Skill，第二个就简单多了。我们快速实现一个加法计算功能。

3.2.1 编写SKILL.md

创建add-calculator/SKILL.md：

markdown复制# 技能名称：加法计算
功能：计算两个数字的和，支持整数、小数计算
参数：
- a：第一个数字（整数/小数），必填项
- b：第二个数字（整数/小数），必填项
调用格式（AI输出格式，必须严格遵循，和所有Skill统一）：
{
  "name": "加法计算",
  "params": {
    "a": 10,
    "b": 20
  }
}
备注：若传入的参数不是数字，函数会返回"参数错误，请传入有效的数字（整数或小数）"

注意这个SKILL.md的结构与天气查询完全一致，只是内容不同。

3.2.2 实现核心函数

add-calculator/scripts/skills.py内容：

python复制def add(a, b):
    """
    计算两个数字的和
    :param a: 第一个数字（整数/小数）
    :param b: 第二个数字（整数/小数）
    :return: 加法计算结果（字符串）
    """
    # 参数校验
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        return "参数错误，请传入有效的数字（整数或小数）"
    
    # 返回格式化结果
    return f"{a} + {b} = {a + b}"

这个实现展示了数值处理的技巧：

1. 使用isinstance检查类型，同时接受int和float
2. 返回格式化的字符串，便于直接展示给用户
3. 清晰的错误提示信息

3.2.3 测试加法Skill

创建add-calculator/scripts/test.py：

python复制from skills import add

def test_add():
    # 测试整数
    print(add(10, 20))     # 预期：10 + 20 = 30
    # 测试小数
    print(add(1.5, 2.5))   # 预期：1.5 + 2.5 = 4.0
    # 测试错误输入
    print(add("10", 20))   # 预期：参数错误...

if __name__ == "__main__":
    test_add()

运行测试：

bash复制cd add-calculator/scripts
python test.py

4. 实现统一调度器

4.1 为什么需要统一调度？

在开发多个Skill后，你会发现每个Skill都需要：

1. 独立的HTTP端点（如果部署为服务）
2. 重复的错误处理逻辑
3. 相同的参数校验代码
4. 一致的日志记录需求

统一调度器解决了这些问题，它相当于一个"总控中心"，负责：

1. 接收所有AI请求
2. 路由到正确的Skill
3. 处理公共逻辑（如鉴权、日志）
4. 返回统一格式的响应

4.2 调度器实现详解

创建ai-skills/common/harness.py：

python复制import logging
from importlib import import_module

# 配置日志
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class SkillHarness:
    def __init__(self):
        self.skill_map = {}
        self._load_skills()

    def _load_skills(self):
        """动态加载所有Skill"""
        skills = [
            "weather_query.scripts.skills",
            "add_calculator.scripts.skills"
        ]
        
        for skill_path in skills:
            try:
                module = import_module(skill_path)
                skill_name = skill_path.split(".")[0].replace("_", " ")
                # 假设每个模块只有一个主要函数
                func = getattr(module, next(
                    f for f in dir(module) 
                    if not f.startswith("_")
                ))
                self.skill_map[skill_name] = func
                logger.info(f"成功加载技能: {skill_name}")
            except Exception as e:
                logger.error(f"加载技能{skill_path}失败: {str(e)}")

    def execute(self, skill_name, params):
        """
        执行指定技能
        :param skill_name: 技能名称（如"weather query"）
        :param params: 参数字典
        :return: (success, result)
        """
        if skill_name not in self.skill_map:
            return False, f"未找到技能: {skill_name}"
        
        try:
            result = self.skill_map[skill_name](**params)
            return True, result
        except Exception as e:
            logger.exception(f"执行技能{skill_name}出错")
            return False, f"技能执行错误: {str(e)}"

# 示例使用
if __name__ == "__main__":
    harness = SkillHarness()
    
    # 测试天气查询
    success, result = harness.execute(
        "weather query",
        {"city": "北京"}
    )
    print(f"天气查询结果: {result}")
    
    # 测试加法计算
    success, result = harness.execute(
        "add calculator",
        {"a": 10, "b": 20}
    )
    print(f"加法计算结果: {result}")

这个调度器有几个关键设计：

1. 动态加载：自动发现并加载所有Skill，无需手动注册
2. 统一接口：所有Skill通过相同的execute方法调用
3. 错误隔离：一个Skill出错不会影响其他Skill
4. 日志记录：详细记录执行过程，便于排查问题

4.3 调度器的进阶优化

在实际项目中，你还可以为调度器添加更多功能：

1. 缓存机制：对频繁查询的天气结果进行缓存
2. 限流控制：防止某个Skill被过度调用
3. 权限校验：检查用户是否有权使用特定Skill
4. 性能监控：记录每个Skill的执行时间

这些扩展都能在调度器中统一实现，而不需要修改各个Skill的代码。

5. 项目实战：完整调用流程

5.1 初始化项目结构

首先确保你的项目结构如下：

code复制ai-skills/
├── common/
│   └── harness.py
├── weather-query/
│   ├── SKILL.md
│   └── scripts/
│       ├── skills.py
│       └── test.py
└── add-calculator/
    ├── SKILL.md
    └── scripts/
        ├── skills.py
        └── test.py

5.2 编写主程序

创建ai-skills/main.py作为应用入口：

python复制from common.harness import SkillHarness
import json

def main():
    # 初始化调度器
    harness = SkillHarness()
    
    # 模拟用户交互
    while True:
        print("\n可用技能:")
        print("1. 查询天气")
        print("2. 加法计算")
        print("0. 退出")
        
        choice = input("请选择功能编号: ")
        
        if choice == "0":
            break
        elif choice == "1":
            city = input("请输入城市名称: ")
            success, result = harness.execute(
                "weather query",
                {"city": city}
            )
        elif choice == "2":
            try:
                a = float(input("请输入第一个数字: "))
                b = float(input("请输入第二个数字: "))
                success, result = harness.execute(
                    "add calculator",
                    {"a": a, "b": b}
                )
            except ValueError:
                result = "输入错误，请输入有效数字"
                success = False
        else:
            result = "无效选择"
            success = False
        
        print("\n结果:")
        print(result if success else f"错误: {result}")

if __name__ == "__main__":
    main()

5.3 运行完整系统

启动程序：

bash复制cd ai-skills
python main.py

你将看到交互式菜单，可以测试两个Skill的功能。这个简单的CLI界面展示了如何将多个Skill集成到一个统一系统中。

6. 开发经验与避坑指南

6.1 常见问题及解决方案

在开发AI Skill过程中，我遇到过各种问题，以下是典型场景及解决方法：

问题1：Skill无法被调度器识别

• 原因：目录结构或命名不符合规范
• 解决：检查是否满足：
  • 根目录是小写连字符格式
  • 存在SKILL.md文件
  • scripts/skills.py中有实现函数
  • 调度器中正确导入了该Skill

问题2：参数传递错误

• 现象：函数收到None或错误类型的参数
• 解决：
  • 检查SKILL.md中的参数定义
  • 确保调用格式完全匹配
  • 在函数开始处添加参数校验

问题3：新增Skill后系统崩溃

• 原因：新Skill影响了其他Skill
• 解决：
  • 确保每个Skill有独立命名空间
  • 在调度器中添加异常捕获
  • 先单独测试新Skill，再集成

6.2 性能优化技巧

当Skill数量增多时，需要考虑性能问题：

1. 懒加载：不要一次性加载所有Skill，而是在首次调用时加载
2. 缓存机制：对耗时的远程调用（如天气API）添加缓存
3. 超时控制：为每个Skill设置最大执行时间
4. 资源隔离：使用单独进程运行可能崩溃的Skill

6.3 测试策略建议

完善的测试是保证Skill质量的关键：

1. 单元测试：为每个Skill函数编写测试用例
2. 集成测试：测试Skill与调度器的集成
3. 性能测试：模拟高并发场景下的表现
4. 模糊测试：用随机输入测试系统的健壮性

6.4 扩展思路

掌握了基础框架后，你可以考虑以下扩展方向：

1. 对接大模型：让LLM自动选择合适的Skill
2. Web界面：开发可视化Skill管理界面
3. 技能市场：允许用户下载安装第三方Skill
4. 自动编排：多个Skill组合完成复杂任务

7. 项目进阶与扩展

7.1 对接真实天气API

之前的天气查询使用的是模拟数据，现在我们来对接真实API。以和风天气为例：

1. 注册获取API Key
2. 修改weather-query/scripts/skills.py：

python复制import requests

def query_weather(city, api_key="YOUR_API_KEY"):
    """
    查询真实天气（使用和风天气API）
    :param city: 城市名称
    :param api_key: 和风天气API Key
    :return: 天气信息字符串
    """
    # 1. 获取城市LocationID
    geo_url = f"https://geoapi.qweather.com/v2/city/lookup?location={city}&key={api_key}"
    try:
        geo_resp = requests.get(geo_url).json()
        if geo_resp["code"] != "200":
            return f"获取城市信息失败: {geo_resp.get('message', '未知错误')}"
        
        location_id = geo_resp["location"][0]["id"]
    except Exception as e:
        return f"查询城市ID出错: {str(e)}"
    
    # 2. 获取实时天气
    weather_url = f"https://devapi.qweather.com/v7/weather/now?location={location_id}&key={api_key}"
    try:
        weather_resp = requests.get(weather_url).json()
        if weather_resp["code"] != "200":
            return f"获取天气失败: {weather_resp.get('message', '未知错误')}"
        
        now = weather_resp["now"]
        return (
            f"{city}当前天气：{now['text']}，"
            f"温度{now['temp']}℃，"
            f"湿度{now['humidity']}%，"
            f"风向{now['windDir']}，"
            f"风力{now['windScale']}级"
        )
    except Exception as e:
        return f"查询天气出错: {str(e)}"

这个改进版本：

1. 使用真实天气API获取数据
2. 包含完整的错误处理
3. 返回更详细的天气信息
4. 保持与原有相同的接口，不影响调度器

7.2 添加权限控制

某些Skill可能需要权限控制，可以在调度器中实现：

python复制class SkillHarness:
    def __init__(self):
        self.skill_map = {}
        self.skill_permissions = {
            "weather query": ["user", "admin"],
            "add calculator": ["user", "admin"],
            "admin only skill": ["admin"]
        }
        self._load_skills()

    def execute(self, skill_name, params, user_role="user"):
        """添加user_role参数"""
        if skill_name not in self.skill_map:
            return False, f"未找到技能: {skill_name}"
        
        # 检查权限
        if user_role not in self.skill_permissions.get(skill_name, []):
            return False, "无权使用此技能"
        
        try:
            result = self.skill_map[skill_name](**params)
            return True, result
        except Exception as e:
            logger.exception(f"执行技能{skill_name}出错")
            return False, f"技能执行错误: {str(e)}"

7.3 支持异步执行

对于耗时的Skill，可以使用异步模式：

python复制import asyncio

class AsyncSkillHarness:
    async def execute(self, skill_name, params):
        if skill_name not in self.skill_map:
            return False, f"未找到技能: {skill_name}"
        
        try:
            # 假设skill函数是async的
            result = await self.skill_map[skill_name](**params)
            return True, result
        except Exception as e:
            logger.exception(f"执行技能{skill_name}出错")
            return False, f"技能执行错误: {str(e)}"

7.4 添加监控指标

使用Prometheus等工具监控Skill使用情况：

python复制from prometheus_client import Counter, Summary

# 定义指标
SKILL_CALL_TOTAL = Counter(
    'skill_calls_total',
    'Total number of skill calls',
    ['skill_name']
)
SKILL_DURATION = Summary(
    'skill_duration_seconds',
    'Time spent processing skill calls',
    ['skill_name']
)

class MonitoredSkillHarness(SkillHarness):
    def execute(self, skill_name, params):
        SKILL_CALL_TOTAL.labels(skill_name).inc()
        
        with SKILL_DURATION.labels(skill_name).time():
            return super().execute(skill_name, params)

8. 最佳实践总结

经过多个AI Skill项目的实践，我总结了以下最佳实践：

1. 严格遵循规范：从第一个Skill就采用标准结构，避免后期重构
2. 单一职责原则：每个Skill只做一件事，保持功能聚焦
3. 完善的文档：SKILL.md要详细准确，这是AI理解Skill的关键
4. 防御性编程：对所有输入进行校验，确保系统健壮性
5. 统一错误处理：通过调度器集中处理异常，保持一致性
6. 渐进式复杂度：从简单实现开始，逐步添加高级功能
7. 全面测试：为每个Skill编写单元测试和集成测试

记住，好的AI Skill系统就像运转良好的餐厅：每个角色各司其职，流程标准化，扩展性强。当你需要新增功能时，就像在菜单上添加新菜品一样简单。