Spec Agent Skill 入门指南：从零构建你的第一个智能体技能

7次阅读

共计 1615 个字符，预计需要花费 5 分钟才能阅读完成。

Spec Agent Skill 是智能体（Agent）系统中可扩展的功能模块，类似于手机上的应用。它允许开发者通过定义特定领域的交互逻辑，赋予智能体处理任务的能力。例如天气查询、日程管理或电商比价等场景，都可以通过开发对应的 Skill 来实现。

安装 Python 3.8+（推荐使用 pyenv 或 conda 管理版本）

创建虚拟环境并激活：

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate    # Windows

安装核心 SDK：
```
pip install spec-agent-sdk
```

验证安装：

import spec_agent
print(spec_agent.__version__)

下面我们以「工作日倒计时」技能为例，演示完整开发流程：

from datetime import datetime
from spec_agent.skill import BaseSkill, Context

class WorkdayCountdownSkill(BaseSkill):
    """计算距离下一个工作日还有多少天"""

    def __init__(self):
        super().__init__(
            skill_id="workday_countdown",
            description="Show days remaining until next workday"
        )

    def execute(self, context: Context) -> str:
        today = datetime.now().date()
        next_day = today

        # 跳过周末
        while True:
            next_day += timedelta(days=1)
            if next_day.weekday() < 5:  # 0-4 为工作日
                break

        delta = next_day - today
        return f"距离下一个工作日还有 {delta.days} 天"

关键点说明：

必须继承 BaseSkill 基类
skill_id 需全局唯一
execute() 是核心处理方法
通过 Context 对象获取请求参数

本地测试脚本：

skill = WorkdayCountdownSkill()
print(skill.execute(Context({})))  # 空上下文

使用 SDK 测试工具：

spec-agent test skills/workday_countdown.py

查看交互日志：

2023-11-20 14:00:00 [INFO] 收到请求: {}
2023-11-20 14:00:00 [DEBUG] 计算日期差: 2

对耗时操作使用 @lru_cache 装饰器缓存结果
避免在 execute() 中进行复杂初始化
大数据集处理建议异步执行

def execute(self, context: Context):
    user_input = context.get("date")

    # 输入验证示例
    try:
        datetime.strptime(user_input, "%Y-%m-%d")
    except ValueError:
        return "日期格式错误，请使用 YYYY-MM-DD 格式"