尧图网站开发 
最近在AI开发圈里一个名为“Claude Skill清单”的项目火了GitHub上斩获了7万颗星。很多开发者第一反应是赶紧收藏、学习这份清单但真正深入其中你会发现这份清单本身的价值远不如它背后所揭示的AI应用开发新范式重要。盲目照搬清单里的“技能”可能让你陷入无意义的重复劳动而理解其设计思想、掌握构建自定义AI技能的核心方法才是让你在AI浪潮中保持竞争力的关键。本文将带你从零开始深入剖析Claude Skill的运作机制并手把手教你如何构建、部署和管理自己的AI技能让你不仅会用更能创造。1. 背景与核心概念什么是Claude Skill在深入技术细节之前我们首先要厘清几个核心概念避免后续讨论产生混淆。1.1 Claude、Skill与清单Claude由Anthropic公司开发的大型语言模型LLM以其强大的推理能力、安全性和长上下文窗口而闻名。它提供了API供开发者集成是构建AI应用的“大脑”。Skill在Claude的语境下一个“Skill”可以理解为一个可复用的、特定领域的AI能力模块。它不仅仅是一段提示词Prompt更可能包含系统指令System Prompt定义AI的角色、行为边界和核心能力。工具调用Function Calling定义AI可以调用的外部函数或API例如查询天气、搜索数据库、执行计算等。上下文示例Few-shot Examples提供少量高质量的输入输出示例引导AI更好地理解任务。知识库/文档检索关联特定的知识源让AI的回答基于给定文档。清单List/Manifest指的就是那个在GitHub上流行的“Claude Skill清单”项目。它本质上是一个社区维护的Skill集合目录每个条目可能包含Skill的描述、触发关键词、配置方法或直接可用的提示词模板。1.2 为什么“学清单”是误区清单项目之所以能获得7万星反映了社区对结构化、可复用AI能力的巨大需求。但直接“学习”清单有以下问题信息过时AI领域迭代极快清单中的具体提示词或API调用方式可能很快失效。脱离场景清单中的Skill是为通用场景设计的直接套用到你的具体业务中效果往往大打折扣。知其然不知其所以然你只学会了“用什么”但不知道“为什么这么设计”以及“如何改进”无法举一反三。真正该学的是构建和优化一个Skill的完整方法论。这包括如何设计有效的系统指令如何将复杂任务拆解为AI可执行的步骤如何安全地集成外部工具以及如何评估和迭代Skill的效果。2. 环境准备与版本说明我们将以Python为主要语言通过Anthropic官方API来实践Skill的构建。请确保你的环境满足以下要求。2.1 基础环境操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)。Python版本3.8 或更高版本。推荐使用3.9或3.10以获得最佳兼容性。包管理工具pip(Python自带)。2.2 关键依赖库我们将使用anthropic官方Python SDK。其他库如python-dotenv用于管理密钥pydantic用于数据验证可根据项目需要添加。创建一个新的项目目录并初始化虚拟环境是推荐的做法# 创建项目目录 mkdir claude-skill-builder cd claude-skill-builder # 创建并激活虚拟环境 (以venv为例) python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate # 安装核心依赖 pip install anthropic python-dotenv2.3 获取API密钥访问 Anthropic Console 。注册并登录账户。在控制台中找到“Get API Keys”部分创建一个新的密钥。重要切勿将API密钥直接硬编码在代码中。我们使用环境变量来管理。在项目根目录创建.env文件# .env ANTHROPIC_API_KEY你的实际API密钥并在代码中通过os.getenv或dotenv加载。3. 核心原理与架构拆解一个健壮的Claude Skill不仅仅是发送一段文本。理解其背后的交互模式至关重要。3.1 对话与消息结构Claude API的核心是围绕“消息”进行的。一次完整的交互通常包含一个系统提示和一系列用户/助理的对话消息。# 这是一个基本的消息结构示例 messages [ {role: user, content: 请问今天北京的天气怎么样} ] # 系统提示定义了AI的“人设”和基础规则 system_prompt 你是一个乐于助人且信息准确的助手。API调用会将system_prompt和messages一起发送给Claude模型。3.2 工具调用Function Calling机制这是实现Skill“能动性”的关键。它允许Claude根据对话内容主动请求调用外部函数。定义工具你向Claude描述一个或多个可用的函数包括函数名、描述和参数格式通常遵循JSON Schema。模型决策Claude在理解用户请求后如果判断需要调用工具会在回复中返回一个特殊的tool_use块。执行工具你的代码解析这个块执行对应的本地函数或调用外部API。返回结果将工具执行的结果以tool_result块的形式再次放入对话历史中供Claude生成最终回答。3.3 系统提示词System Prompt设计艺术系统提示词是Skill的“灵魂”。一个好的系统提示词应该角色明确“你是一位资深Python代码审查专家。”任务清晰“你的任务是分析用户提供的Python代码片段指出潜在的错误、性能问题和不符合PEP 8规范的地方。”格式要求“请以Markdown列表的形式输出分为‘错误’、‘警告’、‘建议’三个部分。”边界限定“仅讨论代码本身不回答与代码审查无关的问题。”4. 完整实战构建一个“智能代码审查”Skill让我们通过一个完整的例子将上述理论付诸实践。我们将构建一个可以分析Python代码并提供改进建议的Skill。4.1 项目结构初始化创建如下项目结构claude-skill-builder/ ├── .env # 存储API密钥 ├── requirements.txt # 依赖列表 ├── skill_code_review.py # 主程序文件 └── test_code.py # 用于测试的代码文件requirements.txt内容anthropic0.25.0 python-dotenv1.0.04.2 编写核心技能逻辑创建skill_code_review.py文件# skill_code_review.py import os import anthropic from dotenv import load_dotenv import json # 1. 加载环境变量 load_dotenv() # 2. 初始化Claude客户端 client anthropic.Anthropic( api_keyos.getenv(ANTHROPIC_API_KEY) ) # 3. 定义系统提示词 - 这是Skill的核心 SYSTEM_PROMPT 你是一个严格且专业的Python代码审查助手。你的审查标准基于 1. **正确性**潜在的运行时错误、逻辑错误。 2. **性能**时间复杂度、空间复杂度优化建议。 3. **可读性**是否符合PEP 8规范命名是否清晰。 4. **安全性**是否存在注入风险、不安全的函数调用。 5. **Python特性**是否可以使用更地道的Python语法如列表推导式、f-string。 请按以下格式输出审查结果 ## 代码审查报告 ### 错误与缺陷 - [列出关键错误] ### ⚠️ 警告与改进 - [列出可改进点] ### 优化建议 - [列出优化建议] ### 重构示例 (可选) 如果问题典型提供一个简短的重构代码片段。 **注意**只分析与代码相关的问题不回应无关请求。 # 4. 定义工具本例暂不涉及复杂工具主要展示提示词工程 # 假设我们有一个获取PEP 8最新规则摘要的工具此处模拟 def get_pep8_summary(): 返回PEP 8关键规则的简要摘要。 return { indentation: 使用4个空格缩进。, line_length: 每行不超过79个字符。, naming: 函数名用小写加下划线类名用驼峰。 } # 5. 主函数执行代码审查 def code_review_skill(user_code: str) - str: 对提供的Python代码进行审查。 Args: user_code: 待审查的Python代码字符串。 Returns: Claude生成的审查报告字符串。 # 构建用户消息 user_message f 请审查以下Python代码 python {user_code} 请提供详细的审查报告。 try: # 调用Claude API message client.messages.create( modelclaude-3-5-sonnet-20241022, # 使用合适的模型版本 max_tokens2000, temperature0.2, # 较低的温度使输出更专注、稳定 systemSYSTEM_PROMPT, messages[ {role: user, content: user_message} ] ) # 返回助理的回复内容 # message.content 是一个列表我们取第一个文本块 review_report message.content[0].text return review_report except anthropic.APIConnectionError as e: return f连接API失败: {e} except anthropic.APIStatusError as e: return fAPI返回错误状态码: {e.status_code}, {e.response} except Exception as e: return f发生未知错误: {e} # 6. 测试与运行 if __name__ __main__: # 示例读取一个测试代码文件 test_code_file test_code.py if os.path.exists(test_code_file): with open(test_code_file, r, encodingutf-8) as f: code_to_review f.read() else: # 如果文件不存在使用一个内联的示例代码 code_to_review def calculate_average(numbers): sum 0 for i in range(len(numbers)): sum numbers[i] avg sum / len(numbers) return avg def process_data(data): result [] for item in data: if item 10: result.append(item*2) else: result.append(item) return result print(calculate_average([1,2,3,4,5])) print(正在审查代码...\n) report code_review_skill(code_to_review) print(*50) print(代码审查报告) print(*50) print(report)4.3 创建测试代码创建test_code.py文件放入一些有“味道”的代码供审查# test_code.py # 这是一个包含一些常见问题的示例代码 data_list [1, 2, 3, 4, 5, 20, 15, 30] def calc(lst): s0 for i in range(len(lst)): sslst[i] as/len(lst) return a def filter_and_double(data, threshold10): output[] for d in data: if d threshold: output.append(d*2) return output result filter_and_double(data_list) print(fResult: {result}) print(fAverage: {calc(data_list)}) # 潜在问题使用input而不验证可能存在安全风险 user_input input(Enter a number: ) try: num int(user_input) print(fYou entered: {num}) except: pass # 空的except是坏习惯4.4 运行与验证在终端中确保虚拟环境已激活并运行python skill_code_review.py你将看到Claude对test_code.py代码的详细审查报告其输出会类似于以下结构 代码审查报告 ## 代码审查报告 ### 错误与缺陷 - 第18行except: 使用了空的except语句会捕获所有异常包括KeyboardInterrupt和SystemExit这是危险的做法。应至少指定异常类型如except ValueError:。 ### ⚠️ 警告与改进 - 函数和变量命名不清晰calc应改为calculate_averages、a、lst等单字母变量名应使用描述性名称。 - 不符合PEP 8函数定义后应有两个空行第4行后。运算符周围应有空格如sslst[i]应为s s lst[i]。 - calc函数中的循环可以更Pythonic直接使用for num in lst:进行迭代而不是索引。 ### 优化建议 - filter_and_double函数可以使用列表推导式简化[d * 2 for d in data if d threshold]。 - 计算平均值可以使用内置函数sum()sum(lst) / len(lst)。 ### 重构示例 原calc函数可重构为 def calculate_average(numbers): if not numbers: return 0 # 避免除零错误 return sum(numbers) / len(numbers)5. 进阶集成工具调用实现“联网搜索”Skill单纯的文本生成有限让Claude能调用外部工具才是强大之处。我们构建一个能查询最新信息的Skill。5.1 设计工具函数我们模拟一个搜索工具实际项目中会替换为真实的搜索引擎API如Serper、Google Custom Search等。# skill_web_searcher.py import os import anthropic from dotenv import load_dotenv import json load_dotenv() client anthropic.Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) # 模拟的搜索函数 - 实际应调用真实API def search_web(query: str): 模拟网络搜索返回结构化结果。 # 这里是模拟数据。真实情况需调用如Serper API: # response requests.post(https://google.serper.dev/search, ...) print(f[模拟] 正在搜索: {query}) mock_results [ { title: f关于{query}的最新研究进展, snippet: f近期在{query}领域取得了突破性进展主要涉及..., url: https://example.com/research }, { title: f{query}的技术实践指南, snippet: 本文详细介绍了如何在实际项目中应用相关技术..., url: https://example.com/guide } ] return { query: query, results: mock_results } # 定义可供Claude调用的工具列表 TOOLS [ { name: search_web, description: 在互联网上搜索最新信息。当用户询问需要最新、实时数据的问题时使用此工具。, input_schema: { type: object, properties: { query: { type: string, description: 搜索关键词应具体、明确。 } }, required: [query] } } ] SYSTEM_PROMPT 你是一个拥有联网搜索能力的助手。当用户的问题涉及实时信息、最新事件、不确定的事实或需要验证的数据时你必须使用search_web工具进行查询并基于查询结果回答。 如果用户的问题是基于已知常识或无需最新信息你可以直接回答。 你的回答应引用来源并注明信息来自网络搜索。 def run_conversation_with_tools(user_query: str): messages [{role: user, content: user_query}] while True: # 调用Claude传入工具定义 response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, systemSYSTEM_PROMPT, messagesmessages, toolsTOOLS ) # 处理响应 message response.content[0] # 1. 如果Claude返回文本直接输出并结束 if message.type text: print(fAssistant: {message.text}) break # 2. 如果Claude决定使用工具 elif message.type tool_use: tool_name message.name tool_input message.input print(fAssistant 决定使用工具: {tool_name}, 输入: {tool_input}) # 根据工具名调用对应的本地函数 if tool_name search_web: tool_result search_web(tool_input[query]) else: tool_result {error: f未知工具: {tool_name}} # 将工具执行结果以特定格式追加到消息历史中 messages.append({ role: assistant, content: [message] # 包含Claude的tool_use请求 }) messages.append({ role: user, content: [ { type: tool_result, tool_use_id: message.id, content: json.dumps(tool_result, ensure_asciiFalse) } ] }) # 循环继续Claude将基于工具结果生成最终回复 if __name__ __main__: # 测试不同类型的问题 queries [ 2024年巴黎奥运会中国队的金牌情况如何, # 需要实时信息 Python中列表和元组有什么区别, # 常识问题可能无需搜索 帮我找一下最近关于大语言模型推理速度优化的论文。 ] for q in queries: print(f\n用户: {q}) run_conversation_with_tools(q) print(-*40)运行此脚本你会看到Claude对于需要实时信息的问题会先调用search_web工具模拟然后将搜索结果整合到最终回答中。6. 常见问题与排查思路在开发和集成Claude Skill时你可能会遇到以下问题。问题现象可能原因排查与解决思路APIConnectionError或超时1. 网络连接问题。2. API密钥无效或未设置。3. Anthropic服务暂时不可用。1. 检查网络尝试ping api.anthropic.com。2. 确认.env文件中的ANTHROPIC_API_KEY正确且在代码中成功加载 (print(os.getenv(...)))。3. 查看 Anthropic Status 页面。APIStatusError: 401API密钥错误、过期或无权访问目标模型。1. 在Anthropic控制台确认密钥有效且未过期。2. 确认你的账户有对应模型的访问权限如Claude 3.5 Sonnet。APIStatusError: 429请求速率超限Rate Limit。1. 检查免费 tier 或付费套餐的速率限制。2. 在代码中增加请求间隔如time.sleep(1)。3. 考虑实现重试机制使用指数退避。APIStatusError: 400请求参数错误。1. 检查model名称是否拼写正确如claude-3-5-sonnet-20241022。2. 检查messages格式是否符合API要求角色必须是user/assistant。3. 检查tools参数的定义是否符合JSON Schema规范。Claude不调用工具1. 工具描述不清晰。2. 系统提示词未强制要求。3. 用户问题未触发工具使用条件。1. 优化工具description明确使用场景。2. 在system提示词中强调“当遇到XX问题时你必须使用YY工具”。3. 在messages中提供少量工具调用的示例few-shot。生成的回复格式不符合要求系统提示词中的格式指令不够明确或未被遵循。1. 在system提示词中使用更强烈的指令如“你必须严格按照以下格式输出...”。2. 在user消息中再次明确格式要求。3. 考虑使用输出解析库如Pydantic进行后处理。处理长上下文时性能下降或丢失信息1. 输入token数超过模型上限。2. 关键信息被淹没在长文本中。1. 对长文档进行分块chunk采用“检索增强生成RAG”模式只传入相关片段。2. 在system提示词中要求Claude“重点关注用户最后提供的文档”。7. 最佳实践与工程建议掌握了基础构建方法后以下实践能帮助你将Skill应用到真实、可持续的项目中。7.1 提示词工程优化结构化与分层将复杂的系统提示词分成几个部分如“角色定义”、“核心任务”、“输出格式”、“禁忌”使其更易维护。使用XML标签在提示词中使用如rule.../rule、format.../format等标签有助于模型更好地识别指令边界。提供示例Few-shot在messages中提供1-3个高质量的输入输出示例比单纯描述规则更有效。迭代与评估建立评估体系。对于代码审查Skill可以准备一批有已知问题的代码测试Skill的检出率、准确率和建议质量。7.2 代码工程化配置化管理将SYSTEM_PROMPT、TOOLS定义、模型参数等移出主代码放入配置文件如config.yaml或config.json中。错误处理与重试对所有API调用进行完善的错误处理如网络超时、速率限制并实现带退避的重试逻辑。日志记录记录每一次交互的请求和响应注意脱敏API密钥和隐私数据便于调试和效果分析。异步处理如果Skill需要处理大量并发请求使用asyncio和异步HTTP客户端如httpx可以大幅提升性能。7.3 安全与成本控制密钥安全永远不要将API密钥提交到代码仓库。使用.env文件并通过.gitignore忽略它。在生产环境使用密钥管理服务如AWS Secrets Manager。输入验证与清理对用户输入进行严格的验证和清理防止提示词注入攻击。避免将未经处理的用户输入直接拼接到系统提示词中。设置Token上限合理设置max_tokens参数避免生成过长内容导致不必要的费用。对于总结类任务可以设置较小的值。监控用量与成本定期查看Anthropic控制台的用量统计设置预算告警。对于工具调用也要监控外部API的调用成本。7.4 Skill的部署与集成封装为API服务使用FastAPI或Flask将你的Skill封装成RESTful API方便与其他系统集成。# 使用FastAPI的简单示例 from fastapi import FastAPI, HTTPException app FastAPI() app.post(/review-code) async def review_code(request: CodeReviewRequest): # request.code 包含用户代码 report code_review_skill(request.code) return {report: report}构建Skill仓库像那个“7万星清单”一样你可以为自己团队构建一个内部的Skill仓库每个Skill包含描述、版本、输入输出规范、测试用例和部署配置。持续集成/持续部署为Skill仓库配置CI/CD流水线自动化测试和部署过程。回到最初的问题那份7万星的清单只是一个目录和灵感的起点。真正的价值在于掌握从需求分析、提示词设计、工具集成、到测试部署的完整闭环能力。下一个爆火的AI应用或许就始于你今天为自己业务精心构建的那个定制化Skill。 
最近在AI开发圈里一个名为“Claude Skill清单”的项目火了GitHub上斩获了7万颗星。很多开发者第一反应是赶紧收藏、学习这份清单但真正深入其中你会发现这份清单本身的价值远不如它背后所揭示的AI应用开发新范式重要。盲目照搬清单里的“技能”可能让你陷入无意义的重复劳动而理解其设计思想、掌握构建自定义AI技能的核心方法才是让你在AI浪潮中保持竞争力的关键。本文将带你从零开始深入剖析Claude Skill的运作机制并手把手教你如何构建、部署和管理自己的AI技能让你不仅会用更能创造。1. 背景与核心概念什么是Claude Skill在深入技术细节之前我们首先要厘清几个核心概念避免后续讨论产生混淆。1.1 Claude、Skill与清单Claude由Anthropic公司开发的大型语言模型LLM以其强大的推理能力、安全性和长上下文窗口而闻名。它提供了API供开发者集成是构建AI应用的“大脑”。Skill在Claude的语境下一个“Skill”可以理解为一个可复用的、特定领域的AI能力模块。它不仅仅是一段提示词Prompt更可能包含系统指令System Prompt定义AI的角色、行为边界和核心能力。工具调用Function Calling定义AI可以调用的外部函数或API例如查询天气、搜索数据库、执行计算等。上下文示例Few-shot Examples提供少量高质量的输入输出示例引导AI更好地理解任务。知识库/文档检索关联特定的知识源让AI的回答基于给定文档。清单List/Manifest指的就是那个在GitHub上流行的“Claude Skill清单”项目。它本质上是一个社区维护的Skill集合目录每个条目可能包含Skill的描述、触发关键词、配置方法或直接可用的提示词模板。1.2 为什么“学清单”是误区清单项目之所以能获得7万星反映了社区对结构化、可复用AI能力的巨大需求。但直接“学习”清单有以下问题信息过时AI领域迭代极快清单中的具体提示词或API调用方式可能很快失效。脱离场景清单中的Skill是为通用场景设计的直接套用到你的具体业务中效果往往大打折扣。知其然不知其所以然你只学会了“用什么”但不知道“为什么这么设计”以及“如何改进”无法举一反三。真正该学的是构建和优化一个Skill的完整方法论。这包括如何设计有效的系统指令如何将复杂任务拆解为AI可执行的步骤如何安全地集成外部工具以及如何评估和迭代Skill的效果。2. 环境准备与版本说明我们将以Python为主要语言通过Anthropic官方API来实践Skill的构建。请确保你的环境满足以下要求。2.1 基础环境操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)。Python版本3.8 或更高版本。推荐使用3.9或3.10以获得最佳兼容性。包管理工具pip(Python自带)。2.2 关键依赖库我们将使用anthropic官方Python SDK。其他库如python-dotenv用于管理密钥pydantic用于数据验证可根据项目需要添加。创建一个新的项目目录并初始化虚拟环境是推荐的做法# 创建项目目录 mkdir claude-skill-builder cd claude-skill-builder # 创建并激活虚拟环境 (以venv为例) python -m venv venv # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate # 安装核心依赖 pip install anthropic python-dotenv2.3 获取API密钥访问 Anthropic Console 。注册并登录账户。在控制台中找到“Get API Keys”部分创建一个新的密钥。重要切勿将API密钥直接硬编码在代码中。我们使用环境变量来管理。在项目根目录创建.env文件# .env ANTHROPIC_API_KEY你的实际API密钥并在代码中通过os.getenv或dotenv加载。3. 核心原理与架构拆解一个健壮的Claude Skill不仅仅是发送一段文本。理解其背后的交互模式至关重要。3.1 对话与消息结构Claude API的核心是围绕“消息”进行的。一次完整的交互通常包含一个系统提示和一系列用户/助理的对话消息。# 这是一个基本的消息结构示例 messages [ {role: user, content: 请问今天北京的天气怎么样} ] # 系统提示定义了AI的“人设”和基础规则 system_prompt 你是一个乐于助人且信息准确的助手。API调用会将system_prompt和messages一起发送给Claude模型。3.2 工具调用Function Calling机制这是实现Skill“能动性”的关键。它允许Claude根据对话内容主动请求调用外部函数。定义工具你向Claude描述一个或多个可用的函数包括函数名、描述和参数格式通常遵循JSON Schema。模型决策Claude在理解用户请求后如果判断需要调用工具会在回复中返回一个特殊的tool_use块。执行工具你的代码解析这个块执行对应的本地函数或调用外部API。返回结果将工具执行的结果以tool_result块的形式再次放入对话历史中供Claude生成最终回答。3.3 系统提示词System Prompt设计艺术系统提示词是Skill的“灵魂”。一个好的系统提示词应该角色明确“你是一位资深Python代码审查专家。”任务清晰“你的任务是分析用户提供的Python代码片段指出潜在的错误、性能问题和不符合PEP 8规范的地方。”格式要求“请以Markdown列表的形式输出分为‘错误’、‘警告’、‘建议’三个部分。”边界限定“仅讨论代码本身不回答与代码审查无关的问题。”4. 完整实战构建一个“智能代码审查”Skill让我们通过一个完整的例子将上述理论付诸实践。我们将构建一个可以分析Python代码并提供改进建议的Skill。4.1 项目结构初始化创建如下项目结构claude-skill-builder/ ├── .env # 存储API密钥 ├── requirements.txt # 依赖列表 ├── skill_code_review.py # 主程序文件 └── test_code.py # 用于测试的代码文件requirements.txt内容anthropic0.25.0 python-dotenv1.0.04.2 编写核心技能逻辑创建skill_code_review.py文件# skill_code_review.py import os import anthropic from dotenv import load_dotenv import json # 1. 加载环境变量 load_dotenv() # 2. 初始化Claude客户端 client anthropic.Anthropic( api_keyos.getenv(ANTHROPIC_API_KEY) ) # 3. 定义系统提示词 - 这是Skill的核心 SYSTEM_PROMPT 你是一个严格且专业的Python代码审查助手。你的审查标准基于 1. **正确性**潜在的运行时错误、逻辑错误。 2. **性能**时间复杂度、空间复杂度优化建议。 3. **可读性**是否符合PEP 8规范命名是否清晰。 4. **安全性**是否存在注入风险、不安全的函数调用。 5. **Python特性**是否可以使用更地道的Python语法如列表推导式、f-string。 请按以下格式输出审查结果 ## 代码审查报告 ### 错误与缺陷 - [列出关键错误] ### ⚠️ 警告与改进 - [列出可改进点] ### 优化建议 - [列出优化建议] ### 重构示例 (可选) 如果问题典型提供一个简短的重构代码片段。 **注意**只分析与代码相关的问题不回应无关请求。 # 4. 定义工具本例暂不涉及复杂工具主要展示提示词工程 # 假设我们有一个获取PEP 8最新规则摘要的工具此处模拟 def get_pep8_summary(): 返回PEP 8关键规则的简要摘要。 return { indentation: 使用4个空格缩进。, line_length: 每行不超过79个字符。, naming: 函数名用小写加下划线类名用驼峰。 } # 5. 主函数执行代码审查 def code_review_skill(user_code: str) - str: 对提供的Python代码进行审查。 Args: user_code: 待审查的Python代码字符串。 Returns: Claude生成的审查报告字符串。 # 构建用户消息 user_message f 请审查以下Python代码 python {user_code} 请提供详细的审查报告。 try: # 调用Claude API message client.messages.create( modelclaude-3-5-sonnet-20241022, # 使用合适的模型版本 max_tokens2000, temperature0.2, # 较低的温度使输出更专注、稳定 systemSYSTEM_PROMPT, messages[ {role: user, content: user_message} ] ) # 返回助理的回复内容 # message.content 是一个列表我们取第一个文本块 review_report message.content[0].text return review_report except anthropic.APIConnectionError as e: return f连接API失败: {e} except anthropic.APIStatusError as e: return fAPI返回错误状态码: {e.status_code}, {e.response} except Exception as e: return f发生未知错误: {e} # 6. 测试与运行 if __name__ __main__: # 示例读取一个测试代码文件 test_code_file test_code.py if os.path.exists(test_code_file): with open(test_code_file, r, encodingutf-8) as f: code_to_review f.read() else: # 如果文件不存在使用一个内联的示例代码 code_to_review def calculate_average(numbers): sum 0 for i in range(len(numbers)): sum numbers[i] avg sum / len(numbers) return avg def process_data(data): result [] for item in data: if item 10: result.append(item*2) else: result.append(item) return result print(calculate_average([1,2,3,4,5])) print(正在审查代码...\n) report code_review_skill(code_to_review) print(*50) print(代码审查报告) print(*50) print(report)4.3 创建测试代码创建test_code.py文件放入一些有“味道”的代码供审查# test_code.py # 这是一个包含一些常见问题的示例代码 data_list [1, 2, 3, 4, 5, 20, 15, 30] def calc(lst): s0 for i in range(len(lst)): sslst[i] as/len(lst) return a def filter_and_double(data, threshold10): output[] for d in data: if d threshold: output.append(d*2) return output result filter_and_double(data_list) print(fResult: {result}) print(fAverage: {calc(data_list)}) # 潜在问题使用input而不验证可能存在安全风险 user_input input(Enter a number: ) try: num int(user_input) print(fYou entered: {num}) except: pass # 空的except是坏习惯4.4 运行与验证在终端中确保虚拟环境已激活并运行python skill_code_review.py你将看到Claude对test_code.py代码的详细审查报告其输出会类似于以下结构 代码审查报告 ## 代码审查报告 ### 错误与缺陷 - 第18行except: 使用了空的except语句会捕获所有异常包括KeyboardInterrupt和SystemExit这是危险的做法。应至少指定异常类型如except ValueError:。 ### ⚠️ 警告与改进 - 函数和变量命名不清晰calc应改为calculate_averages、a、lst等单字母变量名应使用描述性名称。 - 不符合PEP 8函数定义后应有两个空行第4行后。运算符周围应有空格如sslst[i]应为s s lst[i]。 - calc函数中的循环可以更Pythonic直接使用for num in lst:进行迭代而不是索引。 ### 优化建议 - filter_and_double函数可以使用列表推导式简化[d * 2 for d in data if d threshold]。 - 计算平均值可以使用内置函数sum()sum(lst) / len(lst)。 ### 重构示例 原calc函数可重构为 def calculate_average(numbers): if not numbers: return 0 # 避免除零错误 return sum(numbers) / len(numbers)5. 进阶集成工具调用实现“联网搜索”Skill单纯的文本生成有限让Claude能调用外部工具才是强大之处。我们构建一个能查询最新信息的Skill。5.1 设计工具函数我们模拟一个搜索工具实际项目中会替换为真实的搜索引擎API如Serper、Google Custom Search等。# skill_web_searcher.py import os import anthropic from dotenv import load_dotenv import json load_dotenv() client anthropic.Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) # 模拟的搜索函数 - 实际应调用真实API def search_web(query: str): 模拟网络搜索返回结构化结果。 # 这里是模拟数据。真实情况需调用如Serper API: # response requests.post(https://google.serper.dev/search, ...) print(f[模拟] 正在搜索: {query}) mock_results [ { title: f关于{query}的最新研究进展, snippet: f近期在{query}领域取得了突破性进展主要涉及..., url: https://example.com/research }, { title: f{query}的技术实践指南, snippet: 本文详细介绍了如何在实际项目中应用相关技术..., url: https://example.com/guide } ] return { query: query, results: mock_results } # 定义可供Claude调用的工具列表 TOOLS [ { name: search_web, description: 在互联网上搜索最新信息。当用户询问需要最新、实时数据的问题时使用此工具。, input_schema: { type: object, properties: { query: { type: string, description: 搜索关键词应具体、明确。 } }, required: [query] } } ] SYSTEM_PROMPT 你是一个拥有联网搜索能力的助手。当用户的问题涉及实时信息、最新事件、不确定的事实或需要验证的数据时你必须使用search_web工具进行查询并基于查询结果回答。 如果用户的问题是基于已知常识或无需最新信息你可以直接回答。 你的回答应引用来源并注明信息来自网络搜索。 def run_conversation_with_tools(user_query: str): messages [{role: user, content: user_query}] while True: # 调用Claude传入工具定义 response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, systemSYSTEM_PROMPT, messagesmessages, toolsTOOLS ) # 处理响应 message response.content[0] # 1. 如果Claude返回文本直接输出并结束 if message.type text: print(fAssistant: {message.text}) break # 2. 如果Claude决定使用工具 elif message.type tool_use: tool_name message.name tool_input message.input print(fAssistant 决定使用工具: {tool_name}, 输入: {tool_input}) # 根据工具名调用对应的本地函数 if tool_name search_web: tool_result search_web(tool_input[query]) else: tool_result {error: f未知工具: {tool_name}} # 将工具执行结果以特定格式追加到消息历史中 messages.append({ role: assistant, content: [message] # 包含Claude的tool_use请求 }) messages.append({ role: user, content: [ { type: tool_result, tool_use_id: message.id, content: json.dumps(tool_result, ensure_asciiFalse) } ] }) # 循环继续Claude将基于工具结果生成最终回复 if __name__ __main__: # 测试不同类型的问题 queries [ 2024年巴黎奥运会中国队的金牌情况如何, # 需要实时信息 Python中列表和元组有什么区别, # 常识问题可能无需搜索 帮我找一下最近关于大语言模型推理速度优化的论文。 ] for q in queries: print(f\n用户: {q}) run_conversation_with_tools(q) print(-*40)运行此脚本你会看到Claude对于需要实时信息的问题会先调用search_web工具模拟然后将搜索结果整合到最终回答中。6. 常见问题与排查思路在开发和集成Claude Skill时你可能会遇到以下问题。问题现象可能原因排查与解决思路APIConnectionError或超时1. 网络连接问题。2. API密钥无效或未设置。3. Anthropic服务暂时不可用。1. 检查网络尝试ping api.anthropic.com。2. 确认.env文件中的ANTHROPIC_API_KEY正确且在代码中成功加载 (print(os.getenv(...)))。3. 查看 Anthropic Status 页面。APIStatusError: 401API密钥错误、过期或无权访问目标模型。1. 在Anthropic控制台确认密钥有效且未过期。2. 确认你的账户有对应模型的访问权限如Claude 3.5 Sonnet。APIStatusError: 429请求速率超限Rate Limit。1. 检查免费 tier 或付费套餐的速率限制。2. 在代码中增加请求间隔如time.sleep(1)。3. 考虑实现重试机制使用指数退避。APIStatusError: 400请求参数错误。1. 检查model名称是否拼写正确如claude-3-5-sonnet-20241022。2. 检查messages格式是否符合API要求角色必须是user/assistant。3. 检查tools参数的定义是否符合JSON Schema规范。Claude不调用工具1. 工具描述不清晰。2. 系统提示词未强制要求。3. 用户问题未触发工具使用条件。1. 优化工具description明确使用场景。2. 在system提示词中强调“当遇到XX问题时你必须使用YY工具”。3. 在messages中提供少量工具调用的示例few-shot。生成的回复格式不符合要求系统提示词中的格式指令不够明确或未被遵循。1. 在system提示词中使用更强烈的指令如“你必须严格按照以下格式输出...”。2. 在user消息中再次明确格式要求。3. 考虑使用输出解析库如Pydantic进行后处理。处理长上下文时性能下降或丢失信息1. 输入token数超过模型上限。2. 关键信息被淹没在长文本中。1. 对长文档进行分块chunk采用“检索增强生成RAG”模式只传入相关片段。2. 在system提示词中要求Claude“重点关注用户最后提供的文档”。7. 最佳实践与工程建议掌握了基础构建方法后以下实践能帮助你将Skill应用到真实、可持续的项目中。7.1 提示词工程优化结构化与分层将复杂的系统提示词分成几个部分如“角色定义”、“核心任务”、“输出格式”、“禁忌”使其更易维护。使用XML标签在提示词中使用如rule.../rule、format.../format等标签有助于模型更好地识别指令边界。提供示例Few-shot在messages中提供1-3个高质量的输入输出示例比单纯描述规则更有效。迭代与评估建立评估体系。对于代码审查Skill可以准备一批有已知问题的代码测试Skill的检出率、准确率和建议质量。7.2 代码工程化配置化管理将SYSTEM_PROMPT、TOOLS定义、模型参数等移出主代码放入配置文件如config.yaml或config.json中。错误处理与重试对所有API调用进行完善的错误处理如网络超时、速率限制并实现带退避的重试逻辑。日志记录记录每一次交互的请求和响应注意脱敏API密钥和隐私数据便于调试和效果分析。异步处理如果Skill需要处理大量并发请求使用asyncio和异步HTTP客户端如httpx可以大幅提升性能。7.3 安全与成本控制密钥安全永远不要将API密钥提交到代码仓库。使用.env文件并通过.gitignore忽略它。在生产环境使用密钥管理服务如AWS Secrets Manager。输入验证与清理对用户输入进行严格的验证和清理防止提示词注入攻击。避免将未经处理的用户输入直接拼接到系统提示词中。设置Token上限合理设置max_tokens参数避免生成过长内容导致不必要的费用。对于总结类任务可以设置较小的值。监控用量与成本定期查看Anthropic控制台的用量统计设置预算告警。对于工具调用也要监控外部API的调用成本。7.4 Skill的部署与集成封装为API服务使用FastAPI或Flask将你的Skill封装成RESTful API方便与其他系统集成。# 使用FastAPI的简单示例 from fastapi import FastAPI, HTTPException app FastAPI() app.post(/review-code) async def review_code(request: CodeReviewRequest): # request.code 包含用户代码 report code_review_skill(request.code) return {report: report}构建Skill仓库像那个“7万星清单”一样你可以为自己团队构建一个内部的Skill仓库每个Skill包含描述、版本、输入输出规范、测试用例和部署配置。持续集成/持续部署为Skill仓库配置CI/CD流水线自动化测试和部署过程。回到最初的问题那份7万星的清单只是一个目录和灵感的起点。真正的价值在于掌握从需求分析、提示词设计、工具集成、到测试部署的完整闭环能力。下一个爆火的AI应用或许就始于你今天为自己业务精心构建的那个定制化Skill。