1. 引言当大模型遇到“知识盲区”最近在折腾一个内部项目需要让Claude帮我处理一些基于特定框架的代码。这个框架比较新或者说比较小众Claude的知识库里显然没有它的详细资料。一开始我尝试了最直接的方法把框架的官方文档扔给它然后提问。结果呢Claude的回答要么是基于通用编程模式的猜测要么就是直接承认“我不熟悉这个框架但根据您提供的文档我推测...”。这种“推测”出来的代码往往似是而非跑起来不是报错就是逻辑不对。这让我开始思考一个更本质的问题我们总说大模型能力强但它的能力边界到底在哪里当它遇到一个完全陌生的领域时我们除了费时费力地去微调模型这成本太高也不现实有没有更轻量、更敏捷的方法能像教一个聪明的新手一样快速让它“学会”并应用新知识答案就是构建一个高质量的Skill。这里的“Skill”不是指模型参数的调整而是一套精心设计的提示词Prompt工程组合。它本质上是一个“外部知识插件”或“操作指南”告诉模型在面对特定领域问题时应该如何思考、如何调用知识、如何输出符合要求的答案。今天我就结合让Claude学会一个全新框架的实战过程拆解如何从零构建一个有效的Skill让你手里的AI助手真正成为某个垂直领域的“专家”。2. 理解“Skill”的本质超越简单提示词的系统工程很多人对提示词工程的理解还停留在“问得详细一点”或者“给几个例子”Few-Shot Learning的层面。这当然有用但面对一个复杂的、体系化的新知识比如一个完整的开发框架零散的提示和例子就像只给了学生几张单词卡却指望他能写出一篇专业论文。构建一个Skill是一个系统工程其核心目标是在模型的上下文窗口内为它搭建一个临时的、结构化的“思维框架”和“知识库”。2.1 Skill与普通提示词的关键区别普通提示词通常是任务导向的“请帮我写一个函数实现XX功能。” 而Skill是认知框架导向的。它不仅要告诉模型“做什么”更要重塑模型“如何思考”这件事。以一个Web框架为例普通提示词可能是“用Flask写一个用户登录接口。” 模型凭借对Flask的内置知识可以完成。但如果换成一个它不知道的框架“NovelWeb”普通提示词就失效了。而一个为“NovelWeb框架”设计的Skill则会包含以下层次框架世界观这是一个用于构建API的轻量级Node.js框架核心哲学是“约定优于配置”。核心概念映射将模型已知的概念如Router Middleware Controller与NovelWeb中的特定术语如RouteTablePipelineHandler建立准确关联并解释细微差异。标准操作流程SOP创建一个RESTful端点通常遵循“定义路由 - 编写处理器 - 注册中间件 - 导出模块”的固定流程。代码风格与惯例包括文件命名、目录结构、特定的导入方式等。常见陷阱与验证方法指出新手最容易出错的地方以及如何快速验证一段代码是否符合框架规范。当模型被“装备”上这个Skill后它再处理相关请求时就不再是盲目联想而是在一个它刚建立的、清晰的边界和规则内进行推理和生成。2.2 构建Skill的三大核心支柱一个健壮的Skill通常建立在三大支柱上缺一不可结构化知识注入这是Skill的“肉体”。你需要将零散的文档信息重新组织成模型易于消化和理解的结构。例如不要直接粘贴完整的API文档而是提炼出核心对象列表及其属性/方法用表格呈现最清晰。生命周期或数据流图用文字描述如“一个请求进入NovelWeb后首先经过全局前置中间件然后匹配路由再执行路由级中间件最后交给处理器Handler响应则按相反顺序返回。”。关键配置项及其默认值。思维链Chain-of-Thought设计这是Skill的“灵魂”。你需要在Skill中明确要求模型按照特定的步骤进行思考。这对于复杂任务尤其关键。例如在Skill中可以这样设计“当你需要为NovelWeb框架编写代码时请按照以下顺序思考确定上下文用户请求的功能属于哪个模块路由、数据库、认证等匹配模式回忆Skill中提供的模式这个功能对应哪种标准实现模式例如‘创建资源’模式通常包含验证、创建、返回填充细节根据用户的具体要求将模式中的占位符替换为具体的对象名、字段和逻辑。遵守惯例检查生成的代码是否符合Skill中提到的命名约定和文件结构。输出与解释输出最终代码并简要说明关键步骤与Skill中哪部分知识对应。”约束与边界划定这是Skill的“安全护栏”。明确告诉模型什么不能做比告诉它能做什么有时更重要。这能有效防止模型“幻觉”出一些框架不支持的特性。例如“请注意NovelWeb框架的中间件不支持异步函数所有中间件必须是同步的。” “NovelWeb的配置必须通过config.yaml文件加载不支持在代码中硬编码。” “如果用户请求的功能涉及WebSocket请直接说明NovelWeb框架原生不支持此功能并建议替代方案。”3. 实战为“Starlight”框架构建一个开发Skill假设我们有一个虚构的、Claude肯定没学过的Python Web框架叫“Starlight”。下面我将一步步展示如何为它构建一个Skill。3.1 第一步原始资料分析与信息萃取首先我拿到了Starlight的简明文档模拟。原始信息可能是杂乱无章的“用app.route装饰器定义路由。”“请求对象是starlight.Request可以用.json()方法获取JSON数据。”“用starlight.Response返回设置status_code和json数据。”“数据库操作推荐用async with app.db.acquire() as conn:。”“项目结构建议app/main.py,app/routers/,app/models/。”作为Skill构建者我的任务不是照搬而是翻译和重构。我要从中提取出模型需要的结构化知识。我提炼出的核心结构化知识1. 核心对象与概念表概念Starlight中的体现关键属性/方法说明应用实例app starlight.App()app.route,app.db全局唯一是入口路由定义app.route(‘/path‘, methods[‘GET‘])装饰器形式类似Flask请求对象request: starlight.Requestrequest.json(),request.query自动注入到处理函数响应对象starlight.ResponseResponse(data, status_code200)必须显式返回此对象数据库连接app.db(异步)app.db.acquire(),execute()需异步上下文管理2. 标准请求处理流程文字描述“一个HTTP请求在Starlight中的旅程首先被app对象接收根据URL匹配到由app.route装饰的函数。该函数至少接收一个request参数。在函数内部你可以从request中获取数据进行业务逻辑处理可能涉及异步数据库操作app.db最后必须返回一个starlight.Response对象。框架负责将这个响应发送给客户端。”3. 项目惯例入口文件app/main.py内部创建app实例并导入路由。路由组织建议将路由分组写在app/routers/目录下的模块中然后在main.py中通过app.include_router引入。异步支持Starlight是异步框架处理函数应定义为async def。3.2 第二步编写Skill指令核心Prompt接下来我将上述结构化知识、思维链和约束融合成一段给Claude的“系统指令”。这段指令会放在对话的最开始或者通过Claude的“自定义指令”功能注入。# Role: Starlight框架专家 你是一个精通Starlight Python Web框架的开发者。请严格按照以下关于Starlight框架的知识和规范来回答用户问题。 ## 框架核心知识 **1. 核心对象** - **应用**通过 app starlight.App() 创建。所有操作的起点。 - **路由**使用 app.route(‘/path‘, methods[‘GET‘, ‘POST‘]) 装饰器定义。被装饰的函数是**异步的**即 async def handler(request):。 - **请求**处理函数第一个参数是 request: starlight.Request。常用方法 - await request.json(): 获取JSON请求体异步。 - request.query.get(‘key‘): 获取URL查询参数。 - **响应**必须返回 starlight.Response 对象。例如return starlight.Response(data, status_code201)。 - **数据库**通过 app.db 访问是一个异步连接池。使用模式async with app.db.acquire() as conn: result await conn.execute(query)。 **2. 标准项目结构** - app/main.py: 应用入口。创建app并导入、注册所有路由。 - app/routers/: 存放路由模块例如 users.py, posts.py。 - app/models/: 存放数据模型定义。 **3. 关键约束与惯例** - **必须异步**所有路由处理函数必须是 async def。 - **必须返回Response**不能直接返回字典或字符串必须包装在 starlight.Response 中。 - **配置**数据库连接等配置在 app 初始化时传入如 app starlight.App(database_url‘...‘)。 - **不支持**Starlight **没有**内置模板引擎如需渲染HTML需自行集成或返回JSON。 ## 你的思考与工作流程 当用户提出一个与Starlight框架相关的编码任务时请遵循以下步骤 1. **解析需求**明确用户要创建什么例如一个用户注册的POST端点。 2. **匹配模式**回忆上述知识判断这属于“定义路由”、“处理请求”、“数据库操作”中的哪一种或哪几种组合。 3. **构建代码骨架**根据标准结构确定代码应该放在哪个文件如 app/routers/users.py并写出基本的导入语句和函数定义。 4. **填充逻辑细节**根据用户具体需求编写核心业务逻辑特别注意使用正确的异步语法和API如 await request.json()。 5. **遵守惯例与约束**检查代码是否满足“异步函数”、“返回Response对象”、“正确使用数据库连接”等关键约束。 6. **输出与说明**输出完整的、可运行的代码片段并简要解释关键部分是如何应用上述Starlight知识的。 现在请基于以上角色和知识开始协助用户。如果用户需求超出Starlight能力范围请明确指出。这个Skill指令就是一个完整的、可操作的“外部大脑”。它没有修改Claude一丝一毫的权重只是给了它一个极其明确、结构化的上下文。3.3 第三步测试与迭代优化构建Skill不是一蹴而就的。发出上述指令后我开始用各种问题测试Claude。测试用例1基础路由我的提问“帮我用Starlight写一个简单的GET接口访问/hello返回{“message“: “Hello, Starlight“}。”Claude的输出符合预期# 文件app/routers/greeting.py import starlight # 假设这个router会被导入到main.py # 在main.py中会有app.include_router(greeting.router) # 但根据Skill我们更常用直接装饰app的方式。这里按Skill展示直接装饰法。 # 首先需要在main.py中创建app实例。这里展示路由函数本身。 # 假设 app 实例在别处已创建我们在此模块中通过导入使用它。 # 更常见的做法是在 routers/greeting.py 中定义函数在 main.py 中导入并装饰。 # 方案A直接在main.py中简单演示 # app starlight.App() # app.route(‘/hello‘, methods[‘GET‘]) # async def hello_handler(request: starlight.Request): # return starlight.Response({“message“: “Hello, Starlight“}, status_code200) # 方案B模块化组织推荐 # 在 app/routers/greeting.py 中 from starlight import Request, Response # 注意app对象需要从主模块传入或使用蓝图如Skill未提及蓝图则按简单方式 # 假设我们定义一个函数它将在main.py中被装饰。 async def hello_handler(request: Request) - Response: “““处理 /hello 请求””” data {“message“: “Hello, Starlight“} return Response(data, status_code200) # 然后在 app/main.py 中 # from app.routers import greeting # app.route(‘/hello‘, methods[‘GET‘])(greeting.hello_handler)分析Claude成功应用了Skill。它知道要用app.route或等效方式处理函数是async def并且返回starlight.Response。它还主动考虑了代码组织给出了两种方案这甚至超出了Skill的细节要求体现了模型的理解和推理能力。测试用例2涉及数据库的复杂操作我的提问“假设我有一个users表有id,name,email字段。请创建一个POST接口/users接收JSON数据{“name“: “...“, “email“: “...“}插入数据库并返回创建的用户信息。”Claude的输出部分展示关键点# app/routers/users.py import starlight from starlight import Request, Response async def create_user(request: Request) - Response: # 1. 获取请求数据 try: user_data await request.json() # 注意异步读取 except Exception: return Response({“error“: “Invalid JSON“}, status_code400) name user_data.get(‘name‘) email user_data.get(‘email‘) if not name or not email: return Response({“error“: “Missing name or email“}, status_code400) # 2. 数据库操作 # 假设app实例已配置数据库连接池 # 此函数被调用时app对象应已存在。这里展示逻辑。 # 实际应用中可能需要通过请求上下文或依赖注入获取app.db这里假设可以访问。 # 一种常见模式是在路由注册时传递db实例但根据Skill我们使用 app.db # 我们需要重构Skill指出app.db是属性但如何在路由函数内访问app # 这暴露了Skill的一个模糊点路由函数如何访问app对象 # 典型模式是使用请求状态request.app或全局变量。我们根据常见异步框架模式补充 # Starlight可能将app存储在request.state.app或类似位置。假设是 request.app。 # 修改Skill知识请求对象可能有一个 app 属性指向应用实例。 # 因此数据库操作应为 async with request.app.db.acquire() as conn: query “INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id, name, email“ # 假设使用asyncpg风格占位符 row await conn.fetchrow(query, name, email) new_user dict(row) if row else None if not new_user: return Response({“error“: “Creation failed“}, status_code500) # 3. 返回响应 return Response(new_user, status_code201)分析这次测试暴露了Skill的一个关键漏洞Skill中没有明确说明在路由处理函数内部如何获取到app对象以访问app.db。Claude基于常见模式如FastAPI的request.app进行了合理推测并给出了代码同时也注释指出了这个不确定性。这是一个非常重要的反馈3.4 第四步Skill的迭代与修补根据测试反馈我需要立即更新Skill指令修补模糊和错误的地方。针对“如何访问数据库”的漏洞我更新了Skill知识部分重要修正应用实例访问在路由处理函数内部可以通过request.app属性访问到当前的Starlight应用实例。因此数据库操作的正确写法是async with request.app.db.acquire() as conn: # ... 执行SQL ...请确保在创建App时已传入正确的database_url配置。同时我可能还需要补充一些常见错误的处理例如JSON解析错误、数据库连接异常等让Skill更加健壮。经过几轮这样的测试-反馈-修正循环这个Starlight框架的Skill就会变得越来越可靠和强大。4. 高级技巧让Skill更强大、更通用一个基础的Skill能让模型“照章办事”而一个优秀的Skill能让模型“举一反三”。以下是一些提升Skill等级的技巧。4.1 引入“设计模式”和“最佳实践”不要只教API用法要教“套路”。在Skill中加入框架常用的设计模式能极大提升模型生成代码的质量。例如在Starlight的Skill中我可以加入数据验证模式对于输入数据建议使用pydantic模型进行验证。在Skill中提供示例from pydantic import BaseModel class UserCreate(BaseModel): name: str email: str async def create_user(request: Request): try: user_data await request.json() user UserCreate(**user_data) # 触发验证 except ValidationError as e: return Response({“errors“: e.errors()}, status_code422) # ... 后续逻辑依赖注入模式对于需要共享的服务如数据库会话、认证层可以描述一种简单的依赖注入模式即使框架不原生支持。# 定义一个获取数据库连接的依赖函数 async def get_db_conn(request): async with request.app.db.acquire() as conn: yield conn # 在路由处理函数中使用 async def get_users(request, conn Depends(get_db_conn)): # 这里conn已由依赖函数提供 users await conn.fetch(“SELECT * FROM users“) ...注意这里Depends可能是你假定的或框架类似的机制需要在Skill中说明其实现方式或指出这是一种推荐模式。4.2 构建“反例库”和“审查清单”在Skill中明确写出“坏味道”代码和“不要做的事情”能有效防止模型生成有缺陷的代码。常见反例错误同步数据库调用conn.execute(query)缺少await。Starlight的数据库连接是异步的必须使用await。错误直接返回字典return {“msg“: “ok“}。这会导致Starlight报错必须包装在Response中。错误忘记异常处理对request.json()和数据库操作不做try...except包裹可能导致应用崩溃。代码审查清单 在输出任何Starlight代码后请自行检查[ ] 所有路由处理函数是否都以async def开头[ ] 所有返回给客户端的数据是否都包装在starlight.Response中[ ] 所有涉及I/O的操作网络请求、数据库是否都正确使用了await[ ] 是否对用户输入进行了基本的验证或清理4.3 创建“场景化任务模板”对于最常见的开发任务直接在Skill中提供模板。当用户提出类似需求时模型可以快速套用并修改。模板创建完整的CRUD路由器对于一个/items资源通常需要以下端点GET /items列表查询可能带分页、过滤。POST /items创建新项。GET /items/{item_id}获取单项。PUT/PATCH /items/{item_id}更新单项。DELETE /items/{item_id}删除单项。在Skill中提供一个简化的items.py模块模板包含函数骨架和注释说明每个部分需要填充什么。当用户说“为我的产品表实现CRUD”时模型可以直接引用这个模板大幅提升生成效率和准确性。5. 避坑指南构建Skill时最容易犯的五个错误在多次构建不同领域Skill的过程中我踩过不少坑。总结下来主要有以下五个常见错误错误1知识堆砌缺乏结构把整篇文档复制粘贴进Skill。这会导致上下文窗口被低信息密度的内容占据模型无法抓住重点而且容易因为无关信息产生干扰。正确做法像本章节3.1所示进行提炼、归纳和表格化。只放入最核心的概念、API和流程。错误2定义模糊存在二义性使用“可能”、“通常”、“类似XXX”这样的模糊词汇。例如“数据库连接大概通过app.db访问”。模型会困惑进而产生不一致或错误的输出。正确做法使用绝对肯定的语气。“数据库连接通过app.db属性访问它是一个异步连接池对象。”如果不确定就去查证直到能给出确切描述。错误3忽略边界条件和错误处理只描述了“成功路径”。当用户输入不合法或系统出现异常时模型不知道该如何处理可能会生成不安全的代码。正确做法在Skill中明确关键操作的错误处理模式。例如“调用await request.json()时必须用try...except包裹因为用户可能发送非JSON数据。”并提供示例代码片段。错误4思维链过于简单或缺失仅仅提供了知识但没有指导模型如何运用这些知识。模型可能会以错误的顺序或方式组合这些知识点。正确做法必须包含清晰的思考步骤Chain-of-Thought如本章节2.2和3.2所示。强制模型按照“解析-匹配-构建-填充-检查”的流程工作。错误5一次成型从不测试和迭代认为写完Skill指令就大功告成。实际上第一个版本的Skill几乎必然存在漏洞。正确做法将Skill的构建视为一个敏捷开发过程。编写 - 用典型和边缘用例测试 - 分析输出中的问题 - 修正Skill指令 - 再次测试。循环2-3次后Skill的可靠性会显著提升。6. 扩展应用Skill思维的无限可能让Claude学会一个框架只是Skill应用的一个起点。这种“不微调模型只写Skill”的思路可以扩展到无数领域。场景一内部工具与私有API你的公司有一套内部REST API或数据查询语言外部模型绝无可能知道。你可以为这套系统构建一个Skill详细说明认证方式如特殊的Header格式、端点地址规则、请求/响应数据格式、错误码含义。之后团队任何成员都可以用自然语言让Claude生成调用这些内部API的正确代码极大提升效率。场景二特定领域语言DSL或配置文件比如你团队使用一种特定的YAML格式来定义数据流水线。你可以构建一个Skill描述这种YAML的结构、每个字段的含义、有效的枚举值、以及配置之间的依赖关系。然后你就可以对Claude说“创建一个YAML配置它从Kafka主题A读取数据过滤掉状态为‘failed’的记录然后写入到Elasticsearch的索引B中。” Claude就能基于Skill生成基本正确的配置。场景三复杂、多步骤的运维或部署流程例如一套基于Kubernetes和Helm的微服务部署流程涉及多个命令和文件修改。你可以将整个流程拆解成Skill包括1环境检查清单2配置修改点说明3一系列有序执行的命令并解释每个命令的作用4验证部署是否成功的检查点。这样即使是新人也能通过向装备了此Skill的Claude提问安全地执行部署。场景四创意写作的特定风格与规则如果你想用Claude辅助生成符合某品牌调性、某种特定文风如学术摘要、产品说明书、武侠小说的文本你也可以构建Skill。这个Skill里定义的是“风格要素”常用词汇库、句子结构偏好、段落展开逻辑、禁止使用的词语等。这比单纯说“请用科技感强的风格写”要有效和稳定得多。构建Skill的核心思想是将人类专家的领域知识和思维过程外化成一种结构化的、机器可精确遵循的“协议”。它绕开了模型本身知识的局限性通过上下文学习的方式为模型临时装备上一个专业的“大脑模块”。这个过程本身也是对你自己领域知识的一次极佳梳理和沉淀。当你试图把你知道的东西清晰地教给AI时你往往会对这些知识有更深的理解。