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時你往往會對這些知識有更深的理解。