1. 项目概述为什么“Skills”是AI Agent进化的下一站最近和几个做AI应用开发的朋友聊天大家不约而同地提到了一个词Skills。无论是讨论Claude的最新动态还是规划自己的AI Agent项目这个词出现的频率越来越高。它不再是简历上那个泛泛的“技能”描述而是演变成了一个具体、可封装、可调用的AI能力单元。简单来说你可以把Skill理解为一个AI的“小程序”或“微服务”它让大语言模型LLM从一个“知道很多但手无缚鸡之力”的智者变成了一个“既懂理论又能实操”的多面手。举个例子一个只会聊天的模型你问它“帮我查一下上海明天天气然后总结成邮件发给我”它可能只能给你一段描述天气的文本。但一个装备了“天气查询Skill”和“邮件撰写Skill”的AI Agent就能真正地调用天气API获取数据再按照你设定的格式生成一封完整的邮件草稿。这个从“知道”到“做到”的跨越核心就是Skills。这不仅仅是AnthropicClaude的创造者在推的概念更是整个AI Agent领域从玩具走向工具的关键一步。无论是个人开发者想做个智能助手还是企业想构建复杂的自动化流程理解并掌握Skills的构建与集成都成了当下的必修课。2. Skills的核心原理拆解AI的“可执行能力”要玩转Skills不能只停留在调用层面得先搞清楚它的内在逻辑。这就像你用手机App如果不知道它是如何与系统API交互的一旦出问题就只能干瞪眼。2.1 Skill的本质结构化指令与外部能力的桥梁一个Skill本质上是一个高度结构化的“能力描述”加上其“执行逻辑”。它通常包含几个核心部分能力描述Skill Description 用自然语言清晰定义这个Skill能干什么、需要什么输入、会输出什么。这部分是给LLM看的让它知道在什么情况下应该调用这个Skill。例如“这是一个天气查询Skill。输入是一个城市名称输出是该城市当前天气的简要报告包括温度、湿度和天气状况。”执行逻辑Implementation 这是Skill的“肌肉”是真正的代码或配置负责完成具体任务。它可以是一段函数Function 最常见的形态用Python、JavaScript等编写包含调用外部API、处理数据、访问数据库等所有操作。一个工具调用Tool Call 遵循OpenAI或Anthropic等平台定义的函数调用Function Calling规范将执行逻辑封装成JSON Schema描述。一个工作流Workflow 对于复杂操作可能是一系列子步骤的编排。输入/输出模式I/O Schema 严格定义输入参数和返回值的类型、格式。这是确保LLM能正确生成调用请求并且执行结果能被LLM理解的关键。比如城市名称是字符串温度是浮点数。为什么需要这种结构因为LLM本质是文本生成器它不会“运行”代码。通过Skill的描述和模式LLM学会了“说出”一个结构化的调用请求如{“skill”: “get_weather”, “city”: “上海”}。然后由外部的“执行器”你的程序或Agent框架捕获这个请求找到对应的执行逻辑并运行最后将结果以文本形式塞回给LLM让它继续对话或处理。这个过程就是所谓的“规划-行动-观察”循环。2.2 Skill与普通提示词Prompt的根本区别很多人容易把Skill和复杂的提示词工程混淆。它们的区别至关重要提示词Prompt 是在LLM的“知识”和“推理”边界内跳舞。你通过精巧的文本引导激发模型已有知识产生更符合预期的回答。它无法让模型做它“不知道”或“做不到”的事比如获取实时数据、操作你的电脑。技能Skill 是给LLM装上“新肢体”和“新感官”。它扩展了LLM的行动边界使其能触达模型训练数据之外的世界实时信息、私有数据、具体操作。Skill的执行发生在LLM之外。用一个类比Prompt是教一个学识渊博但足不出户的教授如何更好地组织语言来解答历史问题而Skill是给这位教授配了一个研究员查最新资料、一个秘书发邮件和一个司机出门调研让他能解决需要实时信息和实际操作的综合性问题。2.3 主流框架中的Skill实现方式目前围绕Skills生态主要有两种实现路径大厂官方路径如Anthropic的Claude Code Anthropic在其开发工具如Claude Code中很可能内置了一套Skill开发、管理和调用的标准体系。它的优势是深度集成与Claude模型配合度可能更高调试和部署体验更顺畅。从网络信息看用户遇到“unable to connect to anthropic services”这类错误往往就是在配置或网络环节与这套官方体系连接时出了问题。这种路径的缺点是可能相对封闭生态依赖单一厂商。开源框架路径如LangChain, LlamaIndex, Semantic Kernel等 这是目前更活跃、更灵活的领域。以LangChain的“Tool”概念为例它本质上就是Skill。开发者通过装饰器或类定义将一个Python函数包装成Tool并为其提供名称、描述和参数模式。Agent框架负责在适当时机让LLM选择并调用这些Tool。优势 框架无关可对接不同LLMOpenAI, Anthropic, 本地模型生态丰富有大量社区贡献的现成Tools/Skills灵活性高可深度定制。劣势 需要一定的开发集成工作量不同框架有学习成本。注意 网络热词中提到的“Harness”被描述为“包裹在AI Agent核心推理逻辑之外的基础设施层”这非常精准。你可以把Harness理解为Skill的“运行平台”或“管理平台”它负责Skill的注册、发现、安全调用、监控和生命周期管理但它本身不包含具体的业务逻辑。这类似于Kubernetes之于容器应用的关系。3. 从零开始构建你的第一个Skill以天气查询Agent为例理论讲再多不如动手做一遍。我们以构建一个“天气查询Skill”并将其集成到一个简单AI Agent中为例展示完整流程。这里我们选择Python和LangChain框架因为它应用最广资料最多。3.1 环境准备与依赖安装首先确保你的开发环境就绪。我强烈建议使用Python虚拟环境来管理依赖避免包冲突。# 创建并激活虚拟环境以venv为例 python -m venv ai_agent_env source ai_agent_env/bin/activate # Linux/macOS # 或 ai_agent_env\Scripts\activate # Windows # 安装核心依赖 pip install langchain langchain-openai requests python-dotenvlangchain: Agent框架核心。langchain-openai: LangChain的OpenAI官方集成包我们暂时用OpenAI的API来演示原理相通。requests: 用于调用天气API。python-dotenv: 用于管理环境变量安全存储API密钥。接下来你需要准备两个关键的API密钥OpenAI API Key 用于访问GPT模型作为Agent的“大脑”。天气API Key 这里我们使用和风天气免费版足够测试你也可以用OpenWeatherMap等。在项目根目录创建.env文件并填入你的密钥OPENAI_API_KEYsk-your-openai-key-here HEFENG_API_KEYyour-hefeng-key-here重要安全提醒 务必把.env文件加入.gitignore切勿提交到代码仓库。3.2 定义并实现Weather Skill现在我们来创建Skill的核心逻辑。新建一个Python文件比如weather_skill.py。import os import requests from typing import Optional from langchain.tools import tool from dotenv import load_dotenv # 加载环境变量 load_dotenv() HEFENG_API_KEY os.getenv(HEFENG_API_KEY) BASE_URL https://devapi.qweather.com/v7/weather/now tool def get_current_weather(city: str, adm: Optional[str] None) - str: 获取指定城市的当前天气情况。 Args: city: 城市名称例如“上海”、“北京”。 adm: 可选城市所属的上级行政区如省份用于精确匹配。例如“上海”可以单独但“朝阳”可能需要adm“北京”来区分。 Returns: 一个字符串描述该城市的当前天气、温度和体感温度。 如果查询失败返回错误信息。 # 1. 参数检查与构造 if not city: return 请输入有效的城市名称。 location city if adm: location f{adm},{city} params { location: location, key: HEFENG_API_KEY, lang: zh, unit: m # 公制单位 } # 2. 调用外部API try: response requests.get(BASE_URL, paramsparams, timeout10) response.raise_for_status() # 如果状态码不是200抛出HTTPError data response.json() # 3. 解析API响应 if data[code] 200: now data[now] result ( f{city}的当前天气{now[text]}。 f温度{now[temp]}摄氏度 f体感温度{now[feelsLike]}摄氏度 f湿度{now[humidity]}% f风向{now[windDir]}风力{now[windScale]}级。 ) return result else: return f查询天气失败{data.get(message, 未知错误)} except requests.exceptions.RequestException as e: return f网络请求出错{e} except (KeyError, ValueError) as e: return f解析天气数据时出错{e} # 为了方便测试可以添加以下代码块 if __name__ __main__: # 简单测试一下Skill print(get_current_weather.invoke({city: 上海}))代码解析与实操要点tool装饰器 这是LangChain将普通函数转化为Tool即Skill的关键。它自动从函数签名和文档字符串中提取名称、描述和参数模式供LLM理解。文档字符串Docstring 必须清晰、准确LLM完全依赖它来决定是否以及如何调用这个Skill。描述要说明功能、参数意义和返回格式。错误处理 这是Skill健壮性的核心。外部API可能失败、网络可能超时、返回数据格式可能意外。必须用try-except捕获异常并返回对LLM友好的错误信息字符串而不是让程序崩溃。参数设计city是必填adm是可选。这种设计提高了Skill的灵活性。LLM在理解用户 query “北京朝阳区的天气”时可能会自动填入city“朝阳” adm“北京”。实操心得 在编写Skill时要时刻想着“LLM会怎么理解它”。你的参数名和描述要尽可能自然、无歧义。返回的字符串也要结构清晰便于LLM在后续对话中引用。避免返回原始的、复杂的JSON除非你确定你的Agent框架或后续Skill能处理。3.3 构建并运行一个简单的AI Agent有了Skill我们需要一个“大脑”LLM来指挥它。创建一个主文件main.py。import os from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_openai import ChatOpenAI from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from weather_skill import get_current_weather # 导入我们刚写的Skill # 加载环境变量 from dotenv import load_dotenv load_dotenv() # 1. 初始化LLM大脑 llm ChatOpenAI( modelgpt-3.5-turbo-1106, # 或 gpt-4根据你的API权限选择 temperature0, # 对于工具调用温度设低一些输出更确定 openai_api_keyos.getenv(OPENAI_API_KEY) ) # 2. 定义Agent可用的工具Skills列表 tools [get_current_weather] # 3. 构建提示词模板告诉Agent它的角色和能力 prompt ChatPromptTemplate.from_messages([ (system, 你是一个有用的天气查询助手。你可以使用工具来获取实时天气信息。如果用户的问题涉及天气请务必调用工具获取准确数据后再回答。请用中文回复。), MessagesPlaceholder(variable_namechat_history, optionalTrue), # 预留对话历史的位置 (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), # 这是关键用于放置Agent的思考过程和工具调用记录 ]) # 4. 创建Agent agent create_openai_tools_agent(llmllm, toolstools, promptprompt) # 5. 创建Agent执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 运行一个对话循环 if __name__ __main__: print(天气助手已启动输入退出或quit结束对话。) chat_history [] # 简单的内存存储对话历史 while True: try: user_input input(\n你) if user_input.lower() in [退出, quit, exit]: print(助手再见) break # 执行Agent response agent_executor.invoke({ input: user_input, chat_history: chat_history }) output response[output] print(f助手{output}) # 更新对话历史简单示例实际项目可能需要更精细的管理 chat_history.append((human, user_input)) chat_history.append((ai, output)) except KeyboardInterrupt: print(\n程序被中断。) break except Exception as e: print(f发生错误{e})运行与测试确保你的.env配置正确。在终端运行python main.py。尝试提问“上海天气怎么样”、“北京和上海哪个更热”、“帮我查一下广州的湿度”。你会看到控制台输出verboseTrue带来的详细思考过程类似 Entering new AgentExecutor chain... 我需要查询上海和北京的当前天气来比较温度。 Action: get_current_weather Action Input: {city: 上海} Observation: 上海的当前天气晴。温度22摄氏度体感温度21摄氏度湿度65%风向东南风力2级。 Thought: 现在我有了上海的天气需要北京的。 Action: get_current_weather Action Input: {city: 北京} Observation: 北京的当前天气多云。温度18摄氏度体感温度17摄氏度湿度50%风向北风风力3级。 Thought: 上海22度北京18度所以上海更热。 Action: 最终答案 最终答案根据实时天气数据上海当前气温22摄氏度北京当前气温18摄氏度。因此上海比北京更热一些。 Finished chain. 助手根据实时天气数据...4. Skills开发进阶设计模式与最佳实践当你掌握了单个Skill的开发后构建复杂Agent就会遇到新的挑战如何管理多个Skill如何设计Skill间的协作如何保证稳定性和安全性4.1 Skill的模块化与分类管理一个实用的AI Agent往往需要数十甚至上百个Skills。像把所有文件放在一个文件夹里一样把所有Skill函数堆在一个文件里是灾难性的。你需要模块化。推荐的项目结构my_ai_agent/ ├── skills/ # 技能包目录 │ ├── __init__.py │ ├── weather.py # 天气相关技能 │ ├── calendar.py # 日历日程技能 │ ├── web_search.py # 网络搜索技能 │ └── data_tools/ # 子包用于更复杂的分类 │ ├── __init__.py │ └── analysis.py ├── agents/ # 不同的Agent定义 ├── chains/ # 复杂的工作流链 ├── config.py # 配置文件 ├── main.py # 主入口 └── .env在skills/__init__.py中你可以统一导出所有Skill方便主程序导入from .weather import get_current_weather, get_weather_forecast from .calendar import create_event, list_events from .web_search import search_web __all__ [ get_current_weather, get_weather_forecast, create_event, list_events, search_web, ]然后在主程序中from skills import *或from skills import get_current_weather, search_web。4.2 复杂Skill与工作流设计有些任务不是一个API调用能解决的它可能需要多个步骤甚至根据中间结果进行判断。这时你有两种选择封装成复合Skill 在Skill内部实现多步逻辑。例如一个“安排出差行程”Skill内部可能依次调用查询目的地天气 - 查询航班信息 - 查询酒店 - 生成行程草案。这样做对LLM透明LLM只看到调用了一次但逻辑复杂内部错误处理难度大。使用Agent或Chain编排多个基础Skill 这是更灵活和强大的方式。你创建一个专用的“行程规划Agent”它本身具备调用天气、航班、酒店等基础Skill的能力由LLM来主导整个规划和决策过程。这更符合AI Agent的核心理念也更容易调试。LangChain的AgentExecutor和SequentialChain就是干这个的。示例一个简单的两步工作流Chain查询天气并给出穿衣建议from langchain.chains import SequentialChain, LLMChain from langchain.prompts import PromptTemplate from langchain_openai import ChatOpenAI # 假设我们已经有了一个能返回天气文本的get_weather_skill函数不是tool直接返回字符串 def get_weather_skill(city: str) - str: # ... 实现同上返回天气字符串 ... pass # 定义第二个Chain根据天气文本生成建议 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7) advice_prompt PromptTemplate( input_variables[weather_report], template根据以下天气报告为用户提供简洁的穿衣和出行建议。报告{weather_report}\n建议 ) advice_chain LLMChain(llmllm, promptadvice_prompt, output_keyadvice) # 组合成顺序链 overall_chain SequentialChain( chains[{function: get_weather_skill, output_key: weather_report}, advice_chain], input_variables[city], output_variables[weather_report, advice], verboseTrue ) result overall_chain.run(city上海) print(result[weather_report]) print(result[advice])4.3 安全性、权限与错误处理这是企业级应用必须考虑的严肃问题。权限控制Permission 不是所有用户都能调用所有Skill。需要在Skill执行前加入身份验证和授权检查。例如在tool装饰的函数内部首先检查传入的user_id或session是否有权执行该操作。tool def delete_database_table(table_name: str, user_ctx: dict) - str: if not user_ctx.get(is_admin): return 错误权限不足需要管理员权限。 # ... 执行删除操作 ...如何传递用户上下文这通常需要自定义Agent执行流程将用户信息注入到每个Tool的调用参数中。输入验证与清理 永远不要相信来自LLM或用户的输入。在Skill内部对输入参数进行严格的类型检查、范围校验和恶意代码过滤特别是涉及系统调用、数据库查询时。def get_current_weather(city: str): # 简单的清理和验证 city city.strip()[:50] # 防止超长字符串攻击 if not re.match(r^[\w\s\u4e00-\u9fa5\-]$, city): # 基本的中英文数字空格校验 return 城市名称包含非法字符。 # ...资源隔离与限流 对于调用外部API或消耗计算资源的Skill要设置超时timeout、重试次数retry和速率限制rate limit防止单个错误请求拖垮整个系统或避免产生意外的高额API费用。错误处理标准化 定义统一的错误返回格式。这不仅让LLM更容易理解也便于前端展示。例如总是返回一个包含success、data、error_message字段的字典或特定对象。5. 调试、优化与常见问题排查开发过程中你一定会遇到各种问题。以下是一些高频问题及排查思路。5.1 Skill未被调用或调用错误症状 LLM直接回答了问题而没有调用你提供的Skill。排查检查Skill描述 这是最常见的原因。描述是否足够清晰LLM是否理解在什么场景下该调用它尝试将描述写得更具体、场景化。例如将“获取天气”改为“当用户询问当前天气、气温、湿度、风力或穿衣建议时使用此工具获取实时数据。”检查系统提示词System Prompt 你的系统提示词是否明确指示Agent去使用工具像前文例子中的“请务必调用工具获取准确数据后再回答”就是很强的指令。开启Verbose模式 像我们示例中那样设置verboseTrue观察LLM的完整思考链Chain of Thought看它到底是如何决策的。测试工具列表 确保你的tools列表正确传递给了Agent创建函数并且每个tool都被正确初始化。症状 LLM尝试调用Skill但参数格式错误或缺失。排查检查函数签名和文档字符串 LangChain等框架严重依赖它们来生成JSON Schema。确保参数有类型注解如city: str文档字符串里对每个参数有说明。使用更强大的模型 GPT-3.5-Turbo在复杂工具调用上有时不如GPT-4稳定。如果条件允许换用GPT-4或Claude 3系列模型试试。提供少量示例Few-Shot 在系统提示词中给出一两个用户问题及正确调用工具的示例能显著提升模型调用准确性。5.2 网络与API连接问题网络问题在调用外部API时极为常见从热词中大量的连接错误就能看出。症状requests.exceptions.ConnectionError,Timeout, 或unable to connect to anthropic services等。排查与解决本地网络诊断 在Skill代码中或单独写脚本用requests直接调用目标API看是否能通。检查代理设置如果你在特殊网络环境下。注意某些服务如Anthropic可能在某些区域访问不稳定。超时设置 务必为所有网络请求设置合理的超时如timeout(3.05, 27)避免线程被永远挂起。实现重试机制 对于瞬时的网络波动加入简单的重试逻辑能极大提高稳定性。from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min2, max10)) def call_weather_api(params): response requests.get(BASE_URL, paramsparams, timeout10) response.raise_for_status() return responseAPI密钥与端点 反复核对API密钥是否正确、是否过期、是否有调用权限。检查API的基础URL是否更新有时服务商会迁移端点。5.3 性能优化与成本控制当Skill和Agent变得复杂性能和成本就成为关键。上下文长度Context Length 每次调用LLM你发送的对话历史、系统提示、工具描述都会消耗Token。工具越多描述越详细消耗越大。优化策略 精简工具描述只保留最关键信息对于长对话实现“摘要式记忆”或只保留最近N轮对话而不是全部历史考虑使用具有更长上下文窗口的模型如GPT-4 Turbo 128K Claude 200K。思考深度与步骤Step Agent的每一步“思考”和“行动”都是一次LLM API调用复杂任务可能涉及数十步。优化策略 设计更精准的Skill让一个Skill能完成更复合的工作减少LLM规划步骤为Agent设置最大迭代次数max_iterations防止陷入死循环使用“ReAct”等更高效的Agent推理模式。异步与并行 如果多个Skill调用之间没有依赖关系可以考虑异步执行以缩短总响应时间。import asyncio from langchain.agents import AgentExecutor, create_openai_tools_agent # 注意需要使用支持异步的LLM和Agent执行器 # 例如使用 langchain_openai 的 ChatOpenAI 并配合 asyncio5.4 与Claude/Anthropic生态集成的特别注意事项从热词可以看出很多人关注Claude Code及其Skills。虽然我们示例用了OpenAI但原理相通切换时需注意API协议差异 OpenAI和Anthropic的API接口规范不同。OpenAI使用function calling而Anthropic有其自家的tools或skills调用格式。这意味着你不能直接把为OpenAI写的Skill描述照搬到Claude。你需要使用对应平台的SDK如anthropic库和适配方式。Claude Code的特定环境 热词中提到的“virtual machine platform not available”错误通常与Claude Code所需的特定运行环境如Windows的WSL2、虚拟化支持有关。确保你的开发环境满足其要求。模型特性 Claude模型在长文本、遵循指令方面有独特优势但在工具调用的格式遵循上可能和GPT系列有细微差别。需要参考Anthropic官方文档进行测试和调整。我个人在同时维护基于GPT和Claude的Agent项目时会抽象出一个“工具适配层”将Skill的核心逻辑与模型特定的调用格式解耦。核心业务代码一致只在最外层包装上根据目标模型选择不同的描述生成器和结果解析器。这比维护两套独立的Skill代码要高效得多。构建和调试Skills是一个需要耐心和细致观察的过程。最有效的调试方式就是结合verbose日志像侦探一样一步步跟随LLM的思考链看看它是在哪一步理解出现了偏差或是哪一步执行遇到了障碍。每一次成功的调试都会让你对LLM如何理解世界、如何使用工具产生更深刻的认识。