在AI智能体开发领域如何让一个“聪明”的模型具备执行特定任务的能力是开发者面临的核心挑战。无论是处理复杂的数据分析、自动化办公流程还是集成外部API都需要为AI模型“安装”相应的“技能”。近期围绕“skill”、“Agent Skills”以及“Claude Code”、“Codex”等工具的热度持续攀升反映出开发者对构建和集成AI技能的强烈需求。本文将以一个典型的技能库项目为切入点系统性地拆解AI技能Skill的概念、实现原理并提供从零开始创建、测试到集成一个自定义技能的完整实战指南。无论你是想为Claude、GPTs或其他AI Agent平台开发技能的新手还是希望深入理解Agent架构的进阶开发者都能从本文获得可直接复用的代码和清晰的工程思路。1. 背景与核心概念什么是AI Skill在讨论具体项目之前我们首先要厘清几个关键概念Skill、Agent以及它们之间的关系。这对于后续的开发和集成至关重要。Skill技能可以理解为AI模型能够调用的一个具体功能单元。它通常封装了一段特定的逻辑或能力例如查询天气、发送邮件、计算器、调用某个API等。一个技能通常包含清晰的输入参数定义、内部处理逻辑和格式化的输出。技能的目标是让AI模型能够“即插即用”地扩展其能力边界。Agent智能体是指具备自主感知、决策和执行能力的AI程序。一个强大的Agent往往不是“全能”的而是通过集成多种Skills来应对复杂任务。你可以把Agent想象成一个“大脑”而Skills就是它可灵活使用的“工具手”。Skill与Agent的关系一个Agent可以拥有一个技能列表Skill List。当用户提出一个需求时Agent会分析需求判断是否需要以及调用哪个Skill来完成任务然后将Skill的执行结果整合进回复中。因此Skill的开发是Agent能力扩展的基石。相关生态与工具Claude Code / Codex这些术语常出现在讨论如何为Claude AI模型扩展能力的上下文中。它们可能指代一些社区项目、插件系统或脚本工具旨在为Claude提供运行代码、调用技能的能力。其核心思想是建立一个桥梁让Claude能够识别用户意图并触发本地或远程的技能脚本执行。skills.sh / Agent Skills网站这很可能是一个社区驱动的技能仓库或管理平台开发者可以在这里发布、分享和发现各种预制的Skill方便其他Agent集成使用。理解了这些我们再来看项目标题alchaincyf / zhangxuefeng-skill。这很可能是一个托管在代码平台如GitHub上的技能库其中包含了一个或多个以“张雪峰”相关功能命名的Skill例如可能是高考志愿咨询、专业解读等领域的问答或数据处理技能。我们的目标就是学习如何创建类似这样的技能项目。2. 环境准备与版本说明开发一个AI Skill不依赖于某个固定的IDE或操作系统其核心是编写可执行的逻辑代码。但为了统一演示和便于管理我们假设一个典型的开发环境。基础环境操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04)。本文示例命令以Linux/macOS的bash为主Windows用户可使用WSL或Git Bash获得类似体验。编程语言Python 3.8。Python因其简洁和丰富的库生态是构建AI技能的热门选择。我们将主要使用Python进行演示。版本控制Git。用于管理技能代码。包管理pip (Python)。可选但推荐的工具代码编辑器VS Code, PyCharm。虚拟环境管理venv, conda。强烈建议使用虚拟环境隔离项目依赖。API测试工具Postman, curl。如果技能涉及HTTP API。本项目示例版本说明Python: 3.9核心库无强制要求视技能功能而定。例如网络请求可用requests数据处理可用pandas。重要提示Skill的本质是一个独立的可执行模块其具体依赖完全由技能功能决定。下文示例将创建一个简单的技能因此依赖很少。3. 技能的核心结构与原理拆解一个设计良好的Skill应该具备以下特征这不仅是代码规范也是它能被Agent正确调用的前提。3.1 技能契约输入、处理、输出一个技能必须明确其“契约”输入Input技能需要哪些参数例如一个“天气查询”技能需要city城市名参数。参数应有清晰的名称、类型和说明。处理Process技能内部如何运行这里是技能的核心逻辑可以是纯计算、数据库查询、调用第三方API等。输出Output技能返回什么结果应该是结构化的数据如JSON便于Agent解析和呈现给用户。3.2 技能的实现形式技能可以以多种形式存在本地函数/脚本最简单的形式一个Python函数或一个可执行的Shell脚本。HTTP API服务更通用和可扩展的形式。技能作为一个独立的Web服务运行通过HTTP接口如POST /execute接收输入并返回输出。这种方式便于远程调用和集成。特定框架的插件针对某些Agent框架如LangChain的Tool定义的格式。3.3 技能的描述文件为了让Agent自动发现和理解技能通常需要一个机器可读的描述文件。这个文件告诉Agent“我是什么技能我能干什么你需要给我什么参数”常见格式JSON Schema, OpenAPI Specification (Swagger), 或框架自定义的格式如LangChain Tool的description和args_schema。描述内容技能名称、描述、参数列表名称、类型、描述、是否必需、返回值的类型和描述。下面我们将按照“HTTP API服务”这种通用形式创建一个完整的技能实战项目。4. 完整实战案例构建一个“专业解读”技能我们假设要构建一个类似zhangxuefeng-skill的项目其功能是根据用户输入的专业名称返回该专业的简要解读、核心课程和就业方向。4.1 创建项目结构首先创建一个清晰的项目目录。mkdir zhangxuefeng-skill-demo cd zhangxuefeng-skill-demo项目结构规划如下zhangxuefeng-skill-demo/ ├── skill_demo/ # 技能核心包 │ ├── __init__.py │ └── major_skill.py # 专业解读技能实现 ├── data/ # 数据文件可选 │ └── majors.json # 专业数据库 ├── requirements.txt # 项目依赖 ├── app.py # FastAPI 主应用 ├── skill_manifest.json # 技能描述文件 └── README.md # 项目说明4.2 添加依赖与配置创建并激活Python虚拟环境然后编写requirements.txt。python -m venv venv # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activaterequirements.txt内容fastapi0.104.1 uvicorn[standard]0.24.0 pydantic2.5.0安装依赖pip install -r requirements.txt4.3 编写核心代码第一步创建数据文件简化示例data/majors.json{ 计算机科学与技术: { description: 研究计算机设计、制造和利用计算机进行信息获取、表示、存储、处理、控制等的理论、原则、方法和技术的学科。, core_courses: [数据结构, 操作系统, 计算机网络, 计算机组成原理, 算法设计与分析], career_paths: [软件开发工程师, 算法工程师, 系统架构师, 网络安全工程师, 科研人员] }, 金融学: { description: 研究价值判断和价值规律的学科主要包括金融学、经济学、投资学、银行学、证券学、保险学、信托学等。, core_courses: [货币银行学, 国际金融, 证券投资学, 公司金融, 金融风险管理], career_paths: [银行职员, 证券分析师, 投资顾问, 风险控制专员, 金融产品经理] }, 临床医学: { description: 一门实践性很强的应用科学专业致力于培养具备基础医学、临床医学的基本理论和医疗预防的基本技能的高级医学人才。, core_courses: [人体解剖学, 生理学, 病理学, 药理学, 内科学, 外科学], career_paths: [临床医生, 医学研究员, 公共卫生医师, 医疗管理人员] } }第二步实现技能逻辑skill_demo/major_skill.pyimport json from pathlib import Path from typing import Dict, Optional, Any from pydantic import BaseModel, Field class MajorQueryInput(BaseModel): 专业查询技能的输入参数模型 major_name: str Field(..., description需要查询的专业名称例如计算机科学与技术) class MajorSkill: 专业解读技能核心类 def __init__(self, data_path: str data/majors.json): 初始化技能加载专业数据 self.data_path Path(data_path) self.majors_db: Dict[str, Any] self._load_data() def _load_data(self) - Dict: 加载JSON格式的专业数据 try: with open(self.data_path, r, encodingutf-8) as f: return json.load(f) except FileNotFoundError: print(f警告数据文件 {self.data_path} 未找到使用空数据库。) return {} except json.JSONDecodeError as e: print(f错误数据文件 {self.data_path} 格式错误: {e}) return {} def query_major(self, input_data: MajorQueryInput) - Dict[str, Any]: 查询专业信息的主方法 Args: input_data: 包含专业名称的输入参数 Returns: 包含查询结果或错误信息的字典 major_name input_data.major_name.strip() if not major_name: return { success: False, error: 专业名称不能为空, data: None } # 简单的大小写和模糊匹配实际项目可使用更复杂的搜索引擎 matched_key None for key in self.majors_db.keys(): if major_name.lower() in key.lower(): matched_key key break if matched_key and matched_key in self.majors_db: major_info self.majors_db[matched_key] return { success: True, data: { matched_major: matched_key, description: major_info.get(description, 暂无描述), core_courses: major_info.get(core_courses, []), career_paths: major_info.get(career_paths, []), source: 本地数据库 } } else: # 如果本地未找到可以在这里集成网络API作为后备方案 return { success: False, error: f未找到专业 {major_name} 的相关信息, suggestions: list(self.majors_db.keys())[:3] if self.majors_db else [], data: None }第三步创建HTTP API服务app.pyfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel from skill_demo.major_skill import MajorSkill, MajorQueryInput app FastAPI( title专业解读技能API, description一个提供大学专业信息解读的AI技能服务, version1.0.0 ) # 初始化技能实例 major_skill MajorSkill() class SkillExecuteRequest(BaseModel): 技能执行请求体 major_name: str class SkillExecuteResponse(BaseModel): 技能执行响应体 success: bool data: dict None error: str None execution_time_ms: float None app.get(/) async def root(): 服务根路径返回基本信息 return { service: Major Interpretation Skill, version: 1.0, available_endpoints: { GET /: 此信息页, POST /execute: 执行专业查询技能, GET /manifest: 获取技能描述清单 } } app.post(/execute, response_modelSkillExecuteResponse) async def execute_skill(request: SkillExecuteRequest): 执行专业解读技能 这是Agent调用技能的主要入口。 import time start_time time.time() try: # 将请求参数转换为技能所需的输入模型 skill_input MajorQueryInput(major_namerequest.major_name) # 调用技能核心逻辑 result major_skill.query_major(skill_input) # 计算执行时间 execution_time_ms (time.time() - start_time) * 1000 result[execution_time_ms] round(execution_time_ms, 2) return SkillExecuteResponse(**result) except Exception as e: raise HTTPException(status_code500, detailf技能执行内部错误: {str(e)}) app.get(/manifest) async def get_skill_manifest(): 返回技能的描述清单Manifest。 Agent可以通过此端点自动发现技能的元数据。 manifest { name: major_interpreter, version: 1.0, description: 根据专业名称提供该专业的简要解读、核心课程和就业方向信息。, author: Your Name, endpoint: /execute, input_schema: { type: object, properties: { major_name: { type: string, description: 需要查询的大学专业名称例如计算机科学与技术、金融学 } }, required: [major_name] }, output_schema: { type: object, properties: { success: {type: boolean}, data: { type: object, properties: { matched_major: {type: string}, description: {type: string}, core_courses: {type: array, items: {type: string}}, career_paths: {type: array, items: {type: string}}, source: {type: string} } }, error: {type: string}, execution_time_ms: {type: number} } }, examples: [ { input: {major_name: 计算机科学与技术}, output: { success: True, data: { matched_major: 计算机科学与技术, description: 研究计算机设计、制造和利用计算机进行信息获取、表示、存储、处理、控制等的理论、原则、方法和技术的学科。, core_courses: [数据结构, 操作系统, 计算机网络, 计算机组成原理, 算法设计与分析], career_paths: [软件开发工程师, 算法工程师, 系统架构师, 网络安全工程师, 科研人员], source: 本地数据库 } } } ] } return manifest if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)第四步创建技能描述文件skill_manifest.json(此文件内容与API中的/manifest端点返回的一致可用于离线注册或文档){ name: major_interpreter, version: 1.0, description: 根据专业名称提供该专业的简要解读、核心课程和就业方向信息。, author: Your Name, endpoint: http://localhost:8000/execute, input_schema: { type: object, properties: { major_name: { type: string, description: 需要查询的大学专业名称例如计算机科学与技术、金融学 } }, required: [major_name] } }4.4 运行与验证启动技能服务python app.py服务将在http://localhost:8000启动。测试技能API方法一使用浏览器或curl访问根路径curl http://localhost:8000/方法二获取技能清单curl http://localhost:8000/manifest方法三执行技能查询使用curlcurl -X POST http://localhost:8000/execute \ -H Content-Type: application/json \ -d {major_name: 金融学}方法四使用Python requests库测试创建一个测试脚本test_skill.pyimport requests import json def test_skill(): url http://localhost:8000/execute payload {major_name: 临床医学} headers {Content-Type: application/json} try: response requests.post(url, jsonpayload, headersheaders) response.raise_for_status() result response.json() print(json.dumps(result, indent2, ensure_asciiFalse)) except requests.exceptions.RequestException as e: print(f请求失败: {e}) if __name__ __main__: test_skill()运行它python test_skill.py预期输出 成功调用后你将收到一个结构化的JSON响应类似于{ success: true, data: { matched_major: 临床医学, description: 一门实践性很强的应用科学专业致力于培养具备基础医学、临床医学的基本理论和医疗预防的基本技能的高级医学人才。, core_courses: [人体解剖学, 生理学, 病理学, 药理学, 内科学, 外科学], career_paths: [临床医生, 医学研究员, 公共卫生医师, 医疗管理人员], source: 本地数据库 }, error: null, execution_time_ms: 1.24 }4.5 结果说明至此我们已经成功创建并运行了一个完整的、符合通用规范的AI技能服务。这个服务提供了清晰的API接口(POST /execute)供Agent调用。自描述清单(GET /manifest)让Agent能自动理解技能的功能和调用方式。结构化的输入输出使用Pydantic模型确保数据格式正确。错误处理对无效输入和内部错误有明确的反馈。可扩展的数据层当前使用本地JSON文件未来可以轻松替换为数据库或网络API。5. 常见问题与排查思路在开发和使用Skill过程中你可能会遇到以下问题问题现象常见原因解决思路服务启动失败端口被占用端口8000已被其他程序使用。1. 更改app.py中的端口号如port8001。2. 查找并停止占用端口的进程lsof -i:8000(macOS/Linux) 或netstat -ano | findstr :8000(Windows)。调用/executeAPI 返回 422 错误请求体JSON格式错误或缺少必需的参数。1. 检查请求头Content-Type: application/json。2. 确保JSON体包含major_name字段且值为字符串。3. 使用Postman或curl的-v参数查看详细请求和响应。技能查询总是返回“未找到专业”1. 数据文件路径错误或未加载。2. 专业名称匹配逻辑过于严格如大小写敏感。1. 检查data/majors.json文件是否存在且格式正确。2. 在major_skill.py的_load_data方法中添加日志确认数据已加载。3. 优化匹配逻辑如统一转为小写比较或引入模糊匹配库如fuzzywuzzy。Agent无法发现或调用技能1. Agent配置中未正确添加技能端点。2. 技能清单manifest格式不符合Agent要求。3. 网络不通。1. 确认Agent配置中技能的URL如http://localhost:8000正确。2. 核对Agent框架所需的技能描述格式调整/manifest端点的输出。3. 确保Agent所在环境能访问技能服务考虑使用公网IP或内网穿透。技能执行速度慢1. 数据文件过大每次查询都全量加载。2. 匹配算法复杂度高。3. 集成了慢速的外部API。1. 将数据加载到内存缓存中避免重复I/O。2. 对专业名称建立索引如字典树。3. 为外部API调用设置超时并考虑异步处理。依赖安装失败网络问题或Python环境不兼容。1. 使用国内镜像源pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。2. 确认Python版本为3.8。3. 在虚拟环境中操作。6. 最佳实践与工程建议将技能从“能运行”提升到“好用、可靠、易维护”需要遵循一些工程最佳实践。6.1 技能设计原则单一职责一个技能只做好一件事。不要创建“超级技能”而应将复杂功能拆分为多个小技能由Agent协调调用。接口稳定技能的输入输出Schema一旦确定应尽量保持向后兼容。如需变更考虑版本化如/v2/execute。无状态性技能服务本身应尽量设计为无状态的Stateless这样便于水平扩展和容灾。状态信息应由调用方Agent或外部存储管理。6.2 代码与配置管理配置外部化将数据库连接字符串、API密钥、服务端口等配置信息抽离到环境变量或配置文件中如.env不要硬编码在代码里。完善的日志在技能的关键节点如收到请求、开始处理、处理完成、发生错误记录日志便于监控和调试。可以使用Python的logging模块。输入验证与清理除了使用Pydantic进行类型验证还应对输入内容进行业务逻辑验证和清理如防止SQL注入、XSS攻击特别是当技能涉及数据库或命令执行时。超时与重试如果技能内部需要调用其他服务必须设置合理的超时时间并实现重试机制使用指数退避等策略。6.3 安全性考量认证与授权如果技能涉及敏感操作或数据必须为API添加认证如API Key、JWT。FastAPI可以方便地集成依赖项来实现。限流防止恶意用户高频调用耗尽资源。可以使用中间件实现简单的IP限流或集成更专业的网关。敏感信息脱敏日志中不应记录密码、密钥等敏感信息。6.4 性能与可观测性健康检查端点添加一个/health端点用于检查技能服务的状态如数据库连接、依赖服务状态。这对于容器化部署和运维至关重要。指标暴露考虑使用Prometheus等工具暴露技能的性能指标如请求量、延迟、错误率方便监控。异步处理对于耗时较长的技能如文件处理、复杂计算应考虑使用异步框架如FastAPI本身支持async/await或消息队列避免阻塞请求线程。6.5 部署与集成容器化使用Docker将技能及其依赖打包成镜像确保环境一致性便于在任何地方部署。# Dockerfile 示例 FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [uvicorn, app:app, --host, 0.0.0.0, --port, 8000]服务发现在微服务架构中技能服务启动后应向服务注册中心如Consul, Nacos注册Agent通过注册中心发现技能而不是硬编码地址。版本管理对技能代码使用Git进行版本控制。考虑为技能API和描述清单manifest定义版本号并在接口变更时妥善管理。7. 总结与学习路线通过本文的实战我们完成了一个AI技能从概念到实现、从开发到测试的完整闭环。我们创建了一个提供“专业解读”功能的HTTP API技能服务它具备清晰的接口、自描述能力和良好的结构。本文关键点回顾概念清晰理解了Skill作为Agent能力扩展单元的角色。结构规范掌握了技能应具备的输入、处理、输出契约以及描述清单Manifest的重要性。技术实现使用FastAPI快速构建了RESTful技能服务利用Pydantic保证了数据验证。工程化思维探讨了错误处理、日志、配置、安全、部署等生产级考量。下一步学习方向集成到具体Agent尝试将本技能集成到你正在使用的Agent框架中如LangChain Tools、AutoGPT插件系统或研究如何让Claude Code调用此HTTP API。丰富技能功能为本技能添加更强大的后端例如连接真实的专业数据库、集成网络爬虫获取实时信息、或添加简单的推荐算法“学了A专业的人也看了B专业”。探索技能编排学习如何让一个Agent顺序或并行调用多个技能来完成复杂任务如“先查询专业再根据就业方向查询相关招聘信息”。加入技能生态将你的技能按照skills.sh或类似社区的规范进行包装和提交分享给其他开发者。技能开发是构建实用AI应用的关键一步。从这个小而美的项目开始逐步积累你将能够创建出功能强大、鲁棒性高的智能体生态系统。动手修改代码添加一个新专业或者为技能增加一个“热门专业排行”的端点是巩固学习的最佳方式。如果在实践中遇到问题回顾第5节的排查思路并善用搜索引擎和开发者社区。