1. 项目概述与核心价值最近在折腾AI助手本地化部署和技能扩展的朋友应该都听说过Claude API和各类围绕它构建的第三方工具。今天要聊的这个项目——SirPangolin/sirpangolin-claude-skills是我在深度使用Claude API进行自动化工作流构建时发现的一个相当有意思的“技能库”项目。简单来说它不是一个完整的应用而是一个专门为Claude API设计的、开源的、可扩展的“技能插件”集合。想象一下你给Claude API发一个请求它不仅能理解你的文字还能帮你执行一些具体的操作比如查询天气、翻译文本、计算复杂公式甚至调用外部API获取实时数据。这就是“技能”的核心价值让大语言模型从一个“聊天机器人”升级为一个能真正“做事”的智能助手。SirPangolin-claude-skills项目就提供了这样一套现成的、经过设计的技能模板和实现让你可以快速集成到自己的Claude应用中省去了从零设计技能交互逻辑、处理错误、定义输入输出格式的麻烦。这个项目特别适合两类开发者一是正在基于Claude API开发智能助手、客服机器人或自动化脚本希望快速增加实用功能的二是对AI Agent智能体和工具调用Tool Calling机制感兴趣想通过实际代码学习如何设计让大语言模型与外部世界交互的接口的。我自己在用它搭建一个内部知识库问答兼日常任务自动化工具时发现它提供的技能结构清晰扩展起来也很顺手能节省大量前期设计的时间。2. 项目架构与设计思路拆解2.1 核心概念什么是Claude Skill在深入代码之前我们必须先厘清一个关键概念。在Claude API的语境下特别是结合Anthropic官方推荐的“工具使用”Tool Use模式一个“Skill”本质上是一个可被Claude模型识别、描述并请求调用的外部函数或API。模型本身并不能直接执行代码或访问网络但当我们将技能以特定格式通常是JSON Schema描述给Claude时它就能在对话中判断是否需要调用该技能并生成符合技能要求的调用参数。SirPangolin-claude-skills项目将这些技能进行了封装和标准化。每个技能通常包含以下几个核心部分技能定义Skill Definition一个JSON或Python字典严格按照Claude Tool Use的格式描述了技能的名称、描述、输入参数及其类型、是否必需、描述。这是Claude模型“理解”该技能的说明书。技能执行器Skill Executor一个Python函数或类方法包含了真正的执行逻辑。当Claude决定调用某个技能并提供了参数后这部分代码会被触发运行。技能注册与路由一个管理机制负责将所有可用的技能收集起来并在收到Claude的调用请求时找到对应的执行器并运行它最后将结果返回。项目的设计思路很清晰解耦、模块化、即插即用。每个技能都是一个独立的模块你不需要修改核心的对话处理逻辑只需要增删技能模块文件就能动态地改变你的AI助手的能力范围。2.2 技术栈与依赖关系这个项目主要基于Python生态。其核心依赖通常包括anthropic官方的Claude Python SDK用于与Claude API通信发送消息并处理包含工具调用请求的响应。pydantic用于数据验证和设置管理。很多技能会用它来定义强类型的输入参数模型确保从Claude那里接收到的参数是正确、完整的避免运行时错误。requests或httpx对于需要调用外部Web API的技能如天气、汇率查询这是必不可少的HTTP客户端库。python-dotenv管理API密钥等敏感配置遵循十二要素应用的原则将配置与环境分离。项目的结构通常不是框架级的复杂而是一个清晰的库结构。你可能会看到类似下面的目录组织sirpangolin-claude-skills/ ├── skills/ # 核心技能目录 │ ├── __init__.py │ ├── calculator.py # 计算器技能 │ ├── web_search.py # 网络搜索技能 │ ├── weather.py # 天气查询技能 │ └── ... # 其他技能 ├── core/ │ ├── skill_manager.py # 技能注册与管理中心 │ └── schemas.py # 共享的数据模型定义 ├── config.py # 配置文件 ├── example_usage.py # 使用示例 └── requirements.txt # 项目依赖这种结构让技能的开发和添加变得非常直观你基本上就是在skills文件夹里新建一个Python文件实现好定义和执行器然后在管理器里注册一下就行。2.3 与Claude API的交互流程理解这个项目必须理解它如何嵌入到完整的Claude API调用流程中。一个典型的、集成了技能调用的对话回合如下初始化你的应用启动加载所有技能模块生成一个包含所有技能定义的列表。这个列表的格式是Claude API要求的tools参数。用户请求用户发送一条消息例如“北京今天的天气怎么样顺便把摄氏温度转换成华氏。”调用Claude API你将用户消息和tools参数技能列表一起发送给Claude API。模型决策Claude模型分析用户请求识别出需要调用get_weather查询天气和unit_converter单位转换这两个技能。它会停止生成普通的文本回复转而返回一个或多个tool_use块里面包含了它想要调用的技能名称和它推断出的参数例如location“北京”target_unit“fahrenheit”。本地执行技能你的应用Skill Manager接收到Claude的响应解析出tool_use信息根据技能名称找到对应的本地执行函数传入参数并执行。get_weather函数可能去调用一个天气APIunit_converter函数进行本地计算。返回结果给Claude你将技能执行的结果按照Claude API要求的格式作为新的消息内容发送回去。这个消息的类型是tool_result包含对应的tool_use_id和执行结果。Claude整合回复Claude接收到技能执行结果后会基于这些事实信息组织成一段自然、连贯的文本回复给用户。例如“北京今天晴气温15摄氏度。换算成华氏温度是59度。”SirPangolin-claude-skills项目主要精彩地解决了第1步技能定义标准化、第5步技能执行路由的通用性问题让你可以专注于第5步中每个技能的具体业务逻辑实现。注意这里有一个关键点Claude模型本身并不运行你的技能代码。它只负责“思考”是否需要调用技能以及参数应该是什么。真正的代码执行完全发生在你的本地服务器或运行环境中。这保证了安全性你的内部API密钥和逻辑不会泄露给Anthropic。3. 核心技能解析与实现细节3.1 剖析一个典型技能网络搜索我们以项目中可能包含的一个web_search技能为例深入看看一个技能是如何从定义到实现的。技能定义JSON Schema 这是给Claude看的“说明书”必须严格按照Anthropic的Tools格式。在代码中它通常被写成一个Python字典或由Pydantic模型生成。# 在 skills/web_search.py 中 web_search_tool_schema { name: web_search, description: 在互联网上搜索最新信息。当用户的问题涉及实时事件、最新新闻、未知事实或需要最新数据的查询时使用此工具。, input_schema: { type: object, properties: { query: { type: string, description: 要搜索的关键词或问题尽量具体明确。 }, max_results: { type: integer, description: 返回的最大结果数量默认为5。, default: 5 } }, required: [query] } }name: 技能的唯一标识符Claude在tool_use中会引用这个名字。description: 至关重要这是Claude判断是否调用该技能的主要依据。描述必须清晰、准确说明技能的用途和调用时机。例如这里强调了“实时事件”、“最新信息”。input_schema: 定义了Claude需要生成的参数。query是必填的字符串max_results是可选整数且有默认值。清晰的参数描述能帮助Claude更好地生成参数。技能执行器 这是真正执行搜索的代码。项目可能会集成Serper API、SerpAPI或Google Custom Search JSON API等。import os import requests from typing import Dict, Any from ..core.schemas import SearchResult # 假设有一个结果模型 def execute_web_search(query: str, max_results: int 5) - Dict[str, Any]: 执行网络搜索并返回格式化结果。 api_key os.getenv(SERPER_API_KEY) if not api_key: raise ValueError(SERPER_API_KEY 环境变量未设置) url https://google.serper.dev/search headers {X-API-KEY: api-key, Content-Type: application/json} payload {q: query, num: max_results} try: response requests.post(url, headersheaders, jsonpayload, timeout10) response.raise_for_status() # 检查HTTP错误 data response.json() # 解析结果提取标题、链接、摘要 search_results [] for item in data.get(organic, [])[:max_results]: result SearchResult( titleitem.get(title), linkitem.get(link), snippetitem.get(snippet) ) search_results.append(result.dict()) return { success: True, query: query, results: search_results, source: Serper API } except requests.exceptions.RequestException as e: # 网络请求异常处理 return { success: False, error: f搜索请求失败: {str(e)}, query: query } except KeyError as e: # API响应格式异常处理 return { success: False, error: f解析搜索结果时出错: {str(e)}, raw_response: data # 注意生产环境可能需脱敏 }实现要点与避坑指南密钥管理绝对不要将API密钥硬编码在代码中。必须使用os.getenv从环境变量读取。在项目根目录提供.env.example文件引导用户配置是良好实践。错误处理网络请求和API调用充满不确定性。必须用try-except包裹捕获requests异常超时、连接错误、HTTP状态码非200和数据处理异常KeyError。返回结构化的错误信息方便Claude向用户解释。结果格式化返回给Claude的结果应该结构清晰、信息浓缩。不要直接返回原始API的冗长JSON。提取出标题、链接、摘要等核心信息组装成一个列表。这能减少Claude处理的数据量并使其更容易生成高质量的总结。超时设置务必为网络请求设置超时如timeout10避免因为外部API挂起而导致你的整个应用线程阻塞。3.2 另一个实用技能文件系统操作谨慎使用为了展示技能的多样性我们再看一个理论上可能存在的read_file技能。请注意这类技能具有高风险必须严格控制。技能定义read_file_tool_schema { name: read_file, description: 读取指定路径的文本文件内容。仅用于用户明确要求读取已知文件且该文件位于预设的安全目录内时。切勿用于尝试访问系统文件或用户未指定的文件。, input_schema: { type: object, properties: { file_path: { type: string, description: 相对于安全根目录的文件路径。例如documents/report.txt。禁止使用..或绝对路径。 } }, required: [file_path] } }关键设计——安全性描述中强调限制在description里明确规定了使用条件“预设的安全目录”和禁止行为。这在一定程度上可以“指导”Claude的调用行为。路径规范化与校验在执行器中必须进行严格的路径安全检查。import os from pathlib import Path def execute_read_file(file_path: str) - Dict[str, Any]: # 1. 定义安全根目录 SAFE_BASE_DIR Path(/path/to/safe/directory) # 应从配置读取 # 2. 解析输入路径 requested_path Path(file_path) # 3. 防止目录遍历攻击确保最终路径在安全目录下 try: absolute_path (SAFE_BASE_DIR / requested_path).resolve() absolute_path.relative_to(SAFE_BASE_DIR.resolve()) except ValueError: return {success: False, error: 访问路径超出许可范围。} # 4. 检查文件是否存在且为文件 if not absolute_path.is_file(): return {success: False, error: 指定路径不是文件或不存在。} # 5. 检查文件大小防止读取超大文件 if absolute_path.stat().st_size 5 * 1024 * 1024: # 5MB限制 return {success: False, error: 文件过大拒绝读取。} # 6. 读取文件可考虑编码处理 try: content absolute_path.read_text(encodingutf-8) return {success: True, content: content, file_path: str(requested_path)} except UnicodeDecodeError: return {success: False, error: 文件不是有效的UTF-8文本文件。} except Exception as e: return {success: False, error: f读取文件时发生未知错误: {str(e)}}重要警告文件操作、系统命令执行这类技能极其危险。在开源项目中这类技能要么不提供如果提供必须有极其醒目的安全警告并默认关闭。在实际部署中必须结合用户身份认证、授权和严格的访问控制列表来使用绝不能对未经审查的输入开放。3.3 技能管理器的实现技能管理器Skill Manager是这个项目的大脑它负责技能的注册、列表提供和调用路由。一个简单的实现可能如下# core/skill_manager.py from typing import Dict, Any, List, Callable import importlib import pkgutil import inspect class SkillManager: def __init__(self): self._skills {} # name - {schema: ..., executor: ...} def register_skill(self, name: str, schema: Dict, executor: Callable): 注册单个技能 if name in self._skills: raise ValueError(f技能 {name} 已注册。) self._skills[name] {schema: schema, executor: executor} def register_skills_from_package(self, package_name: str): 自动从指定Python包中扫描并注册技能 package importlib.import_module(package_name) for _, module_name, is_pkg in pkgutil.iter_modules(package.__path__): if is_pkg: continue full_module_name f{package_name}.{module_name} module importlib.import_module(full_module_name) # 约定每个技能模块暴露一个 skill_schema 和一个 execute 函数 if hasattr(module, skill_schema) and hasattr(module, execute): schema module.skill_schema executor module.execute self.register_skill(schema[name], schema, executor) property def tool_schemas(self) - List[Dict]: 获取所有技能的定义用于传给Claude API return [skill[schema] for skill in self._skills.values()] def execute_tool(self, tool_name: str, tool_input: Dict[str, Any]) - Dict[str, Any]: 执行指定技能 if tool_name not in self._skills: raise KeyError(f未找到技能: {tool_name}) skill self._skills[tool_name] executor skill[executor] # 这里可以添加统一的预处理、日志、监控等逻辑 print(f[Skill Manager] 执行技能: {tool_name}, 输入: {tool_input}) try: result executor(**tool_input) return result except Exception as e: # 统一的技能执行异常处理 print(f[Skill Manager] 技能 {tool_name} 执行失败: {e}) return {success: False, error: f技能执行内部错误: {str(e)}}管理器的设计考量自动发现register_skills_from_package方法提供了自动扫描skills目录并注册的技能的能力遵循了“约定优于配置”的原则开发者只需按规范创建文件即可无需手动注册。统一接口execute_tool方法提供了统一的调用入口这里是添加横切关注点Cross-cutting Concerns的绝佳位置比如日志记录记录每个技能的调用、参数和结果用于调试和审计。性能监控计算技能执行耗时便于发现性能瓶颈。错误兜底用try-except包裹执行过程防止单个技能崩溃导致整个服务挂掉。输入验证在执行前可以先用Pydantic模型对tool_input进行二次验证确保数据格式万无一失。清晰的分离管理器只负责“调度”不关心技能的具体逻辑。技能开发者只需关注自己的schema和execute函数。4. 集成与实战构建你的技能化AI助手4.1 项目初始化与环境配置假设你已经克隆了SirPangolin/sirpangolin-claude-skills项目或者基于其结构创建了自己的项目。第一步是搭建环境。# 1. 克隆项目假设 # git clone https://github.com/SirPangolin/sirpangolin-claude-skills.git # cd sirpangolin-claude-skills # 2. 创建虚拟环境推荐 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 3. 安装依赖 pip install -r requirements.txt # 典型依赖anthropic0.25.0, pydantic2.0, requests2.31, python-dotenv1.0 # 4. 配置环境变量 cp .env.example .env # 编辑 .env 文件填入你的 Claude API Key 和其他技能所需的API Key如Serper API Key # ANTHROPIC_API_KEYsk-ant-xxx... # SERPER_API_KEYyyy... # SAFE_BASE_DIR/path/to/your/data4.2 编写主循环对话逻辑接下来我们需要编写一个主程序将Claude API、技能管理器和我们自己的对话逻辑串联起来。下面是一个简化的、但功能完整的示例# main.py import os from anthropic import Anthropic from dotenv import load_dotenv from core.skill_manager import SkillManager # 加载环境变量 load_dotenv() def main(): # 1. 初始化Claude客户端和技能管理器 client Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) skill_manager SkillManager() # 2. 自动注册所有技能假设技能包名为‘skills’ skill_manager.register_skills_from_package(skills) # 3. 准备对话历史 messages [] system_prompt 你是一个有帮助的AI助手可以使用各种工具来获取信息或执行任务。 如果你需要实时信息、计算、单位转换等请主动使用我提供的工具。 使用工具后请根据返回的结果用清晰、友好的语言回答用户的问题。 print(AI助手已启动。输入‘退出’或‘quit’结束对话。) while True: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: break # 4. 将用户输入加入消息历史 messages.append({role: user, content: user_input}) # 5. 调用Claude API传入技能定义 try: response client.messages.create( modelclaude-3-5-sonnet-20241022, # 使用支持工具调用的模型 max_tokens1024, systemsystem_prompt, messagesmessages, toolsskill_manager.tool_schemas # 关键传入技能列表 ) except Exception as e: print(f调用Claude API失败: {e}) continue # 6. 处理Claude的响应 # 响应可能包含文本内容也可能包含工具调用请求 full_response_content [] tool_results_to_send [] for block in response.content: if block.type text: # 普通文本回复直接收集 full_response_content.append(block.text) elif block.type tool_use: # Claude请求调用工具 tool_name block.name tool_input block.input # 这是一个字典 tool_use_id block.id print(f[助手请求调用工具] {tool_name}: {tool_input}) # 7. 通过技能管理器执行工具 tool_result skill_manager.execute_tool(tool_name, tool_input) # 8. 收集工具执行结果准备发回给Claude tool_results_to_send.append({ type: tool_result, tool_use_id: tool_use_id, content: str(tool_result) # 注意content需要是字符串或文本块列表 }) # 可选将工具执行结果也显示给用户看增加透明度 print(f[工具执行结果] {tool_name}: {tool_result}) # 9. 如果有工具调用需要将结果发回给Claude进行下一轮 if tool_results_to_send: # 先将Claude之前生成的文本如果有加入历史 if full_response_content: messages.append({role: assistant, content: .join(full_response_content)}) # 再将工具执行结果作为用户消息实际上是assistant的tool_use的反馈加入历史 for result in tool_results_to_send: messages.append({role: user, content: result}) # 注意这里role是‘user’这是API规范 # 重新调用Claude让它基于工具结果生成最终回复 try: second_response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, systemsystem_prompt, messagesmessages, toolsskill_manager.tool_schemas ) # 处理第二轮响应这次应该只有文本了 final_text for block in second_response.content: if block.type text: final_text block.text print(f\n助手: {final_text}) # 将最终助手回复加入历史 messages.append({role: assistant, content: final_text}) except Exception as e: print(f第二轮API调用失败: {e}) else: # 没有工具调用直接输出Claude的文本回复 assistant_reply .join(full_response_content) print(f\n助手: {assistant_reply}) messages.append({role: assistant, content: assistant_reply}) if __name__ __main__: main()这个主循环清晰地展示了Claude工具调用的“多轮对话”特性第一轮Claude可能返回工具调用请求我们执行工具后将结果作为新的消息输入进行第二轮调用Claude再基于结果生成最终回复。4.3 创建你自己的自定义技能扩展性是本项目的精髓。添加一个新技能非常简单。假设我们要添加一个“生成随机密码”的技能。在skills/目录下创建新文件skills/generate_password.py。实现技能定义和执行器# skills/generate_password.py import secrets import string skill_schema { name: generate_password, description: 生成一个安全的随机密码。当用户要求创建密码或需要随机字符串时使用。, input_schema: { type: object, properties: { length: { type: integer, description: 密码的长度默认为12。建议不少于8位。, default: 12 }, use_digits: { type: boolean, description: 是否包含数字0-9默认为True。, default: True }, use_special_chars: { type: boolean, description: 是否包含特殊字符!#$%等默认为True。, default: True } }, required: [] # 所有参数都有默认值故非必需 } } def execute(length: int 12, use_digits: bool True, use_special_chars: bool True) - dict: 生成随机密码 if length 4: return {success: False, error: 密码长度不能少于4位。} alphabet string.ascii_letters # 大小写字母 if use_digits: alphabet string.digits if use_special_chars: alphabet !#$%^*()_-[]{}|;:,.? if not alphabet: return {success: False, error: 字符集不能为空请至少启用字母、数字或特殊字符中的一项。} # 使用secrets模块生成密码比random更安全 password .join(secrets.choice(alphabet) for _ in range(length)) # 返回结果 return { success: True, password: password, length: length, contains_digits: use_digits, contains_special_chars: use_special_chars, hint: 请妥善保管生成的密码不要明文存储。 }无需修改主程序因为技能管理器是自动扫描注册的重启你的main.py新的generate_password技能就已经可用了。你可以直接问助手“帮我生成一个16位的强密码。”5. 常见问题、调试技巧与性能优化5.1 Claude不调用技能排查指南这是集成初期最常见的问题。你的技能定义好了管理器也注册了但Claude就是“装傻”只用文本回复。可以从以下几个方面排查检查技能描述Description这是最重要的因素描述必须清晰、具体、无歧义并明确说明调用时机。差的描述“一个计算工具。”好的描述“执行数学计算。当用户的问题包含算术表达式如‘12*3’、数学问题如‘计算圆的面积’或明确要求计算时使用。可以处理加减乘除、乘方、开方和三角函数。”技巧在描述中多使用一些可能触发调用的用户问题示例关键词。检查系统提示词System Prompt系统提示词需要“鼓励”Claude使用工具。在提示词中明确告诉它“你拥有一些工具当需要获取实时信息、进行计算或执行特定任务时请主动使用它们。”避免使用过于限制性的提示词。检查模型版本确保你使用的Claude模型版本支持工具调用。例如claude-3-opus-20240229、claude-3-sonnet-20240229及之后的-20241022版本都支持。使用旧版本可能无法触发。简化测试开始时使用一个非常明确、直接的请求测试。例如不要问“今天天气如何”而是问“请使用天气查询工具告诉我北京今天的天气。”如果这样能调用说明技能定义和集成是通的问题在于描述和提示词对自然语言的引导不够。查看API响应在代码中打印出Claude API的完整响应response对象。检查其中是否包含tool_use类型的content块。如果没有说明Claude认为不需要调用工具。如果有说明调用逻辑已经走到你这边了接下来要检查你的技能管理器是否正确解析和执行。5.2 技能执行错误处理与用户反馈技能执行可能失败网络超时、API限额、无效输入等。如何优雅地处理并反馈给用户结构化错误返回如之前示例技能执行函数应始终返回一个字典包含success字段。失败时提供详细的error信息。这有助于Claude生成友好的错误回复例如“查询天气时遇到了网络问题请稍后再试。”在主循环中捕获异常技能管理器execute_tool方法已经有了try-except。但还可以更进一步将异常分类。例如网络错误可以提示用户重试权限错误则提示用户操作不被允许。让Claude解释错误将结构化的错误信息返回给Claude它通常能很好地将其转化为对用户友好的解释。避免直接将Python异常堆栈返回给用户。5.3 性能优化与成本控制技能调用次数每次工具调用都意味着至少两轮Claude API请求请求调用 返回结果这会增加延迟和成本。在设计技能时尽量让一个技能完成更多相关工作。例如一个“金融数据查询”技能可以同时返回股价、涨跌幅和市值而不是让Claude分别调用三个技能。结果缓存对于频繁查询且数据更新不频繁的技能如“汇率换算”基础汇率可能一天更新一次可以引入缓存机制如使用functools.lru_cache或Redis。在技能执行器中先检查缓存命中则直接返回避免重复调用外部API。异步执行如果多个技能之间没有依赖关系可以考虑使用异步IOasyncioaiohttp来并发执行显著降低总延迟。这需要将技能执行器改造成异步函数并使用asyncio.gather来并发调用。不过这增加了代码复杂度需根据实际需求权衡。监控与日志记录每个技能的调用频率、执行时间和成功率。这能帮你发现性能瓶颈哪个技能最慢、成本中心哪个技能调用最费钱和不可靠的技能哪个技能失败率最高从而进行有针对性的优化或替换。5.4 安全加固建议输入验证与净化对所有来自Claude的输入参数进行严格的验证和净化。即使Claude生成的参数通常格式正确也要防止潜在的注入攻击。使用Pydantic模型进行验证是最佳实践。权限控制不是所有用户都应该能调用所有技能。在实际应用中应将技能管理器与用户身份系统结合。在execute_tool前检查当前用户是否有权调用tool_name。可以设计一个权限映射表。沙箱环境对于执行代码如Python代码解释器、访问文件系统或执行系统命令的高危技能必须考虑在沙箱环境中运行例如使用Docker容器进行隔离严格限制其资源CPU、内存、网络和文件系统访问权限。审计日志记录所有技能调用的详细信息时间戳、用户ID、技能名、输入参数、执行结果可脱敏、IP地址等。这对于安全审计和问题追溯至关重要。通过SirPangolin/sirpangolin-claude-skills这样一个项目我们看到的不仅仅是一套代码更是一种构建下一代AI应用的范式。它将大语言模型的“思考”能力与外部工具的“执行”能力优雅地结合在一起。你可以从使用现有的技能开始快速搭建一个有用的助手然后随着需求深入逐步开发更复杂、更贴合自身业务场景的技能。这个过程中你对AI Agent如何理解世界、如何与工具交互的理解也会不断加深。