写这篇文章之前我先说个自己的真实感受以前我在 VS Code 里装 AI 插件图的是自动补全、聊聊天、解释报错。可一旦项目文件多了、工程结构复杂了这些插件就开始“答非所问”经常给我一个孤零零的函数片段完全不知道这个项目是干什么的、哪个文件能改、哪个模块不能碰。直到我把 Agent Skills 这套东西引入 VS Code才发现之前的用法太浅了——它不是多给你一个聊天窗口而是给编辑器里的 AI 装上了一个“项目大脑”。这篇文章不打算做名词科普也不会罗列官网文档。我想从实际操作的角度聊聊Agent Skills 到底解决什么问题、怎么把它装进 VS Code、如何通过它接入 DeepSeek、Qwen、GLM 这些模型以及我在 C、ESP-IDF、Python 这些真实项目里踩过的坑和验证过的配置。适合那些已经受够“弱智补全”、想让 AI 真正理解整个项目的开发者。1. Agent Skills 到底治的是什么病从“会写码”到“懂项目”1.1 普通 AI 插件和 Agent 的差距先说个现象很多人用 VS Code 里的 AI 插件体验就是“选中一段代码让 AI 解释”或者“让 AI 补全下一行”。这在写算法题、写脚本时够用但一旦到了真实工程里就露馅。原因不复杂普通的代码补全模型只看当前文件。你的项目里有几十个模块有公司内部的编码规范有特殊的编译流程有不允许乱动的遗留代码。这些信息模型统统看不到。你问它“这个模块为什么这么写”它只能从函数名和变量名里猜。而 Agent 类的工具比如 Claude Code、Codex 扩展或者 VS Code 里集成的各种 Agent 模式解决的是“多文件、多步骤、可操作”的问题。它能读目录结构、搜索函数定义、修改文件、执行终端命令。但光有 Agent 还不够——Agent 默认是通用能力它不知道你这个项目的规矩。这就是 Agent Skills 出现的核心原因。1.2 Skill 其实不是插件而是给 Agent 的“工作手册”Agent Skills 的底层形态是一个个带结构化说明的目录最常见的入口文件叫SKILL.md。你可以把它理解成给 AI 写的一份入职手册。普通插件是给编辑器扩展功能比如加个按钮、加个菜单Agent Skills 是给 AI 灌输“特定任务的操作流程”。例如你有一个“写单元测试”的 Skill里面会写明测试文件放在哪个目录、用什么命名规则、需要 mock 哪些外部依赖、跑测试用哪条命令。你有一个“处理编译报错”的 Skill里面会写明先看build目录下的日志、可用的编译器版本、已知的历史问题怎么规避。模型在调用这个 Skill 时会先读SKILL.md然后按里面的流程执行。这比你在聊天窗口里反复输入同一套项目背景要可靠得多。因为 Skill 可以随着项目演进单独维护不用每次对话都“重新教它”。如果你还没接触过这个机制建议这样理解Agent 是手Skill 是操作手册。手再灵活没有手册照样在陌生车间里瞎摸。2. 安装与目录结构把 Skill 放进 VS Code 项目里2.1 前置环境该怎么选 Agent 扩展要在 VS Code 里跑 Agent Skills你首先得有一个支持 Agent 模式的运行环境。我目前试过的可行组合有这么几种组合方式优点缺点Claude Code 官方扩展官方支持Skill 兼容性最好需要 Anthropic API 或相关账号国内网络配置麻烦VS Code 内置 Codex 扩展和 GitHub Copilot 生态互通对自定义 SKILL.md 支持不够灵活通过 CC Switch 接入第三方模型可切换 DeepSeek、Qwen、GLM成本低部分模型对 Agent Skills 的流程遵循能力有差异我个人目前的主力方案是VS Code 里装 Claude Code 扩展同时用 CC Switch 做多模型切换。这样既能享受官方对 Agent Skills 的支持又能在需要控成本时切到国产模型。以我的经验第一次配置需要确认几个点扩展装好后能不能在侧边栏打开 Agent 面板终端里能不能直接执行claude命令当前工作目录能不能正确识别项目根目录。如果这三个点都通了再进 Agent Skills 才顺畅。2.2 SKILL.md 的写法从需求到可执行流程Agent Skills 本身的目录结构并不复杂。以一个我常用的“Python 项目规范检查”Skill 为例目录长这样my-vscode-skills/ python-project-check/ SKILL.md scripts/ lint_check.pySKILL.md的内容不需要长篇大论但要结构明确。它通常包含几个段落适用场景、执行步骤、必须遵守的边界条件。下面是一个精简示例# Python Project Check Skill ## 适用场景 当用户要求检查当前 Python 项目的代码规范或者在提交前进行自查时使用。 ## 执行步骤 1. 先读取项目根目录的 pyproject.toml / setup.cfg确认使用哪种 lint 工具。 2. 查看 src 目录和 tests 目录的源码结构。 3. 运行项目自定义的 lint 命令poetry run task lint。 4. 如果输出中包含错误按“文件路径:行号: 错误信息”的格式汇总。 5. 对每个错误给出修复建议但不要直接批量修改文件除非用户明确授权。 ## 边界条件 - 禁止修改 vendor/、generated/ 目录下的任何文件。 - 禁止删除测试数据。 - 如果检测不到 pyproject.toml则停止并询问用户。写这个东西不需要很复杂的语法关键是让 AI 知道“什么情况调用、先做什么、后做什么、绝对不能做什么”。2.3 Profiles 别乱用一个容易翻车的点VS Code 里有一个 Profiles 功能很多人最初很迷惑。它本来是用来做“不同工作场景的配置集合”比如一个 Profile 搞前端开发一个 Profile 搞嵌入式开发。但我在实际使用中吃过亏如果你在 Profile A 里装好了 Agent 扩展和 Skills切到 Profile B 之后这些扩展并不会自动出现。于是经常出现“明明配好了 Agent换个 Profile 就不见了”的情况。建议的做法把 Agent Skills 相关配置放在一个专门的“AI 开发”Profile 里或者干脆使用默认 Profile避免配置分裂。如果你确实需要多 Profile请记住扩展和 Skill 目录都是按 Profile 隔离的要在每个需要的 Profile 里重新启用。3. 多模型接管CC Switch、DeepSeek、Qwen、GLM 怎么组合3.1 为什么值得折腾第三方模型很多人用 VS Code 里的 AI 服务第一反应是申请官方 API。但现实情况是官方模型的价格、速率限制、地区可用性都可能成为瓶颈。社区里更常见的做法是通过 CC Switch 这类工具把 Agent 的接口切换到其他模型供应商比如 DeepSeek、通义千问 Qwen、智谱 GLM。这样做的好处很明显价格便宜尤其是日常代码解释、命名建议这类低难度任务。可以针对不同任务切换不同模型比如日常闲聊和复杂重构分开。不用绑定单一厂商模型更新了随时换。需要注意的是Agent Skills 不只是“模型在聊天”它涉及多步推理、工具调用、按流程执行。不是所有模型都具备同样高的指令遵循能力。我在实测中发现有些模型能很好理解SKILL.md里的步骤有些模型则容易跳过步骤直接给结论。所以不要假设“接入即完美”需要为你的常用模型单独调整 Skill 的措辞。3.2 配置示例CC Switch 的实际接入流程我以“通过 CC Switch 接入 DeepSeek”为例说下实际配置步骤。这里假设你已经安装好 CC Switch 扩展并且有可用的 DeepSeek API Key。打开 CC Switch 的面板选择“新增供应商”。填写供应商名称比如deepseek-test。填入 API Base URL一般是https://api.deepseek.com这类地址具体以供应商文档为准。填入模型名称比如deepseek-chat或deepseek-coder不同版本的模型名可能不同。把 API Key 填入对应字段保存后切换到该供应商。在 VS Code 的 Agent 面板里随便发一句话测试是否正常响应。调用一个自定义 Skill看它是否按预期读取SKILL.md并执行步骤。我用同样方式配过 Qwen 和 GLMQwen 的优势是中文理解比较自然用来写注释、解释逻辑效果不错GLM 在复杂工具链的指令遵循上目前表现比较稳适合跑多步骤任务。DeepSeek 的性价比最高但偶尔会在长时间多步操作中“忘记”前面的约束条件所以我在 Skill 文件的边界条件部分会重复强调关键约束。3.3 各模型在代码场景的表现差异下面这张表是我个人在几个中型项目里的体感参数、环境、Prompt 都会影响结果仅供参考模型代码理解工具调用稳定性中文注释质量成本DeepSeek 系列好适合常见语言中等长任务需盯防良低通义 Qwen 系列良对中文项目友好中等优低智谱 GLM 系列良较好良中低Claude 官方模型优优良高如果你想减少试错我的建议是把“需要严格按 Skill 步骤执行”的任务比如自动化重构、批量改文件分配给指令遵循强的模型把“解释代码、写注释、查文档”这类灵活任务分配给成本更低的模型。4. 实战用 Skill 给一个 C/ESP-IDF 项目配“项目大脑”4.1 需求拆解这个场景为什么最值得做很多人对 Agent Skills 的反应是“好像很厉害但我用在哪里”。我觉得最典型的落地场景是嵌入式开发尤其是 ESP-IDF 这类依赖特定工具链、特定构建系统、特定目标芯片的项目。为什么因为这种项目有很多“项目专属知识”是模型不可能提前知道的项目基于哪个 ESP-IDF 版本必须用哪个版本的工具链。目标芯片是 ESP32-S3 还是 ESP32-C3影响可用的外设和内存布局。编译要用idf.py build烧录要用idf.py flash不能乱用 CMake 指令。有些代码是自动生成的手动改了下次会被覆盖必须避开。这些知识如果靠每次聊天时临时输入既啰嗦又容易漏。写成 Skill 后Agent 每次介入项目时都能自动查阅这才像真正的“项目大脑”。4.2 写一个 ESP-IDF 专用 Skill 的完整流程我给一个实际项目写的 Skill 目录大概是这样的esp32-app-skills/ idf-build-master/ SKILL.md references/ build-notes.md known-errors.md其中SKILL.md的内容我整理成了四个区域识别、构建、烧录、排错。下面是一个经过调整的简化版本# IDF Build Master Skill ## 适用场景 当用户提到编译、烧录、串口日志或者项目中出现 ESP-IDF 相关错误时调用本 Skill。 ## 项目识别 - 先确认 IDF 版本读取 managed_components 目录或运行 idf.py --version。 - 如果当前环境变量中没有 IDF 路径提示用户先执行 export IDF_PATH... 和 . $IDF_PATH/export.sh。 ## 构建步骤 1. 使用 idf.py set-target esp32s3 设置目标芯片以项目实际为准。 2. 执行 idf.py build 进行编译。 3. 若编译失败优先查看 build/log 下的输出并对照 references/known-errors.md 中的已知问题。 ## 烧录与监控 1. 执行 idf.py -p /dev/ttyUSB0 flash注意确认实际串口号。 2. 需要观察日志时使用 idf.py -p /dev/ttyUSB0 monitor。 ## 边界条件 - 绝不修改 managed_components/ 和 dependencies.lock 中的内容。 - 不运行 idf.py fullclean除非用户明确要求。 - 如果编译错误指向某个组件内部不擅自删除组件先报告完整错误信息。这个 Skill 写完之后我在实际项目里让小助手帮我排查过一次编译报错。它确实先读了known-errors.md发现是我把CONFIG_FREERTOS_HZ配错导致任务切换异常直接给出了修改建议而不是像以前那样拿着一行错误代码猜。这种体验差别用过的都知道。4.3 让 Skill 不“失忆”参考资料目录的维护技巧很多人把 Skill 写完之后就不管了结果项目迭代几个月后Skill 里的信息过时AI 给的建议反而变成误导。我现在的习惯是每两周主动更新一次 Skill 里的参考资料。具体做法就是把最常见的编译错误、奇怪的烧录问题、新加的组件注意事项追加到references/known-errors.md里。Agent 在调用 Skill 时会主动读取这个文件相当于项目自身的“经验库”在不断增长。这里有个小技巧在SKILL.md里明确写一行“处理报错前必须查阅references/known-errors.md”这能大大提升模型对参考资料的访问概率。否则有些模型会直接凭训练数据里的通用知识回答忽略你打包进去的项目经验。5. 我踩过的坑解释器版本、插件路径、工具误调用的完整排查链5.1 解释器与终端版本不一致AI 改了半天一跑就错这是我在 Python 项目里遇到最多的诡异问题。表现是VS Code 右下角显示的 Python 解释器是 3.11但打开终端一跑python --version却是 3.9或者根本不是同一个虚拟环境。用 Agent Skills 之后这个问题会被放大。因为 Agent 会根据项目配置选择解释器但它执行终端命令时用的可能是终端环境里的另一个 Python。于是出现“AI 修改了依赖声明结果安装到另一个版本的 Python 环境里”排查起来非常费劲。我的排查链路是这样的先看 VS Code 右下角解释器再打开终端执行python --version确认两者是否一致。在终端里执行which python和which python3检查是否有多套 Python 路径。查看项目根目录下的.vscode/settings.json确认有没有配置过python.defaultInterpreterPath。如果是虚拟环境执行source .venv/bin/activate后再启动 VS Code 的终端必要时新增一个终端 Profile 专门指定加载虚拟环境。一个比较稳妥的配置是在.vscode/settings.json里显式指定解释器路径{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/bin/python, python.terminal.activateEnvironment: true }这样终端和解释器就会尽量一致。若你用的不是虚拟环境也要保证系统只有一个默认 Python或者在 Skill 里写明“所有 Python 命令必须在激活项目环境后执行”。5.2 插件安装路径与扩展失效Agent 说找不到 Skill另一个让我头疼的问题是Skill 目录明明写好了Agent 却提示找不到。刚开始我以为是格式不对后来才发现是插件工作目录的问题。在 VS Code 里Agent 扩展默认会在用户目录或工作区目录找.claude/skills这类路径。你如果把 Skill 放到了别的插件目录或者工作区打开的是子文件夹Agent 的搜索范围就不对。我的解决方法是在项目根目录创建.claude/skills/把 Skill 放在里面而不是放在~/.config/之类的全局目录。确认 VS Code 打开的是包含.claude的顶层文件夹。如果你打开的是src/子目录Agent 可能从src/.claude里找自然找不到。在扩展设置里查看有没有自定义 Skills 路径的选项如果有把它指到你的 Skill 根目录。这个问题看起来很小但一旦发生你会觉得“Agent 完全没读到我的项目规范”其实只是路径错位。5.3 Agent “自作主张”执行危险命令时怎么加护栏Agent 再聪明也只是一套基于统计的模型。我在测试中遇到过它想执行rm -rf build来“清理缓存”的情况也遇到过它想直接覆盖一个自动生成的头文件。单靠模型的自控力是不够的必须在 Skill 层面加硬性护栏。我的做法是每个 Skill 都写“禁止操作清单”用短句、明确表达的负面约束。比如“禁止删除任何目录”“禁止修改自动生成的文件”。在 Agent 的配置里开启“执行破坏性命令前必须确认”的选项不同扩展名称不一样但一般都有类似开关。用 git 做兜底每次让 Agent 批量改文件之前先把当前分支备份一下或者要求它只创建 diff 而不是直接写文件。对于跨文件重构我会让它先用“计划模式”输出改动方案我再确认后才允许执行。一开始我觉得这些步骤很麻烦但吃过几次亏后就真香了。尤其是有一次它差点把测试用的 mock 数据文件全部“清理”掉幸好护栏拦截。记住Agent Skills 越强越要给它设置边界这和给新员工做权限管理一个道理。6. VS Code 和 PyCharm 的 AI 方案对比以及我现在的配置思路6.1 为什么我不再单纯依赖 PyCharm FittenPyCharm 里也有一些好用的 AI 插件比如 Fitten Code很多用惯了 JetBrains 系的人觉得它补全快、集成度高。但我的体感是Fitten 这类工具更适合“补全”和“单文件解释”。它不太擅长跨文件执行一个多步骤任务更不用说项目级的知识沉淀。PyCharm 本身对项目的理解很强但“项目理解”和“AI 可操作”是两码事。VS Code 配合 Agent Skills 后AI 不再只是像搜索引擎一样给出答案而是能真正读取项目规范、按流程修改文件、跑命令验证结果这种闭环在 PyCharm 里做起来没有那么顺手。如果你主要写 PythonPyCharm 的静态分析确实香但如果你的项目涉及多种语言、嵌入式工具链、CI 脚本或者你希望 AI 能按一套自定义流程干活VS Code Agent Skills 的灵活度会更高。6.2 我当前的整体配置清单最后分享一份我目前比较满意的 VS Code AI 配置不一定适合所有人但可以给你一个起点工作区结构 project-root/ .claude/ skills/ code-review/ # 代码审查 Skill unit-test-writer/ # 单元测试 Skill idf-build/ # 嵌入式构建 Skill .vscode/ settings.json # 解释器路径、终端环境、扩展配置扩展组合VS Code 官方市场下载 Claude Code 相关扩展提供 Agent 核心运行环境。CC Switch 做多模型切换默认用 DeepSeek 处理日常任务复杂重构切到 GLM 或官方模型。保留一个 Python 扩展用于解释器管理和调试但调试工作尽量交给 Agent 按 Skill 执行。如果写 C/C 或 ESP-IDFC/C 扩展和 ESP-IDF 扩展还是要有因为 Agent 需要它们提供的语言服务做跳转和诊断。配置好之后我的日常流程变成让 Agent 读一遍SKILL.md然后让它自己分析项目状态、提出改动方案、执行测试、汇总结果。我只需要在关键节点确认。这种感觉确实像给 VS Code 装了一个能记住项目历史的“AI 项目大脑”。我自己在反复配置和试用中最大的体会是Agent Skills 真正厉害的地方不是某个单点功能而是它能把你脑子里的项目经验“外置”成一个文件包让 AI 按照你的方式来干活。随着项目里积累的 Skill 越来越多AI 的产出质量会肉眼可见地提升。如果你也在 VS Code 里折腾 AI 工具我建议从一个小项目开始先写一个解决自己最痛问题的 Skill然后慢慢扩充。这比一开始就追求大而全的配置要实在得多。