之前做 AI 輔助開發(fā)時我更多是把 Claude、GPT 當(dāng)成一個“加強(qiáng)版對話窗口”讓它寫函數(shù)、補(bǔ)注釋、解釋報錯。但真正進(jìn)入 Agent 開發(fā)之后我發(fā)現(xiàn)最核心的差距不是模型選哪個而是有沒有一套“能讓 Agent 穩(wěn)定復(fù)用能力”的機(jī)制。這段時間在 Claude Code 和 Codex 之間來回切換踩了不少配置和調(diào)用層面的坑也逐步把零散的 Prompt 整理成了可復(fù)用的技能包。這篇文章就把我從“會用 AI”到“開發(fā) Agent Skills”的完整經(jīng)驗(yàn)整理出來包含概念拆解、環(huán)境搭建、Skill 目錄規(guī)范、兩個實(shí)戰(zhàn)案例以及高頻報錯的排查思路。文章內(nèi)容較多建議先收藏再慢慢看。1. Agent 與 Agent Skills 核心概念梳理1.1 從 AI 對話助手到 Agent傳統(tǒng)使用 AI 的方式是“你問我答”用戶給一段 Prompt模型生成一段回復(fù)。這種方式適合寫文案、改代碼片段、做知識問答但無法完成多步驟任務(wù)因?yàn)槟Ｐ捅旧聿徽莆瘴募到y(tǒng)、命令行和外部服務(wù)。Agent 的出現(xiàn)改變了這個模式。Agent 可以理解為一個具備“感知 - 決策 - 行動”閉環(huán)的智能體。它不僅能生成文本還能調(diào)用工具、讀取文件、執(zhí)行命令、根據(jù)運(yùn)行結(jié)果調(diào)整下一步操作。比如讓 Agent 完成“拉取代碼、跑測試、收集失敗用例、給出修復(fù)建議”這一整套流程它需要不斷與環(huán)境交互而不只是輸出一段建議。從這個角度看Agent 的關(guān)鍵能力有三個工具調(diào)用能調(diào)用外部函數(shù)或命令。上下文管理能記住任務(wù)目標(biāo)和已執(zhí)行步驟。自主決策能根據(jù)中間結(jié)果決定下一步動作。而要讓 Agent 真正做到“穩(wěn)定可用”關(guān)鍵不只是選哪個模型而是如何把某一類任務(wù)的執(zhí)行知識固化下來這就是本文要講的 Agent Skills。1.2 Agent Skills 是什么Agent Skills 是一套面向 Agent 的“技能封裝機(jī)制”。它把某個領(lǐng)域的執(zhí)行步驟、規(guī)則、示例、約束整理成標(biāo)準(zhǔn)的目錄結(jié)構(gòu)讓 Agent 在遇到相關(guān)任務(wù)時可以自動加載并按照技能定義去執(zhí)行。舉一個容易理解的類比傳統(tǒng) Prompt 相當(dāng)于在對話里告訴 AI“你應(yīng)該怎么做”而 Agent Skill 相當(dāng)于給 AI 安裝一個“崗位說明書 操作手冊 常用工具包”。前者是一次性的口頭交代后者是可復(fù)用、可擴(kuò)展、可版本管理的標(biāo)準(zhǔn)化資產(chǎn)。在 Claude Code 中Skills 通常表現(xiàn)為項(xiàng)目下的.claude/skills目錄每個技能是一個子目錄里面包含SKILL.md主文件以及其他輔助腳本、模板、資料文件。Agent 讀取SKILL.md后會按照里面的指令去完成相關(guān)任務(wù)。1.3 Agent Skills 與 Tools、MCP 的區(qū)別這是最容易混淆的地方。很多開發(fā)者分不清 Agent Skills、Tools 和 MCP 有什么區(qū)別。Tools 是 Agent 可以調(diào)用的具體函數(shù)或命令比如“獲取當(dāng)前時間”“執(zhí)行 Shell 命令”“讀取文件”。它偏底層解決的是“Agent 能不能做某件事”。MCPModel Context Protocol是一種標(biāo)準(zhǔn)化協(xié)議用來讓 Agent 與外部數(shù)據(jù)源、工具服務(wù)進(jìn)行統(tǒng)一通信。它更多是解決“Agent 怎么連接到外部能力”。Agent Skills 偏高層它解決的不僅是“能不能做”和“怎么連”還包括“怎么做才符合規(guī)范和最佳實(shí)踐”。一個 Skill 可以包含多個工具調(diào)用步驟、判斷條件和輸出格式要求。簡單總結(jié)層次解決什么問題典型示例ToolsAgent 能執(zhí)行哪些原子操作執(zhí)行 Shell 命令、讀取文件MCPAgent 如何標(biāo)準(zhǔn)化連接外部服務(wù)通過 MCP 連接數(shù)據(jù)庫、GitHubAgent SkillsAgent 如何按規(guī)范完成一類任務(wù)代碼審查技能、日志排查技能實(shí)際項(xiàng)目中三者的關(guān)系通常是Skill 在內(nèi)部定義調(diào)用流程流程中可能使用 Tools也可能通過 MCP 訪問外部系統(tǒng)。1.4 為什么需要 Agent Skills沒有 Skills 的情況下也可以讓 Agent 干活但存在幾個明顯問題每次都要重復(fù)寫很長的任務(wù)指令效率低且不同人對同一類任務(wù)的描述不一致導(dǎo)致輸出質(zhì)量波動大。Prompt 里的隱性經(jīng)驗(yàn)無法沉淀團(tuán)隊成員之間無法共享“如何做好代碼審查”“如何排查線上故障”這類知識。當(dāng)任務(wù)步驟復(fù)雜時模型可能遺漏約束條件比如忘記跑測試、忘記檢查文件編碼、輸出的格式不符合項(xiàng)目規(guī)范。將執(zhí)行經(jīng)驗(yàn)封裝成 Agent Skills 后團(tuán)隊可以把方法論固化到項(xiàng)目倉庫中模型在需要時自動加載既能保證一致性又能持續(xù)迭代優(yōu)化。2. 環(huán)境準(zhǔn)備與版本說明在開始動手之前先把環(huán)境準(zhǔn)備好。這里的版本信息比較多不同版本之間差異較大需要根據(jù)實(shí)際環(huán)境調(diào)整。2.1 基礎(chǔ)運(yùn)行環(huán)境我本地的環(huán)境如下供參考操作系統(tǒng)macOSWindows/Linux 同樣支持Node.js18 及以上版本包管理器npmGit具備基本命令行使用能力終端工具建議使用支持長文本輸出的終端Claude Code 和 Codex 的實(shí)際版本更新比較頻繁因此本文不會寫死具體版本號。你在安裝時需以官方文檔展示的最新版本為準(zhǔn)本文重點(diǎn)演示配置思路和技能編寫方法。2.2 安裝 Claude CodeClaude Code 是 Anthropic 推出的終端編程助手支持在項(xiàng)目目錄中直接啟動能夠讀取文件結(jié)構(gòu)、執(zhí)行命令、調(diào)用 Skill。安裝方式通常是通過 npm 全局安裝npm install -g anthropic-ai/claude-code安裝完成后在終端輸入claude即可啟動交互界面。首次啟動時會要求完成登錄認(rèn)證請根據(jù)自己的賬號類型選擇對應(yīng)的認(rèn)證方式。注意不同區(qū)域、不同訂閱類型支持的模型和功能有差異具體以官方說明為準(zhǔn)。啟動成功的標(biāo)志是出現(xiàn)可交互的命令行界面并且能夠正?；卮痦?xiàng)目相關(guān)的問題。2.3 安裝 CodexCodex 是 OpenAI 推出的編程 Agent 工具同樣運(yùn)行在終端環(huán)境中。安裝命令通常為npm install -g openai/codex安裝完成后在需要使用的項(xiàng)目目錄中執(zhí)行codex即可進(jìn)入交互模式。Codex 支持通過配置文件指定模型來源、API 地址等參數(shù)這也是后續(xù)接入不同模型服務(wù)的入口。如果你需要使用本地模型或其他兼容接口可以查看配置文件說明將model_providers指向本地服務(wù)地址。注意模型能力差異會導(dǎo)致 Agent 表現(xiàn)不同建議使用官方推薦模型以保證技能執(zhí)行效果。2.4 配置管理工具 cc-switch在實(shí)際開發(fā)中不少開發(fā)者會在 Claude Code 和 Codex 之間來回切換為了管理不同環(huán)境的配置會使用 cc-switch 這類配置切換工具。cc-switch 可以理解為一個“配置管理器”它支持維護(hù)多套 API 配置并根據(jù)需要快速切換。安裝和配置的詳細(xì)步驟以 cc-switch 官方文檔為準(zhǔn)。常見做法是在圖形界面中添加多套配置保存后通過菜單切換。使用這類工具時務(wù)必注意不要在生產(chǎn)環(huán)境隨意切換配置也不要把密鑰明文提交到倉庫。2.5 驗(yàn)證環(huán)境是否可用安裝完成后建議先做一個最小化的環(huán)境驗(yàn)證。在任意項(xiàng)目目錄下執(zhí)行claude --version codex --version如果兩個命令都能正常輸出版本號說明基礎(chǔ)環(huán)境已就緒。接下來可以創(chuàng)建一個測試目錄開始編寫第一個 Agent Skill。3. 理解 Skill 的組織形式與加載機(jī)制3.1 Skill 的推薦目錄結(jié)構(gòu)以 Claude Code 為例一個完整的 Skill 通常放在項(xiàng)目的.claude/skills目錄下結(jié)構(gòu)如下.claude/ └── skills/ └── code-review/ ├── SKILL.md ├── scripts/ │ └── review.py可選 └── references/ └── checklist.md可選每個技能目錄的名稱建議使用中劃線分隔例如code-review、log-analysis、dependency-check。目錄內(nèi)部必須有SKILL.md這是一切技能定義的核心入口。SKILL.md會被 Agent 讀取并解析其他輔助腳本和參考資料則按需調(diào)用。3.2 SKILL.md 的元信息格式SKILL.md不僅僅是一份 Markdown 文檔它還包含一段 YAML 格式的 frontmatter用于描述技能的元信息包括技能名稱、描述、使用場景等。這段元信息非常重要因?yàn)?Agent 需要通過“描述”來判斷當(dāng)前任務(wù)是否與某個技能匹配。一個最小化的SKILL.md示例--- name: code-review description: 用于執(zhí)行代碼審查任務(wù)。當(dāng)用戶要求檢查代碼質(zhì)量、發(fā)現(xiàn)潛在缺陷、給出優(yōu)化建議時使用本技能。 --- # 代碼審查技能 ## 目標(biāo) ... ## 執(zhí)行步驟 ...需要注意description字段要寫清楚技能的能力范圍和觸發(fā)條件盡量使用與用戶自然語言重合度高的詞匯。如果描述過于模糊Agent 在遇到相關(guān)任務(wù)時可能無法正確加載該技能。3.3 Skill 的加載機(jī)制Agent 并不會一次性把所有 Skill 都讀進(jìn)上下文那樣既浪費(fèi) token 又影響響應(yīng)速度。常見的設(shè)計是“按需加載”Agent 根據(jù)當(dāng)前任務(wù)的內(nèi)容結(jié)合所有 Skill 的描述元信息篩選出最匹配的技能再讀取對應(yīng)的SKILL.md文件。因此編寫 Skill 時要特別注意描述要精準(zhǔn)便于匹配。SKILL.md 內(nèi)容要結(jié)構(gòu)化便于 Agent 快速提取關(guān)鍵步驟。大段的示例代碼盡量放在 references 或 scripts 中避免主文件過長。3.4 編寫 Skill 的基本原則根據(jù)實(shí)踐我認(rèn)為編寫高質(zhì)量 Skill 需要遵循下面幾個原則單一職責(zé)一個 Skill 只解決一類問題。不要把“代碼審查 日志分析 性能優(yōu)化”塞到同一個技能里。步驟明確執(zhí)行步驟要按順序編號并給出每個步驟的輸入、操作、輸出。有判斷條件遇到什么情況應(yīng)停止遇到什么情況應(yīng)切換方案需要在 SKILL.md 中寫清楚。提供示例給出一兩個正反示例幫助 Agent 理解輸出標(biāo)準(zhǔn)?？蓽y試技能寫完后要設(shè)計一個固定的測試任務(wù)驗(yàn)證效果。4. 實(shí)戰(zhàn)案例一在 Claude Code 中創(chuàng)建第一個 Skill這一節(jié)我們實(shí)際動手創(chuàng)建一個可復(fù)用的“需求拆解技能”。該技能的作用是當(dāng)用戶提出一個模糊的開發(fā)需求時Agent 能按照既定模板將需求拆分為背景、目標(biāo)、功能列表、驗(yàn)收標(biāo)準(zhǔn)、技術(shù)選型建議和風(fēng)險點(diǎn)。4.1 創(chuàng)建項(xiàng)目結(jié)構(gòu)先創(chuàng)建項(xiàng)目目錄mkdir -p agent-demo/.claude/skills/requirement-split cd agent-demo然后在requirement-split目錄下創(chuàng)建SKILL.md文件。4.2 編寫 SKILL.md文件路徑agent-demo/.claude/skills/requirement-split/SKILL.md--- name: requirement-split description: 用于將模糊的產(chǎn)品需求拆解為可執(zhí)行的技術(shù)開發(fā)任務(wù)。當(dāng)用戶提出一個新的功能想法、業(yè)務(wù)需求或者需要整理開發(fā)任務(wù)清單時使用本技能。 --- # 需求拆解技能 ## 目標(biāo) 將模糊的功能描述轉(zhuǎn)化為結(jié)構(gòu)化的開發(fā)需求說明降低后續(xù)開發(fā)與測試的溝通成本。 ## 執(zhí)行步驟 1. 提取用戶原始需求中的核心意圖。 2. 按照下面的模板輸出需求說明。 ## 輸出模板 ### 需求背景 說明該需求要解決的業(yè)務(wù)問題。 ### 需求目標(biāo) 用 1-3 句話描述最終達(dá)成的效果。 ### 功能清單 - 功能點(diǎn) 1描述 - 功能點(diǎn) 2描述 ### 驗(yàn)收標(biāo)準(zhǔn) - 標(biāo)準(zhǔn) 1如何驗(yàn)證功能是否正確 ### 技術(shù)建議 推薦技術(shù)棧和實(shí)現(xiàn)方案。 ### 風(fēng)險點(diǎn) 列出可能的實(shí)現(xiàn)風(fēng)險或依賴項(xiàng)。 ## 注意事項(xiàng) - 如果用戶給出的信息不足先向用戶提問補(bǔ)齊關(guān)鍵信息不要憑空編造需求。 - 輸出格式嚴(yán)格遵循上述模板使用中文。這個技能的核心是約束 Agent 的輸出結(jié)構(gòu)。沒有技能時不同對話里 Agent 拆解需求的格式可能完全不同有了技能后輸出格式就變得可控了。4.3 編寫輔助腳本可選如果希望技能在執(zhí)行時自動調(diào)用腳本可以在技能目錄下增加scripts文件夾。例如創(chuàng)建一個簡單的模板生成腳本文件路徑agent-demo/.claude/skills/requirement-split/scripts/generate_template.py#!/usr/bin/env python3 # -*- coding: utf-8 -*- 根據(jù)需求關(guān)鍵詞生成需求文檔模板。 import sys def main(): keyword sys.argv[1] if len(sys.argv) 1 else 未命名需求 template f# {keyword} 需求說明 ## 需求背景 待補(bǔ)充 ## 需求目標(biāo) 待補(bǔ)充 ## 功能清單 - 待補(bǔ)充 ## 驗(yàn)收標(biāo)準(zhǔn) - 待補(bǔ)充 ## 技術(shù)建議 待補(bǔ)充 ## 風(fēng)險點(diǎn) 待補(bǔ)充 print(template) if __name__ __main__: main()在SKILL.md中可以通過類似下面這樣的描述來引導(dǎo) Agent 調(diào)用腳本## 工具使用 當(dāng)需要生成空模板時執(zhí)行以下命令 python3 .claude/skills/requirement-split/scripts/generate_template.py 需求名稱注意腳本路徑寫法要基于項(xiàng)目根目錄并且要確保腳本具備執(zhí)行權(quán)限。4.4 在 Claude Code 中測試 Skill在agent-demo目錄下啟動 Claude Codeclaude然后在交互界面輸入類似這樣的任務(wù)請幫我把“用戶登錄增加短信驗(yàn)證碼”這個需求進(jìn)行拆解。如果配置正確Agent 會加載requirement-split技能并按照模板輸出需求文檔。如果輸出結(jié)構(gòu)不符合預(yù)期可以檢查 SKILL.md 的描述是否與任務(wù)語句匹配。4.5 運(yùn)行驗(yàn)證預(yù)期輸出應(yīng)該是包含“需求背景、需求目標(biāo)、功能清單、驗(yàn)收標(biāo)準(zhǔn)、技術(shù)建議、風(fēng)險點(diǎn)”的結(jié)構(gòu)化文檔?？梢詫Ρ纫幌掠屑寄芎蜎]有技能時輸出的差異你會發(fā)現(xiàn)有技能時輸出內(nèi)容更加穩(wěn)定幾乎不會漏掉關(guān)鍵模塊。5. 實(shí)戰(zhàn)案例二在 Codex 中復(fù)用類似技能5.1 Codex 支持自定義指令的方式Codex 同樣支持項(xiàng)目級自定義指令。與 Claude Code 的.claude/skills目錄不同Codex 通常通過項(xiàng)目根目錄下的AGENTS.md文件來定義項(xiàng)目的規(guī)則、約定和任務(wù)執(zhí)行流程。Codex 在啟動時會讀取該文件將其作為會話的長期上下文。這意味著我們可以把“需求拆解技能”的模板直接寫入AGENTS.md讓 Codex 在工程中也具備同樣的輸出規(guī)范。5.2 編寫 AGENTS.md文件路徑agent-demo/AGENTS.md# 項(xiàng)目 Agent 規(guī)則 ## 需求拆解 當(dāng)用戶提出新的功能需求時必須按以下模板輸出 ### 需求背景 說明該需求要解決的業(yè)務(wù)問題。 ### 需求目標(biāo) 用 1-3 句話描述最終達(dá)成的效果。 ### 功能清單 - 功能點(diǎn) 1描述 - 功能點(diǎn) 2描述 ### 驗(yàn)收標(biāo)準(zhǔn) - 標(biāo)準(zhǔn) 1如何驗(yàn)證功能是否正確 ### 技術(shù)建議 推薦技術(shù)棧和實(shí)現(xiàn)方案。 ### 風(fēng)險點(diǎn) 列出可能的實(shí)現(xiàn)風(fēng)險或依賴項(xiàng)。 如果用戶提供的信息不足以編寫需求文檔必須先繼續(xù)提問補(bǔ)齊信息后再輸出。這個文件的作用和SKILL.md類似但粒度上是“項(xiàng)目級約束”。它適合把整個項(xiàng)目都要遵守的規(guī)則放進(jìn)去例如代碼風(fēng)格、提交規(guī)范、測試要求等。5.3 配置 Codex 使用不同模型來源Codex 默認(rèn)使用的模型可以通過配置文件調(diào)整。常見做法是在用戶目錄下創(chuàng)建配置文件或者在項(xiàng)目目錄中配置.codex相關(guān)文件。一個常見的場景是接入兼容 OpenAI 接口的本地模型服務(wù)。配置文件中的關(guān)鍵項(xiàng)大致如下{ model_providers: { local: { name: Local Model, base_url: http://localhost:11434/v1, env_key: LOCAL_API_KEY } }, model: local/qwen2.5-coder:latest }需要注意的是這里只是演示配置結(jié)構(gòu)實(shí)際字段名和接口路徑可能會隨 Codex 版本變化。接入本地模型前先確認(rèn)本地模型服務(wù)是否已啟動以及/v1/chat/completions等接口是否可用。如果模型能力較弱技能執(zhí)行效果可能不穩(wěn)定建議在本地模型場景下降低任務(wù)復(fù)雜度。5.4 運(yùn)行驗(yàn)證在agent-demo目錄下啟動 Codexcodex輸入相同的需求請拆解“增加用戶短信登錄功能”的需求。Codex 在讀取AGENTS.md后會按照同樣的模板輸出需求文檔。這個案例說明了 Agent Skills 的一種跨工具遷移思路底層邏輯一致只是承載文件不同。6. 技能開發(fā)進(jìn)階與擴(kuò)展6.1 多個 Skill 的組合編排在真實(shí)項(xiàng)目中一個任務(wù)往往需要多個技能配合。例如“開發(fā)一個登錄接口”這個任務(wù)可能同時涉及“需求拆解技能”“代碼審查技能”“測試用例生成技能”。組合編排的關(guān)鍵在于每個 Skill 的職責(zé)要清晰輸入輸出要明確。比如需求拆解技能輸出需求文檔測試用例生成技能讀取需求文檔生成用例。通過這種“前一個技能的輸出是后一個技能的輸入”的方式可以構(gòu)建復(fù)雜的自動化流水線。Claude Code 支持在對話中按需加載不同技能你可以通過連續(xù)指令讓 Agent 依次調(diào)用。6.2 技能與外部工具的結(jié)合Agent Skills 的能力邊界可以進(jìn)一步擴(kuò)展。比如在 SKILL.md 中定義“當(dāng)需要調(diào)用某外部服務(wù)時使用以下命令”或者通過腳本調(diào)用外部 HTTP 接口。這里的安全風(fēng)險需要注意技能中的命令如果寫得不夠嚴(yán)謹(jǐn)Agent 可能執(zhí)行預(yù)期之外的命令。建議對技能內(nèi)的 Shell 命令做白名單控制并強(qiáng)調(diào)只能在授權(quán)的項(xiàng)目目錄中運(yùn)行。6.3 技能的版本管理與共享由于 SKILL.md 本質(zhì)上是文本文件完全可以納入 Git 版本管理。團(tuán)隊協(xié)作時可以把技能目錄放在一個獨(dú)立倉庫中通過 Git 子模塊或復(fù)制方式引入各個項(xiàng)目。版本管理的好處是技能變更可追蹤?？梢曰厮莸脚f版技能進(jìn)行對比。支持多團(tuán)隊共享一套最佳實(shí)踐。6.4 與本地模型的結(jié)合場景對于一些需要數(shù)據(jù)隔離或離線開發(fā)的場景可以將 Claude Code、Codex 與本地模型結(jié)合使用。常見方案是使用 Ollama 這類本地推理工具啟動模型服務(wù)然后通過配置把 API 指向本機(jī)地址。這種方案的優(yōu)勢是數(shù)據(jù)不外傳、可以離線使用缺點(diǎn)是模型能力相比云端模型有一定差距Agent 在復(fù)雜任務(wù)上的表現(xiàn)可能下降。因此本地模型場景下建議降低單次任務(wù)復(fù)雜度。在 SKILL.md 中增加更細(xì)化的步驟。對輸出結(jié)果增加校驗(yàn)環(huán)節(jié)。7. 常見問題與排查思路7.1 Claude Code 安裝失敗或命令找不到如果執(zhí)行claude提示找不到命令可能有幾種原因Node.js 版本過低建議升級到 18 及以上。npm 全局安裝路徑不在系統(tǒng) PATH 中需要配置環(huán)境變量。安裝過程中網(wǎng)絡(luò)問題導(dǎo)致包未下載完整。排查順序先檢查 Node 版本再查看 npm 全局目錄最后確認(rèn)環(huán)境變量。7.2 Codex 啟動時提示本地代理配置異常有網(wǎng)友反饋過類似這樣一條報錯本地代理配置失敗Codex 在調(diào)用接口時請求未能正常轉(zhuǎn)發(fā)。這類問題的核心通常不是模型本身的問題而是本地代理服務(wù)的地址、端口或協(xié)議與 Codex 的預(yù)期不一致。解決辦法檢查代理服務(wù)是否啟動。核對配置文件中的base_url是否完整是否包含http://前綴。確認(rèn)請求是否可以直達(dá)目標(biāo)接口必要時可以先用curl做一次連通性測試。注意不要在未確認(rèn)目標(biāo)服務(wù)合法性的情況下隨意配置代理也不要將內(nèi)網(wǎng)地址暴露到公網(wǎng)。7.3 Skill 沒有被 Agent 加載如果發(fā)現(xiàn)輸入的指令符合技能描述但 Agent 仍然沒有按 SKILL.md 輸出可以從以下幾點(diǎn)排查檢查技能目錄是否放在正確的路徑下例如.claude/skills。檢查 SKILL.md 的 frontmatter 是否合法YAML 格式是否出錯。檢查description字段是否與任務(wù)語句匹配。查看 Agent 啟動日志確認(rèn)有沒有讀取技能文件。7.4 Agent 執(zhí)行過程被中斷有時候 Agent 在執(zhí)行多步任務(wù)時提示執(zhí)行被終止。這類問題通常與以下原因有關(guān)單步執(zhí)行時間過長觸發(fā)了超時。命令交互等待輸入但無法自動處理。腳本異常退出Agent 無法接收下一步指令。建議把長任務(wù)拆短在 SKILL.md 中要求 Agent 分階段執(zhí)行每個階段完成后輸出結(jié)果再決定是否繼續(xù)。也可以適當(dāng)調(diào)整超時時間但要注意不同工具版本對超時限制的差異。7.5 常見問題匯總問題現(xiàn)象常見原因解決思路安裝后命令找不到PATH 未配置或 Node 版本過低升級 Node檢查 npm 全局路徑Agent 未加載技能目錄路徑錯誤或 SKILL.md 格式錯誤核對路徑檢查 YAML 格式輸出格式混亂技能描述不夠清晰細(xì)化 SKILL.md 步驟和模板執(zhí)行中斷任務(wù)過長或腳本卡住拆分任務(wù)增加階段輸出本地代理配置報錯地址、協(xié)議或端口不匹配核對配置先用 curl 測試連通性不同工具行為不一致Claude Code 與 Codex 加載邏輯不同分別查看各自文檔調(diào)整配置8. 最佳實(shí)踐與工程建議8.1 Skill 命名與目錄規(guī)劃技能命名要短且語義明確推薦使用中劃線命名法如code-review、db-migration、api-design。目錄層級不要太深一般兩層即可避免 Agent 搜索和讀取文件的開銷過大。8.2 保持技能文件的精簡SKILL.md 不是文檔網(wǎng)站不要把所有知識都堆進(jìn)去。主文件控制在 50 到 100 行左右復(fù)雜的參考資料放到references目錄中腳本放到scripts目錄中。核心目的是讓 Agent 快速理解“要做什么”和“按什么順序做”而不是把大模型當(dāng)瀏覽器用。8.3 明確限制邊界在技能描述中一定要寫清楚哪些事情不允許做。比如不允許執(zhí)行數(shù)據(jù)庫刪除操作。不允許在沒有測試的情況下直接修改生產(chǎn)配置。不允許讀取項(xiàng)目外的敏感文件。不允許將密鑰寫入代碼倉庫。Agent 雖然不具主觀惡意但它會忠實(shí)執(zhí)行指令。技能里缺少安全邊界就可能在自動化流程中產(chǎn)生風(fēng)險。8.4 配置與密鑰管理涉及 API Key、Token 等敏感信息時務(wù)必使用環(huán)境變量或密鑰管理服務(wù)。不要把它們寫進(jìn)SKILL.md、AGENTS.md或其他會提交到倉庫的文件中。在分享技能包時先檢查是否包含敏感信息。8.5 持續(xù)迭代與效果度量Agent Skills 不是寫一次就結(jié)束的。建議每次執(zhí)行后記錄輸出質(zhì)量分析哪些步驟不穩(wěn)定、哪些描述有歧義然后針對性修改。可以建立一個小型測試集每次修改技能后用固定的一組任務(wù)回歸測試保證效果不退化。8.6 結(jié)合項(xiàng)目實(shí)際選擇合適的載體Claude Code 的 Skills 目錄和 Codex 的 AGENTS.md 各有優(yōu)勢。Skills 更靈活適合“多技能按需加載”AGENTS.md 更直接適合“項(xiàng)目級強(qiáng)制規(guī)則”。實(shí)際項(xiàng)目中可以根據(jù)團(tuán)隊分工混合使用項(xiàng)目級通用規(guī)則寫入 AGENTS.md專業(yè)技能打包為 Skills。9. 總結(jié)與后續(xù)學(xué)習(xí)建議通過這篇文章我們從概念上梳理了 Agent 與 Agent Skills 的區(qū)別搞清楚了 Skills、Tools、MCP 三者的定位在實(shí)踐層面完成了 Claude Code 與 Codex 的環(huán)境搭建并用一個“需求拆解技能”走通了從 SKILL.md 編寫到 Agent 加載驗(yàn)證的全流程。對于常見安裝失敗、技能未加載、執(zhí)行中斷、本地代理配置報錯等問題也給出了具體的排查思路。接下來可以繼續(xù)深入的方向有三塊一是學(xué)習(xí) MCP 協(xié)議把 Agent 連接到真實(shí)的數(shù)據(jù)庫、文件服務(wù)和第三方 API二是研究多 Agent 協(xié)作模式讓不同技能由不同 Agent 分工執(zhí)行三是建立自己的技能庫把日常開發(fā)中反復(fù)出現(xiàn)的工作流逐步沉淀為可復(fù)用的 Agent Skills。開發(fā) Agent 的過程很像搭積木模型是底座技能是模塊能拼出多強(qiáng)的系統(tǒng)取決于你積累了多少高質(zhì)量模塊以及你愿不愿意持續(xù)打磨它們。如果這篇文章對你有幫助可以收藏備用也歡迎在評論區(qū)聊聊你在 Agent 開發(fā)中踩過的坑。