这次我们来看一个关于“Skill”的技术概念。如果你经常接触AI工具尤其是像Claude、GPTs、Coze这类智能体平台可能会频繁听到“Skill”这个词。它听起来很酷但到底什么是Skill它和普通的AI提示词、插件、工作流有什么区别更重要的是我们能否自己动手从零开始创建一个专属的Skill实现工作效率的十倍跃迁本文将从最基础的概念讲起彻底拆解Skill的本质。我们会探讨Skill在不同AI平台如Claude、Coze、GPTs中的具体形态和实现方式并提供一个从环境准备、代码编写到测试部署的完整实战指南。无论你是想深度定制一个AI助手来解决重复性工作还是希望将复杂的业务流程自动化理解并掌握Skill的创建都将是你解锁AI高阶应用的关键一步。1. 核心能力速览Skill究竟是什么在AI智能体Agent的语境下Skill技能是一个高度封装、可复用的功能模块。它让AI助手具备了执行特定、复杂任务的能力而不仅仅是进行对话。你可以把它理解为给AI安装的一个个“小程序”或“外挂”。能力项说明与类比本质超越简单对话的可执行能力单元。是提示词Prompt、工具调用Tool Calling、工作流Workflow和外部API的有机结合体。与提示词区别提示词是告诉AI“怎么想”侧重于引导思考过程和输出格式。Skill是告诉AI“怎么做”侧重于连接外部能力、执行具体操作并返回结果。常见形态1.API调用型调用天气、翻译、数据库查询等外部服务。2.代码执行型在沙箱中运行Python、SQL等代码处理数据。3.流程自动化型串联多个步骤如“爬取网页 - 分析内容 - 生成报告”。4.知识增强型连接专属知识库进行精准问答。技术核心函数调用Function Calling或工具调用Tool Calling。AI模型根据用户请求动态选择并调用对应的Skill函数传入参数执行后返回结果。主要平台ClaudeCode Skill、OpenAI GPTsActions、Coze插件/工作流、Dify、LangChain等。各平台实现细节不同但核心理念相通。硬件门槛无特定要求。Skill本身是逻辑定义运行依赖后端服务云服务/本地API。创建和调试过程主要在开发环境中完成。核心价值将一次性的、复杂的提示工程沉淀为可重复使用、可共享、可组合的标准化组件极大提升AI应用的开发效率和可靠性。简单来说当你让AI“总结这个网页”时一个强大的Skill会背后自动完成抓取网页内容、清理格式、调用摘要模型、结构化输出这一整套动作而你只需要说一句话。2. 适用场景与使用边界适合谁用效率追求者厌倦重复操作希望用自然语言自动化处理邮件、文档、数据。业务开发者希望将公司内部系统CRM、ERP或特定业务逻辑如生成周报、审核内容封装成AI可调用的服务。AI应用构建者在Coze、Dify等平台上搭建智能Bot需要为其扩展网页搜索、专业计算、知识库查询等能力。技术爱好者想深入理解AI智能体如何与真实世界交互学习函数调用和API集成。能解决什么问题信息获取与处理实时查询天气、股价、新闻爬取并分析竞品网站数据。内容创作与加工根据关键词自动生成配图、将会议录音转为结构化纪要、批量翻译文档。流程自动化用户说“预定下周一10点的会议室”AI自动检查日历、调用预订系统接口并返回确认链接。专业领域增强为法律AI接入法典数据库为编程AI接入代码仓库搜索为客服AI接入工单系统。不适合什么场景极度简单、一次性的任务一句提示词就能完美解决的事情没必要封装成Skill。完全离线、无网络环境大多数Skill需要调用外部API或云服务。涉及极高安全或实时性要求的核心系统如直接操控工业设备、金融交易下单。AI的决策可能存在不确定性需谨慎评估。侵犯版权、隐私或绕过安全限制的操作如爬取受版权保护内容、破解验证码、生成虚假信息等。安全与合规边界授权与许可Skill调用的任何API、数据源都必须确保拥有合法使用权。使用公开数据也需遵守其Robots协议和服务条款。隐私保护处理用户上传的文档、图片、音频时必须在隐私政策中明确说明并确保数据传输和存储的安全。内容安全Skill生成或处理的内容应主动加入过滤机制避免产生违法违规信息。明确责任Skill作为工具其产生的结果应由使用者负责判断和审核。特别是在医疗、法律、金融等专业领域AI输出仅供参考。3. 环境准备与前置条件创建和测试一个Skill不需要强大的GPU但需要一个稳定的开发环境。以下是通用准备清单操作系统Windows 10/11, macOS, Linux (Ubuntu等) 均可。推荐使用Linux或macOS进行开发环境配置更简单。编程环境Python 3.8这是大多数AI工具链和后端服务的主流语言。确保已安装并配置好pip包管理器。代码编辑器/IDEVSCode、PyCharm等具备良好的Python支持和调试功能。版本控制Git。用于管理你的Skill代码。API密钥大模型平台你需要一个AI平台的API Key来测试Skill的调用。例如OpenAI API Key (用于GPTs)Anthropic API Key (用于Claude)国内平台如智谱AI、DeepSeek、通义千问的API Key。第三方服务如果你的Skill需要调用天气、翻译、数据库等服务需提前申请相应服务的API Key。网络环境能稳定访问外部API服务。部分国内服务可能需要配置代理或使用国内镜像。测试工具终端/命令行工具如Windows Terminal, iTerm2。API测试工具Postman或Insomnia用于手动测试你编写的Skill API。curl命令快速进行命令行测试。4. 实战从零创建一个“天气查询”Skill我们以创建一个最经典的“天气查询”Skill为例演示从设计、编码到集成的全过程。这个Skill将调用一个免费的天气API让AI能够回答关于城市天气的问题。4.1 技能设计与API选择功能根据城市名称查询该城市当前天气、温度、湿度、风力等信息。输入城市名例如“北京”、“New York”。输出结构化的天气信息文本。API选择这里我们使用和风天气HeWeather的免费API它提供中文支持且免费额度足够个人测试。你需要去其官网注册并获取API Key。4.2 创建后端服务FastAPI示例Skill的核心是一个能处理特定请求的API端点。我们使用Python的FastAPI框架快速搭建。首先创建项目目录并安装依赖mkdir weather_skill cd weather_skill python -m venv venv # 创建虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate pip install fastapi uvicorn requests pydantic创建一个名为main.py的文件from fastapi import FastAPI, HTTPException from pydantic import BaseModel import requests import os from typing import Optional app FastAPI(title天气查询Skill API) # 从环境变量读取API Key更安全 HEWEATHER_KEY os.getenv(HEWEATHER_KEY, 你的和风天气API_KEY) class WeatherRequest(BaseModel): Skill接收的请求体格式 city: str lang: Optional[str] zh # 默认中文 class WeatherResponse(BaseModel): Skill返回的响应体格式 city: str weather: str # 天气状况如“晴” temp: int # 温度摄氏度 feels_like: int # 体感温度 humidity: int # 湿度百分比 wind_speed: float # 风速 km/h last_update: str # 更新时间 full_text: str # 完整的自然语言描述 app.post(/weather, response_modelWeatherResponse) async def get_weather(req: WeatherRequest): 天气查询Skill的主端点。 AI智能体会将用户问题中的城市名提取出来调用此接口。 if not HEWEATHER_KEY or HEWEATHER_KEY 你的和风天气API_KEY: raise HTTPException(status_code500, detail天气服务API Key未配置) # 1. 调用和风天气“城市搜索”API获取location_id geo_url fhttps://geoapi.qweather.com/v2/city/lookup?key{HEWEATHER_KEY}location{req.city} try: geo_resp requests.get(geo_url, timeout10) geo_data geo_resp.json() if geo_data[code] ! 200 or not geo_data.get(location): raise HTTPException(status_code404, detailf未找到城市: {req.city}) location_id geo_data[location][0][id] except Exception as e: raise HTTPException(status_code502, detailf查询城市信息失败: {str(e)}) # 2. 用location_id查询实时天气 weather_url fhttps://devapi.qweather.com/v7/weather/now?key{HEWEATHER_KEY}location{location_id}lang{req.lang} try: weather_resp requests.get(weather_url, timeout10) weather_data weather_resp.json() if weather_data[code] ! 200: raise HTTPException(status_code502, detail天气API返回错误) now weather_data[now] except Exception as e: raise HTTPException(status_code502, detailf获取天气数据失败: {str(e)}) # 3. 构造标准化响应 full_text ( f{req.city}当前天气{now[text]}气温{now[temp]}°C f体感温度{now[feelsLike]}°C湿度{now[humidity]}% f风速{now[windSpeed]}公里/小时。数据更新于{now[obsTime][11:16]}。 ) return WeatherResponse( cityreq.city, weathernow[text], tempint(now[temp]), feels_likeint(now[feelsLike]), humidityint(now[humidity]), wind_speedfloat(now[windSpeed]), last_updatenow[obsTime][11:16], full_textfull_text ) app.get(/health) async def health_check(): return {status: healthy, service: weather_skill} if __name__ __main__: import uvicorn # 启动服务host设为0.0.0.0允许本地网络访问port可自定义 uvicorn.run(app, host0.0.0.0, port8000)4.3 启动与测试Skill服务设置环境变量并启动服务 在终端中先设置API Key然后运行服务。# 设置环境变量临时 # Windows (PowerShell): $env:HEWEATHER_KEY你的真实API_KEY # macOS/Linux: export HEWEATHER_KEY你的真实API_KEY # 启动服务 python main.py看到类似Uvicorn running on http://0.0.0.0:8000的输出说明服务启动成功。手动测试API 使用curl或打开浏览器访问http://localhost:8000/docs(FastAPI自动生成的交互式文档)进行测试。curl -X POST http://localhost:8000/weather \ -H Content-Type: application/json \ -d {city:北京}预期返回一个JSON包含结构化的天气信息和full_text字段。5. 将Skill接入AI智能体平台后端API准备好了接下来就是让AI模型知道有这个Skill并学会在合适的时候调用它。这里以OpenAI GPTs (通过Actions)和Claude (通过Code Skill)为例。5.1 接入OpenAI GPTs (Actions)GPTs通过“Actions”功能接入外部Skill其标准是OpenAPI Schema。生成OpenAPI Schema 在main.py同级目录创建一个openapi.json文件。你可以手动编写也可以利用FastAPI自动生成。访问http://localhost:8000/openapi.json即可获取完整的Schema定义。核心是描述/weather这个端点。在GPTs编辑器中配置创建或编辑一个GPT。在配置Configure标签页找到“Actions”部分点击“Create new action”。将openapi.json的内容粘贴到“Schema”框中。在“Authentication”中通常选择“None”因为我们的服务没设鉴权仅本地测试。生产环境务必使用API Key或OAuth。保存后在“Instructions”中告诉GPT“当用户询问天气或提及城市时使用‘get_weather’工具来获取实时信息。”关键点由于GPTs默认调用公网URL你需要将本地服务暴露到公网进行测试。可以使用ngrok或localhost.run等内网穿透工具。# 安装ngrok后 ngrok http 8000它会生成一个如https://xxxx.ngrok-free.app的临时公网地址。将Schema中的servers.url和API请求地址替换为此公网地址。测试对话 在GPT预览界面输入“上海天气怎么样”。观察GPT的思考过程它应该会识别出意图调用你配置的Action并将API返回的full_text自然地组织到回复中。5.2 接入Claude (Code Skill)Claude的Skill机制略有不同它更侧重于在对话中直接提供一段可执行的代码函数定义并引导Claude去使用它。编写Skill描述文件 创建一个claude_skill_weather.py文件这本质上是一个清晰的函数定义和说明。 # Weather Query Skill A skill for Claude to get real-time weather information for any city worldwide. ## Function get_weather(city: str, lang: str zh) - str ## Parameters - city: The name of the city, e.g., London, 东京, 北京. - lang: (Optional) Language for the response. Default is zh (Chinese). Supports en for English. ## Returns A string containing a natural language description of the current weather, temperature, humidity, wind speed, and update time. ## Example get_weather(Paris) 巴黎当前天气多云气温12°C体感温度10°C湿度65%风速15公里/小时。数据更新于14:20。 ## How Claude Should Use It When a user asks about the weather in a city, Claude should call this function with the city name extracted from the query. Then, incorporate the returned weather description naturally into the response. import requests import os HEWEATHER_KEY os.getenv(HEWEATHER_KEY) # Claude的Skill环境可能需要配置环境变量 def get_weather(city: str, lang: str zh) - str: Fetches and returns current weather for a given city. # 这里直接嵌入之前API调用逻辑或调用你部署好的服务端点 # 为了简化我们假设调用本地服务 import requests try: # 注意这里需要是Claude能访问到的地址如果是本地服务同样需要内网穿透 resp requests.post(http://localhost:8000/weather, json{city: city, lang: lang}, timeout10) resp.raise_for_status() data resp.json() return data[full_text] except Exception as e: return f抱歉获取{city}的天气信息时出错{str(e)}。请检查城市名称或稍后再试。 # 提供给Claude的接口 skills { get_weather: get_weather }在Claude平台上使用在Claude的Web或桌面应用中你可以通过“上传代码文件”或直接在对话中粘贴函数定义的方式让Claude“学习”这个Skill。更正式的方式是通过Claude for Developers如果提供相关功能来注册和管理Skill。对Claude说“我上传了一个天气查询的Skill。当用户问天气时请使用get_weather函数。” 然后进行测试。6. 功能测试与效果验证要点创建完Skill后必须进行系统化测试确保其稳定可靠。基础功能测试输入有效性测试常见城市“北京”、“上海”、带空格城市“New York”、中文拼音“beijing”。验证API是否能正确解析。错误处理测试不存在的城市“阿斯加德”、空输入、特殊字符。Skill应返回友好的错误信息而不是崩溃。边界情况测试API服务不可用、网络超时、返回数据格式异常时你的Skill服务是否有容错机制如重试、返回缓存默认值、抛出清晰异常。与AI集成的对话测试意图识别AI是否能正确识别“今天北京热吗”、“旧金山气候如何”、“帮我看看东京的天气”等多样化的问法并触发Skill。参数提取AI从自然语言中提取城市名的准确率。对于“北京和上海天气对比”这类复杂请求高级的Skill设计可能需要支持多城市查询。结果整合AI是否将Skill返回的原始数据full_text自然地、口语化地融入到对话中而不是生硬地粘贴JSON。性能与稳定性测试响应时间从AI发起请求到收到Skill回复的总时间。应控制在2-3秒内避免用户等待过长。并发能力使用工具如locust模拟多个用户同时查询天气观察服务是否能承受一定压力。长期运行将服务部署后观察其内存、CPU占用是否平稳有无内存泄漏。7. 进阶构建更复杂的Skill网页摘要掌握了基础Skill创建流程后我们可以尝试更复杂的例子一个“网页摘要”Skill。它需要先抓取网页内容再用AI模型进行总结。这个Skill的链条更长用户请求 - AI调用Skill - Skill抓取网页 - 清洗内容 - 调用摘要模型或本地NLP库- 返回摘要。后端服务核心思路 (main_summarizer.py):from fastapi import FastAPI from pydantic import BaseModel import requests from bs4 import BeautifulSoup import html2text import hashlib import redis # 用于简单缓存避免重复抓取 from typing import Optional app FastAPI(title网页摘要Skill API) # 初始化缓存客户端示例生产环境需配置 cache redis.Redis(hostlocalhost, port6379, decode_responsesTrue) class SummaryRequest(BaseModel): url: str max_length: Optional[int] 300 # 摘要最大长度 app.post(/summarize) async def summarize_webpage(req: SummaryRequest): # 1. 检查缓存 url_hash hashlib.md5(req.url.encode()).hexdigest() cached_summary cache.get(fsummary:{url_hash}) if cached_summary: return {summary: cached_summary, source: req.url, cached: True} # 2. 抓取网页 try: headers {User-Agent: Mozilla/5.0} resp requests.get(req.url, headersheaders, timeout15) resp.raise_for_status() html_content resp.text except Exception as e: return {error: f抓取网页失败: {str(e)}} # 3. 提取正文简化版可用trafilatura等专业库 soup BeautifulSoup(html_content, html.parser) for tag in soup([script, style, nav, footer]): tag.decompose() text soup.get_text() lines (line.strip() for line in text.splitlines()) chunks (phrase.strip() for line in lines for phrase in line.split( )) text .join(chunk for chunk in chunks if chunk) if len(text) 100: return {error: 未能提取到有效文本内容} # 4. 调用摘要模型这里模拟实际可调用本地模型或云API # 例如调用本地运行的ChatGLM3、Qwen等模型的API或使用transformers库 summary text[:req.max_length] ... if len(text) req.max_length else text # 真实场景下这里应调用一个文本摘要接口 # 5. 存入缓存有效期1小时 cache.setex(fsummary:{url_hash}, 3600, summary) return {summary: summary, source: req.url, cached: False}这个例子展示了Skill如何串联多个步骤网络请求、HTML解析、文本处理、缓存、AI调用并处理更复杂的逻辑。8. 资源占用、部署与性能观察资源占用像天气查询这样的简单Skill后端服务FastAPI内存占用通常在50-100MB。如果Skill内集成了本地AI模型如摘要模型则资源消耗取决于模型大小可能需要数百MB甚至数GB内存。CPU使用率在请求处理时会有峰值。部署建议本地测试使用uvicorn或gunicorn运行方便调试。生产环境容器化使用Docker将Skill及其依赖打包确保环境一致。FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]云服务部署到云服务器如AWS EC2、Google Cloud Run、阿里云函数计算FC或容器平台Kubernetes。Serverless对于调用不频繁的Skill可以改造成无服务器函数如AWS Lambda节省成本。性能观察日志务必添加详细日志记录每个请求的输入、输出、耗时和错误。监控使用Prometheus、Grafana或云平台监控工具观察服务的请求量、延迟、错误率。限流与熔断为防止滥用或下游API故障导致服务雪崩应实施请求限流和故障熔断机制。9. 常见问题与排查方法问题现象可能原因排查方式解决方案AI不调用Skill1. Schema定义错误。2. 认证失败。3. AI指令Instructions未明确。4. 网络不通。1. 检查OpenAPI Schema语法确保端点、参数定义正确。2. 查看AI平台日志或调试信息。3. 在对话中明确要求AI使用某个工具。1. 使用OpenAPI验证工具检查Schema。2. 简化认证或先关闭认证测试。3. 在Instructions中清晰描述Skill用途和调用时机。4. 确保AI能访问到Skill服务地址用curl测试。Skill调用超时1. 下游API响应慢。2. 网络延迟高。3. 服务端处理逻辑复杂。1. 单独测试下游API速度。2. 检查服务端日志定位耗时操作。3. 使用time命令或APM工具分析。1. 为下游API设置合理超时如5-10秒。2. 添加缓存避免重复计算。3. 优化代码异步处理耗时任务。返回结果解析错误1. Skill返回的JSON格式不符合AI预期。2. 字段名或类型不匹配。1. 对比Skill实际返回的JSON与Schema定义。2. 查看AI平台的错误日志。1. 确保Skill响应严格遵循Schema中定义的response_model。2. 使用Pydantic模型进行响应序列化避免手拼JSON。本地服务AI无法访问1. 服务仅在127.0.0.1监听。2. 防火墙/安全组阻止。3. AI平台在公网。1. 检查服务启动命令host应为0.0.0.0。2. 检查端口是否开放。3. 在本地用curl或Postman测试公网IP:端口是否通。1. 启动命令改为uvicorn main:app --host 0.0.0.0 --port 8000。2. 使用ngrok等内网穿透工具暴露服务到公网。依赖安装失败1. Python版本不兼容。2. 网络问题导致包下载失败。3. 系统缺少编译依赖如C库。1. 检查python --version。2. 使用pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple换源。3. 查看错误信息安装系统级依赖如build-essential,python3-dev。1. 使用虚拟环境隔离。2. 使用国内镜像源。3. 根据报错信息搜索并安装系统依赖。10. 最佳实践与高阶建议设计先行动手编码前用纸笔或文档明确Skill的输入、输出、处理逻辑和错误处理流程。定义清晰的API接口。单一职责一个Skill只做好一件事。不要创建“万能”Skill。例如“查询天气”和“查询空气质量”应该是两个独立的Skill便于维护和组合。完善的错误处理Skill必须能优雅地处理所有可能出现的异常网络错误、API限流、无效输入、超时等并返回对AI和最终用户都有意义的错误信息。加入缓存对于数据变化不频繁的查询如天气、新闻摘要引入缓存内存缓存如cachetools或Redis可以极大提升响应速度并降低下游API调用次数。安全性不要将API密钥等敏感信息硬编码在代码中使用环境变量或密钥管理服务。对用户输入进行严格的验证和清理防止注入攻击。如果Skill涉及用户数据确保接口有身份认证和授权机制如API Key、JWT。版本化与文档为你的Skill API维护版本如/v1/weather并编写清晰的API文档利用FastAPI自动生成或使用Swagger。测试全覆盖编写单元测试测试业务逻辑和集成测试测试整个API端点确保代码修改不会破坏现有功能。监控与告警生产环境的Skill必须配备监控关注成功率、延迟、调用量。设置告警在服务异常时及时通知。组合使用真正的威力在于Skill的组合。你可以创建一个“工作流”Skill它按顺序调用“抓取新闻”Skill、“翻译”Skill和“生成摘要”Skill从而实现复杂的自动化流水线。掌握Skill的创建意味着你不再只是AI工具的使用者而是成为了其能力的定义者和扩展者。从今天这个简单的天气查询Skill开始尝试将你工作中那些重复、枯燥但规则明确的环节抽象出来封装成一个个高效的Skill。当你积累的Skill库越来越丰富你的AI助手就会变得越来越强大真正实现个人和工作效率的十倍跃迁。
这次我们来看一个关于“Skill”的技术概念。如果你经常接触AI工具尤其是像Claude、GPTs、Coze这类智能体平台可能会频繁听到“Skill”这个词。它听起来很酷但到底什么是Skill它和普通的AI提示词、插件、工作流有什么区别更重要的是我们能否自己动手从零开始创建一个专属的Skill实现工作效率的十倍跃迁本文将从最基础的概念讲起彻底拆解Skill的本质。我们会探讨Skill在不同AI平台如Claude、Coze、GPTs中的具体形态和实现方式并提供一个从环境准备、代码编写到测试部署的完整实战指南。无论你是想深度定制一个AI助手来解决重复性工作还是希望将复杂的业务流程自动化理解并掌握Skill的创建都将是你解锁AI高阶应用的关键一步。1. 核心能力速览Skill究竟是什么在AI智能体Agent的语境下Skill技能是一个高度封装、可复用的功能模块。它让AI助手具备了执行特定、复杂任务的能力而不仅仅是进行对话。你可以把它理解为给AI安装的一个个“小程序”或“外挂”。能力项说明与类比本质超越简单对话的可执行能力单元。是提示词Prompt、工具调用Tool Calling、工作流Workflow和外部API的有机结合体。与提示词区别提示词是告诉AI“怎么想”侧重于引导思考过程和输出格式。Skill是告诉AI“怎么做”侧重于连接外部能力、执行具体操作并返回结果。常见形态1.API调用型调用天气、翻译、数据库查询等外部服务。2.代码执行型在沙箱中运行Python、SQL等代码处理数据。3.流程自动化型串联多个步骤如“爬取网页 - 分析内容 - 生成报告”。4.知识增强型连接专属知识库进行精准问答。技术核心函数调用Function Calling或工具调用Tool Calling。AI模型根据用户请求动态选择并调用对应的Skill函数传入参数执行后返回结果。主要平台ClaudeCode Skill、OpenAI GPTsActions、Coze插件/工作流、Dify、LangChain等。各平台实现细节不同但核心理念相通。硬件门槛无特定要求。Skill本身是逻辑定义运行依赖后端服务云服务/本地API。创建和调试过程主要在开发环境中完成。核心价值将一次性的、复杂的提示工程沉淀为可重复使用、可共享、可组合的标准化组件极大提升AI应用的开发效率和可靠性。简单来说当你让AI“总结这个网页”时一个强大的Skill会背后自动完成抓取网页内容、清理格式、调用摘要模型、结构化输出这一整套动作而你只需要说一句话。2. 适用场景与使用边界适合谁用效率追求者厌倦重复操作希望用自然语言自动化处理邮件、文档、数据。业务开发者希望将公司内部系统CRM、ERP或特定业务逻辑如生成周报、审核内容封装成AI可调用的服务。AI应用构建者在Coze、Dify等平台上搭建智能Bot需要为其扩展网页搜索、专业计算、知识库查询等能力。技术爱好者想深入理解AI智能体如何与真实世界交互学习函数调用和API集成。能解决什么问题信息获取与处理实时查询天气、股价、新闻爬取并分析竞品网站数据。内容创作与加工根据关键词自动生成配图、将会议录音转为结构化纪要、批量翻译文档。流程自动化用户说“预定下周一10点的会议室”AI自动检查日历、调用预订系统接口并返回确认链接。专业领域增强为法律AI接入法典数据库为编程AI接入代码仓库搜索为客服AI接入工单系统。不适合什么场景极度简单、一次性的任务一句提示词就能完美解决的事情没必要封装成Skill。完全离线、无网络环境大多数Skill需要调用外部API或云服务。涉及极高安全或实时性要求的核心系统如直接操控工业设备、金融交易下单。AI的决策可能存在不确定性需谨慎评估。侵犯版权、隐私或绕过安全限制的操作如爬取受版权保护内容、破解验证码、生成虚假信息等。安全与合规边界授权与许可Skill调用的任何API、数据源都必须确保拥有合法使用权。使用公开数据也需遵守其Robots协议和服务条款。隐私保护处理用户上传的文档、图片、音频时必须在隐私政策中明确说明并确保数据传输和存储的安全。内容安全Skill生成或处理的内容应主动加入过滤机制避免产生违法违规信息。明确责任Skill作为工具其产生的结果应由使用者负责判断和审核。特别是在医疗、法律、金融等专业领域AI输出仅供参考。3. 环境准备与前置条件创建和测试一个Skill不需要强大的GPU但需要一个稳定的开发环境。以下是通用准备清单操作系统Windows 10/11, macOS, Linux (Ubuntu等) 均可。推荐使用Linux或macOS进行开发环境配置更简单。编程环境Python 3.8这是大多数AI工具链和后端服务的主流语言。确保已安装并配置好pip包管理器。代码编辑器/IDEVSCode、PyCharm等具备良好的Python支持和调试功能。版本控制Git。用于管理你的Skill代码。API密钥大模型平台你需要一个AI平台的API Key来测试Skill的调用。例如OpenAI API Key (用于GPTs)Anthropic API Key (用于Claude)国内平台如智谱AI、DeepSeek、通义千问的API Key。第三方服务如果你的Skill需要调用天气、翻译、数据库等服务需提前申请相应服务的API Key。网络环境能稳定访问外部API服务。部分国内服务可能需要配置代理或使用国内镜像。测试工具终端/命令行工具如Windows Terminal, iTerm2。API测试工具Postman或Insomnia用于手动测试你编写的Skill API。curl命令快速进行命令行测试。4. 实战从零创建一个“天气查询”Skill我们以创建一个最经典的“天气查询”Skill为例演示从设计、编码到集成的全过程。这个Skill将调用一个免费的天气API让AI能够回答关于城市天气的问题。4.1 技能设计与API选择功能根据城市名称查询该城市当前天气、温度、湿度、风力等信息。输入城市名例如“北京”、“New York”。输出结构化的天气信息文本。API选择这里我们使用和风天气HeWeather的免费API它提供中文支持且免费额度足够个人测试。你需要去其官网注册并获取API Key。4.2 创建后端服务FastAPI示例Skill的核心是一个能处理特定请求的API端点。我们使用Python的FastAPI框架快速搭建。首先创建项目目录并安装依赖mkdir weather_skill cd weather_skill python -m venv venv # 创建虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate pip install fastapi uvicorn requests pydantic创建一个名为main.py的文件from fastapi import FastAPI, HTTPException from pydantic import BaseModel import requests import os from typing import Optional app FastAPI(title天气查询Skill API) # 从环境变量读取API Key更安全 HEWEATHER_KEY os.getenv(HEWEATHER_KEY, 你的和风天气API_KEY) class WeatherRequest(BaseModel): Skill接收的请求体格式 city: str lang: Optional[str] zh # 默认中文 class WeatherResponse(BaseModel): Skill返回的响应体格式 city: str weather: str # 天气状况如“晴” temp: int # 温度摄氏度 feels_like: int # 体感温度 humidity: int # 湿度百分比 wind_speed: float # 风速 km/h last_update: str # 更新时间 full_text: str # 完整的自然语言描述 app.post(/weather, response_modelWeatherResponse) async def get_weather(req: WeatherRequest): 天气查询Skill的主端点。 AI智能体会将用户问题中的城市名提取出来调用此接口。 if not HEWEATHER_KEY or HEWEATHER_KEY 你的和风天气API_KEY: raise HTTPException(status_code500, detail天气服务API Key未配置) # 1. 调用和风天气“城市搜索”API获取location_id geo_url fhttps://geoapi.qweather.com/v2/city/lookup?key{HEWEATHER_KEY}location{req.city} try: geo_resp requests.get(geo_url, timeout10) geo_data geo_resp.json() if geo_data[code] ! 200 or not geo_data.get(location): raise HTTPException(status_code404, detailf未找到城市: {req.city}) location_id geo_data[location][0][id] except Exception as e: raise HTTPException(status_code502, detailf查询城市信息失败: {str(e)}) # 2. 用location_id查询实时天气 weather_url fhttps://devapi.qweather.com/v7/weather/now?key{HEWEATHER_KEY}location{location_id}lang{req.lang} try: weather_resp requests.get(weather_url, timeout10) weather_data weather_resp.json() if weather_data[code] ! 200: raise HTTPException(status_code502, detail天气API返回错误) now weather_data[now] except Exception as e: raise HTTPException(status_code502, detailf获取天气数据失败: {str(e)}) # 3. 构造标准化响应 full_text ( f{req.city}当前天气{now[text]}气温{now[temp]}°C f体感温度{now[feelsLike]}°C湿度{now[humidity]}% f风速{now[windSpeed]}公里/小时。数据更新于{now[obsTime][11:16]}。 ) return WeatherResponse( cityreq.city, weathernow[text], tempint(now[temp]), feels_likeint(now[feelsLike]), humidityint(now[humidity]), wind_speedfloat(now[windSpeed]), last_updatenow[obsTime][11:16], full_textfull_text ) app.get(/health) async def health_check(): return {status: healthy, service: weather_skill} if __name__ __main__: import uvicorn # 启动服务host设为0.0.0.0允许本地网络访问port可自定义 uvicorn.run(app, host0.0.0.0, port8000)4.3 启动与测试Skill服务设置环境变量并启动服务 在终端中先设置API Key然后运行服务。# 设置环境变量临时 # Windows (PowerShell): $env:HEWEATHER_KEY你的真实API_KEY # macOS/Linux: export HEWEATHER_KEY你的真实API_KEY # 启动服务 python main.py看到类似Uvicorn running on http://0.0.0.0:8000的输出说明服务启动成功。手动测试API 使用curl或打开浏览器访问http://localhost:8000/docs(FastAPI自动生成的交互式文档)进行测试。curl -X POST http://localhost:8000/weather \ -H Content-Type: application/json \ -d {city:北京}预期返回一个JSON包含结构化的天气信息和full_text字段。5. 将Skill接入AI智能体平台后端API准备好了接下来就是让AI模型知道有这个Skill并学会在合适的时候调用它。这里以OpenAI GPTs (通过Actions)和Claude (通过Code Skill)为例。5.1 接入OpenAI GPTs (Actions)GPTs通过“Actions”功能接入外部Skill其标准是OpenAPI Schema。生成OpenAPI Schema 在main.py同级目录创建一个openapi.json文件。你可以手动编写也可以利用FastAPI自动生成。访问http://localhost:8000/openapi.json即可获取完整的Schema定义。核心是描述/weather这个端点。在GPTs编辑器中配置创建或编辑一个GPT。在配置Configure标签页找到“Actions”部分点击“Create new action”。将openapi.json的内容粘贴到“Schema”框中。在“Authentication”中通常选择“None”因为我们的服务没设鉴权仅本地测试。生产环境务必使用API Key或OAuth。保存后在“Instructions”中告诉GPT“当用户询问天气或提及城市时使用‘get_weather’工具来获取实时信息。”关键点由于GPTs默认调用公网URL你需要将本地服务暴露到公网进行测试。可以使用ngrok或localhost.run等内网穿透工具。# 安装ngrok后 ngrok http 8000它会生成一个如https://xxxx.ngrok-free.app的临时公网地址。将Schema中的servers.url和API请求地址替换为此公网地址。测试对话 在GPT预览界面输入“上海天气怎么样”。观察GPT的思考过程它应该会识别出意图调用你配置的Action并将API返回的full_text自然地组织到回复中。5.2 接入Claude (Code Skill)Claude的Skill机制略有不同它更侧重于在对话中直接提供一段可执行的代码函数定义并引导Claude去使用它。编写Skill描述文件 创建一个claude_skill_weather.py文件这本质上是一个清晰的函数定义和说明。 # Weather Query Skill A skill for Claude to get real-time weather information for any city worldwide. ## Function get_weather(city: str, lang: str zh) - str ## Parameters - city: The name of the city, e.g., London, 东京, 北京. - lang: (Optional) Language for the response. Default is zh (Chinese). Supports en for English. ## Returns A string containing a natural language description of the current weather, temperature, humidity, wind speed, and update time. ## Example get_weather(Paris) 巴黎当前天气多云气温12°C体感温度10°C湿度65%风速15公里/小时。数据更新于14:20。 ## How Claude Should Use It When a user asks about the weather in a city, Claude should call this function with the city name extracted from the query. Then, incorporate the returned weather description naturally into the response. import requests import os HEWEATHER_KEY os.getenv(HEWEATHER_KEY) # Claude的Skill环境可能需要配置环境变量 def get_weather(city: str, lang: str zh) - str: Fetches and returns current weather for a given city. # 这里直接嵌入之前API调用逻辑或调用你部署好的服务端点 # 为了简化我们假设调用本地服务 import requests try: # 注意这里需要是Claude能访问到的地址如果是本地服务同样需要内网穿透 resp requests.post(http://localhost:8000/weather, json{city: city, lang: lang}, timeout10) resp.raise_for_status() data resp.json() return data[full_text] except Exception as e: return f抱歉获取{city}的天气信息时出错{str(e)}。请检查城市名称或稍后再试。 # 提供给Claude的接口 skills { get_weather: get_weather }在Claude平台上使用在Claude的Web或桌面应用中你可以通过“上传代码文件”或直接在对话中粘贴函数定义的方式让Claude“学习”这个Skill。更正式的方式是通过Claude for Developers如果提供相关功能来注册和管理Skill。对Claude说“我上传了一个天气查询的Skill。当用户问天气时请使用get_weather函数。” 然后进行测试。6. 功能测试与效果验证要点创建完Skill后必须进行系统化测试确保其稳定可靠。基础功能测试输入有效性测试常见城市“北京”、“上海”、带空格城市“New York”、中文拼音“beijing”。验证API是否能正确解析。错误处理测试不存在的城市“阿斯加德”、空输入、特殊字符。Skill应返回友好的错误信息而不是崩溃。边界情况测试API服务不可用、网络超时、返回数据格式异常时你的Skill服务是否有容错机制如重试、返回缓存默认值、抛出清晰异常。与AI集成的对话测试意图识别AI是否能正确识别“今天北京热吗”、“旧金山气候如何”、“帮我看看东京的天气”等多样化的问法并触发Skill。参数提取AI从自然语言中提取城市名的准确率。对于“北京和上海天气对比”这类复杂请求高级的Skill设计可能需要支持多城市查询。结果整合AI是否将Skill返回的原始数据full_text自然地、口语化地融入到对话中而不是生硬地粘贴JSON。性能与稳定性测试响应时间从AI发起请求到收到Skill回复的总时间。应控制在2-3秒内避免用户等待过长。并发能力使用工具如locust模拟多个用户同时查询天气观察服务是否能承受一定压力。长期运行将服务部署后观察其内存、CPU占用是否平稳有无内存泄漏。7. 进阶构建更复杂的Skill网页摘要掌握了基础Skill创建流程后我们可以尝试更复杂的例子一个“网页摘要”Skill。它需要先抓取网页内容再用AI模型进行总结。这个Skill的链条更长用户请求 - AI调用Skill - Skill抓取网页 - 清洗内容 - 调用摘要模型或本地NLP库- 返回摘要。后端服务核心思路 (main_summarizer.py):from fastapi import FastAPI from pydantic import BaseModel import requests from bs4 import BeautifulSoup import html2text import hashlib import redis # 用于简单缓存避免重复抓取 from typing import Optional app FastAPI(title网页摘要Skill API) # 初始化缓存客户端示例生产环境需配置 cache redis.Redis(hostlocalhost, port6379, decode_responsesTrue) class SummaryRequest(BaseModel): url: str max_length: Optional[int] 300 # 摘要最大长度 app.post(/summarize) async def summarize_webpage(req: SummaryRequest): # 1. 检查缓存 url_hash hashlib.md5(req.url.encode()).hexdigest() cached_summary cache.get(fsummary:{url_hash}) if cached_summary: return {summary: cached_summary, source: req.url, cached: True} # 2. 抓取网页 try: headers {User-Agent: Mozilla/5.0} resp requests.get(req.url, headersheaders, timeout15) resp.raise_for_status() html_content resp.text except Exception as e: return {error: f抓取网页失败: {str(e)}} # 3. 提取正文简化版可用trafilatura等专业库 soup BeautifulSoup(html_content, html.parser) for tag in soup([script, style, nav, footer]): tag.decompose() text soup.get_text() lines (line.strip() for line in text.splitlines()) chunks (phrase.strip() for line in lines for phrase in line.split( )) text .join(chunk for chunk in chunks if chunk) if len(text) 100: return {error: 未能提取到有效文本内容} # 4. 调用摘要模型这里模拟实际可调用本地模型或云API # 例如调用本地运行的ChatGLM3、Qwen等模型的API或使用transformers库 summary text[:req.max_length] ... if len(text) req.max_length else text # 真实场景下这里应调用一个文本摘要接口 # 5. 存入缓存有效期1小时 cache.setex(fsummary:{url_hash}, 3600, summary) return {summary: summary, source: req.url, cached: False}这个例子展示了Skill如何串联多个步骤网络请求、HTML解析、文本处理、缓存、AI调用并处理更复杂的逻辑。8. 资源占用、部署与性能观察资源占用像天气查询这样的简单Skill后端服务FastAPI内存占用通常在50-100MB。如果Skill内集成了本地AI模型如摘要模型则资源消耗取决于模型大小可能需要数百MB甚至数GB内存。CPU使用率在请求处理时会有峰值。部署建议本地测试使用uvicorn或gunicorn运行方便调试。生产环境容器化使用Docker将Skill及其依赖打包确保环境一致。FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]云服务部署到云服务器如AWS EC2、Google Cloud Run、阿里云函数计算FC或容器平台Kubernetes。Serverless对于调用不频繁的Skill可以改造成无服务器函数如AWS Lambda节省成本。性能观察日志务必添加详细日志记录每个请求的输入、输出、耗时和错误。监控使用Prometheus、Grafana或云平台监控工具观察服务的请求量、延迟、错误率。限流与熔断为防止滥用或下游API故障导致服务雪崩应实施请求限流和故障熔断机制。9. 常见问题与排查方法问题现象可能原因排查方式解决方案AI不调用Skill1. Schema定义错误。2. 认证失败。3. AI指令Instructions未明确。4. 网络不通。1. 检查OpenAPI Schema语法确保端点、参数定义正确。2. 查看AI平台日志或调试信息。3. 在对话中明确要求AI使用某个工具。1. 使用OpenAPI验证工具检查Schema。2. 简化认证或先关闭认证测试。3. 在Instructions中清晰描述Skill用途和调用时机。4. 确保AI能访问到Skill服务地址用curl测试。Skill调用超时1. 下游API响应慢。2. 网络延迟高。3. 服务端处理逻辑复杂。1. 单独测试下游API速度。2. 检查服务端日志定位耗时操作。3. 使用time命令或APM工具分析。1. 为下游API设置合理超时如5-10秒。2. 添加缓存避免重复计算。3. 优化代码异步处理耗时任务。返回结果解析错误1. Skill返回的JSON格式不符合AI预期。2. 字段名或类型不匹配。1. 对比Skill实际返回的JSON与Schema定义。2. 查看AI平台的错误日志。1. 确保Skill响应严格遵循Schema中定义的response_model。2. 使用Pydantic模型进行响应序列化避免手拼JSON。本地服务AI无法访问1. 服务仅在127.0.0.1监听。2. 防火墙/安全组阻止。3. AI平台在公网。1. 检查服务启动命令host应为0.0.0.0。2. 检查端口是否开放。3. 在本地用curl或Postman测试公网IP:端口是否通。1. 启动命令改为uvicorn main:app --host 0.0.0.0 --port 8000。2. 使用ngrok等内网穿透工具暴露服务到公网。依赖安装失败1. Python版本不兼容。2. 网络问题导致包下载失败。3. 系统缺少编译依赖如C库。1. 检查python --version。2. 使用pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple换源。3. 查看错误信息安装系统级依赖如build-essential,python3-dev。1. 使用虚拟环境隔离。2. 使用国内镜像源。3. 根据报错信息搜索并安装系统依赖。10. 最佳实践与高阶建议设计先行动手编码前用纸笔或文档明确Skill的输入、输出、处理逻辑和错误处理流程。定义清晰的API接口。单一职责一个Skill只做好一件事。不要创建“万能”Skill。例如“查询天气”和“查询空气质量”应该是两个独立的Skill便于维护和组合。完善的错误处理Skill必须能优雅地处理所有可能出现的异常网络错误、API限流、无效输入、超时等并返回对AI和最终用户都有意义的错误信息。加入缓存对于数据变化不频繁的查询如天气、新闻摘要引入缓存内存缓存如cachetools或Redis可以极大提升响应速度并降低下游API调用次数。安全性不要将API密钥等敏感信息硬编码在代码中使用环境变量或密钥管理服务。对用户输入进行严格的验证和清理防止注入攻击。如果Skill涉及用户数据确保接口有身份认证和授权机制如API Key、JWT。版本化与文档为你的Skill API维护版本如/v1/weather并编写清晰的API文档利用FastAPI自动生成或使用Swagger。测试全覆盖编写单元测试测试业务逻辑和集成测试测试整个API端点确保代码修改不会破坏现有功能。监控与告警生产环境的Skill必须配备监控关注成功率、延迟、调用量。设置告警在服务异常时及时通知。组合使用真正的威力在于Skill的组合。你可以创建一个“工作流”Skill它按顺序调用“抓取新闻”Skill、“翻译”Skill和“生成摘要”Skill从而实现复杂的自动化流水线。掌握Skill的创建意味着你不再只是AI工具的使用者而是成为了其能力的定义者和扩展者。从今天这个简单的天气查询Skill开始尝试将你工作中那些重复、枯燥但规则明确的环节抽象出来封装成一个个高效的Skill。当你积累的Skill库越来越丰富你的AI助手就会变得越来越强大真正实现个人和工作效率的十倍跃迁。
