(2026.01.18-02.01)🚀 好虫子周刊：DeepSeek V4前瞻、Agent标准确立、音频界面革命本周关键词： 混合专家 (MoE)、Agent 技能标准、物理 AI、音频首选 (Audio-first)摘要： 本周是开源界深度复盘与大厂战略转向的关键交汇期。DeepSeek R1 发布周年之际，官方以 86 页超长报告披露了 RL 训练核心机密，并预告 V4 版本将冲击 Claude 代码王座。与此同时，Anthropic 推动的 Agent Skills 规范逐渐成为行业事实标准，OpenAI 亦被传出转向“音频优先”硬件策略。整体趋势显示，AI 正在从“大参数”竞赛转向“高可靠性 Agent”和“低成本推理”的务实阶段。🚨 核心头条 (Top Stories)1. DeepSeek R1 报告更新与 V4 预告：开源界的透明化巅峰发布时间： 01.20核心亮点： DeepSeek 将 R1 技术报告扩展至 86 页，完整披露了从 Dev1 到 Dev3 的三阶段强化学习（RL）路径。同时预告 V4 版本将于 2 月中旬发布。技术突破： 详细记录了 MCTS（蒙特卡洛树搜索）在训练中的失败经验，证明了纯 RL 训练即可实现推理能力涌现。V4 将采用更优化的 MoE 架构，侧重软件工程能力。开源/行业价值： 为全球开发者节省了数亿元的验证算力，奠定了中国开源模型在 Hugging Face 社区的领导地位。2. Agent Skills 规范确立：智能体从“玩具”走向“工具”发布时间： 01.26核心亮点： Anthropic 官方开放 Agent Skills 规范。Moltbot（原 Clawdbot）在 GitHub 狂揽 10 万 Star，成为增长最快的 AI 助手项目。技术突破： 通过 MCP（Model Context Protocol）将智能体与真实系统连接摩擦降至最低。引入自验证机制，解决了复杂任务下 Agent 频繁遗忘上下文的痛点。开源/行业价值： 标志着 Agent 开发从碎片化走向标准化，开发者可复用 Vercel 或 Anthropic 提供的技能模块，加速企业级智能体部署。3. 音频界面革命：OpenAI 战略重心向“声音”偏移发布时间： 01.30核心亮点： 社区情报显示 OpenAI 计划在 Q1 发布新一代非 Transformer 架构的音频模型，并与 Jony Ive 合作开发“音频优先”个人设备。技术突破： 实现真·端到端语音交互，摆脱传统的“语音转文字”中转，延迟大幅降低，支持更细腻的情感表达。开源/行业价值： 预示着 AI 交互将从屏幕端（Screen-based）转向环境音端（Ambient Audio），为可穿戴设备和智能家居开辟新赛道。🛠️ GitHub 热门开源项目 (Trending Tools)本周 GitHub Star 增长最快、开发者关注度最高的项目精选⚡ Moltbot一句话介绍： 自托管的“最强 AI 智能助手”，GitHub 增长奇迹。核心价值： 支持集成 Slack/Discord/Telegram，具备系统级操作权限，重点在于数据完全本地化处理，解决了企业对闭环 AI 的核心焦虑。项目地址： moltbot/moltbot🤖 OpenClaw一句话介绍： 专注解决 Agent 稳定性的开源框架。核心价值： 针对长流程任务进行了“反馈闭环”优化，大幅降低了智能体在多步推理中的出错率（Hallucination Rate）。项目地址： pipecat-ai/nemotron-january-2026 (NVIDIA 驱动版)🎨 HunyuanVideo 1.5一句话介绍： 腾讯开源的“显卡救星”视频生成模型。核心价值： 仅需 13.6GB 显存即可运行 720p 视频生成，通过 SSTA 稀疏注意力技术实现了 1.87 倍的生成提速。项目地址： Tencent/HunyuanVideo📑 前沿研究与行业风向 (Insights)物理 AI (Physical AI) 与世界模型： 随着 Boston Dynamics 展示全电动 Atlas 机器人的 RL 训练成果，学术界开始转向“物理层面的智能定义”。LeCun 的 World Model 实验室获得 50 亿美元估值，标志着 AI 正在尝试理解物理世界的逻辑而非单纯的概率拟合。算力能源瓶颈： 马斯克在达沃斯论坛再次预警：电力供应将成为 2026 年 AI 扩张的最大红利障碍。Vistra 等电力巨头通过收购天然气电厂直接对接 AI 数据中心，能源溢价正在重塑 AI 供应链。✍️ 编辑结语： 本周我们看到了 AI 领域从“堆参数”到“堆逻辑”的结构性转变。开源社区不再盲目跟风，而是通过透明的技术报告和标准化的接口（如 MCP）构建护城河。下周，请密切关注 DeepSeek V4 的定档消息，这可能彻底重写 2026 年的 Coding Agent 竞争格局。整理：好虫子周刊编辑部 数据来源：GitHub, arXiv, Hugging Face等本文由mdnice多平台发布
Claude Code 支持重磅扩展 Skills —— 用最新 API 构建更靠谱的 AI 项目
在上一篇《Claude Code × 智谱 BigModel 实战集成指南》中，我们已经完成了一次完整的项目实战。项目可以正常运行，但在后续代码 Review 时，一个问题逐渐暴露出来：生成的代码虽然能跑，但大量 API 和用法已经过时，与最新官方文档存在明显偏差。这在 AI 辅助开发中其实非常常见——模型的训练数据更新速度，往往赶不上框架和 SDK 的迭代速度。正巧这时，一位朋友向我推荐了 Anthropic 最新发布的 Agent Skills，通过 plugins 的方式，让 Claude 在生成代码时 动态读取最新官方文档和工具能力，从而显著降低“写得像，但跑不通”的概率。本文就是这次探索的完整记录。一、Agent Skills 是什么？官方仓库地址：https://github.com/anthropics/skillsAgent Skills 可以理解为：一套可插拔的“能力模块”，用于教会 Claude 如何用正确的方法、最新的工具、可重复的流程 来完成特定任务。在技术层面上：每个 Skill 本质上是一个文件夹内部包含：指令（instructions）脚本（scripts）资源文件（resources）Claude Code 会在运行时动态加载这些 Skills它能解决什么问题？Agent Skills 的核心价值在于 “降低幻觉 + 提高一致性”，典型应用场景包括：按公司/团队的编码规范生成代码按最新官方文档调用 API（而不是靠模型记忆）执行固定的工程化流程（初始化项目、生成目录结构、部署脚本等）自动化个人或组织级任务简单来说：Skills 不是让模型更聪明，而是让模型更“守规矩”。二、在 Claude Code 中安装 Agent Skills在 Claude Code 命令行中执行：/plugin marketplace add anthropics/skills安装完成后，你就已经具备了使用官方 Skills 的能力。这一步相当于为 Claude Code 打开了“官方增强模式”。三、安装 context7 插件（关键步骤）接下来是本文的重点：context7。1️⃣ 打开插件管理在 Claude Code 中输入：/plugins然后使用键盘 ➡️ 进入 Discover。2️⃣ 搜索并安装 context7在搜索框中输入 context7，完成安装。context7 本质上是一个 MCP（Model Context Protocol）插件，能让 Claude 直接参考并对齐最新的官方文档内容。四、使用 context7 生成项目代码安装完成后，就可以在 Prompt 中显式声明使用 context7。示例 Prompt--- name: context7 description: 使用 Context7，基于框架最新的官方文档 --- # context7 ## 指南 已使用以下技术栈生成企业级项目： - 使用 Context7，基于最新的官方文档 - FastAPI 0.128.0，带 Token 认证 - 使用 sqlite 生成 token - 不使用 JWT，仅做 Token 校验 - langchain 1.2.6，使用 create_agent - langchain-ollama 1.0.1 - model：qwen3-vl:32b - embedding：qwen3-embedding:8b - langgraph 1.0.6 - Milvus（pymilvus）2.6.6 - langfuse 3.12.0通过这种方式，你是在明确告诉 Claude：不要靠“印象”写代码，而是以当前官方文档为准。五、实际体验与问题分析真实结论只有一句话：效果明显提升，但依然不能“一次生成直接可用”。优点API 使用明显更接近最新文档过时参数、废弃方法显著减少工程结构更合理，思路更偏向“真实项目”仍然存在的问题复杂技术栈组合（LangChain + LangGraph + Milvus + Langfuse）仍然需要 多轮调试才能完全跑通某些边界用法依然存在偏差我的判断并不是 context7 不行，而是模型生成速度，依然落后于框架演进速度。context7 做到的是：让 Claude 看得到 最新文档但最终“怎么拼起来”，仍然依赖模型本身的推理与代码能力六、总结如果你正在使用 Claude Code 做偏工程化、偏企业级的项目开发，我的建议是：✅ 一定要上 Agent Skills✅ 能用 context7 就用 context7❌ 不要再完全相信“模型记忆里的 API”但同时也要有一个清醒认知：AI 辅助开发 = 更快的起点，而不是免调试的终点。在当前阶段，最理想的模式依然是：AI 生成 + 人类 Review + 多轮修正后续我也会继续记录 Claude Code + MCP + 多模型协作 的实践经验，欢迎关注。
大家好，我是李琼羽，我没啥拿得出手的 title ，所以就不做这方面的介绍了。另外，本文不过多介绍 skills 是什么，也不教怎么使用，也不会推销 “好用的 skills”，如果对这些有期待，本文可能不适合。零、引言把 agent 放进真实工作里，很快会发现它最常卡住的不是“不会思考”，而是“没在这个组织里做过事”。同样一份报告，你们团队默认的结构、口径、审阅点；同样一次上线，哪些检查是硬规则、哪些是踩过坑才知道的优先级；同样一次对外沟通，哪些信息永远不能外发、哪些措辞必须保留——这些东西通常不在公开知识里，也不在模型参数里，而是活在组织的惯例、清单、事故复盘、师徒传承里。Anthropic 在工程文章里提出的 Agent Skills ，切中的就是这类“怎么做事”的经验：把实践性的、程序性的知识（ procedural knowledge ）封装成一组 agent 可动态发现与按需加载的“文件夹化能力包”，里面可以包含指令、脚本与资源；并且他们直白地类比：写一个 skill 很像给新员工写 onboarding guide——把做事方法捕获、打包、共享，让通用 agent 变成适配具体场景的专门化 agent 。当这套机制在 2025 年底被发布为开放标准并强调跨平台可移植时，它就不再只是某个产品的“提示词技巧”，而是开始变成一种更接近基础设施的形态：经验被对象化、可分发、可组合、可审计。然而，这个转变，本身就是哲学问题。一、Skills 的“技术轮廓”，及其哲学问题一个 skill 最朴素的形态是一个目录，核心文件是 SKILL.md。它必须以 YAML frontmatter 开头，至少包含 name、description； agent 启动时会把每个已安装 skill 的 name/description 预加载进 system prompt ；当判断相关时，再把完整 SKILL.md 正文读入上下文。这套机制的关键词是 progressive disclosure：先加载极小的“目录级线索”，再按需加载正文与引用文件；当 skill 变复杂，可以把更细的内容拆到额外文件，由 agent 在需要时再去读。Anthropic 甚至把它写成一种“手册式分层”：目录（元信息）—章节（ SKILL.md ）—附录（ references/assets/scripts ）。在有文件系统与代码执行能力的 agent 上，技能目录里可捆绑的上下文“几乎无上限”，因为并不需要把所有内容一次性塞进上下文窗口，真正需要时再读取、再执行。但把边界说清楚也同样重要：在当前实现语境里，skills 的“注入”主要是中性工程意义的——把外部文件内容拼接进系统提示与上下文以影响推理与计划；它并不天然负责工具协议、通信、权限治理。开放规范里出现 allowed-tools 字段，恰恰说明了这一点：它更像“权限声明/预批准清单”的雏形，并被标注为 Experimental ，且明确写着“支持程度因实现而异”。也就是说，是否强制执行、如何执行，仍主要由宿主 runtime/产品层决定。到这里为止，skills 看起来像更系统化的 prompt 工程。但它真正有趣的地方在于：它把“经验”变成了可保存、可分发、可调用、可审计的对象；而且这种对象还天然带有目录结构、版本元信息、可选脚本与资源——它已经很像一种“可维护的知识工件”，而不是一次性对话。（不同实现可能会有的信息也略有不同，以后的迭代中可能也会加入更多信息，所以，细节不重要）二、从 know-how 到“可调用的记忆”，Skills 把经验外置成一种可移植的组织“小脑”skills 在工程上解决的是“怎么做”的问题，而哲学里对“会做”这类知识有一条经典区分：know-how 与 know-that 。Ryle 传统里，know-how 并不等价于“掌握一堆命题”，更不是先在脑内默背规则再执行；恰恰相反，很多情形里“会做”在逻辑上反而先于“会说”。Anthropic 对 Agent Skills 的定位（ onboarding guide 式的 procedural knowledge 封装）几乎是对这条区分的工程化回应：把组织里的 know-how 尽可能变成 agent 可读、可执行、可复用的形式。但这里立刻会碰到另一条更尖锐的边界：Polanyi 说“我们知道的多于我们能说出的”。也就是说，许多实践能力带着默会性：能做，却很难完整说清规则。skills 的现实策略并不是“消灭默会知识”，而更像一种切片：把能写下来的部分（流程、模板、禁区、常见坑、例外处理）固化为手册与清单；把不易言说但又关键的部分，留给模型的情境推理与人类的复核机制去兜底。这个切片是否切得好，决定了 skills 的价值上限。把视角再往外推一步，会看到 skills 与 Bernard Stiegler 讨论的“技术性记忆”之间有一种意外的贴合：人的记忆与主体性并不只发生在大脑里，还会被技术媒介外置与塑形（ tertiary retention / technical memory ）。skills 的哲学意味正在这里：它把组织经验做成一种可移植的外部记忆环境。经验不再只住在“某个老员工的脑子里”或“某次复盘会议的氛围里”，而是被写成目录、Markdown 、脚本、引用资料——一种可以安装、更新、复用的记忆模块。这也解释了一个常被低估但很实用的点：skills 虽然主要给 agent 用，但它天然也是“给人学”的。因为它的写作形态从一开始就被定义成 onboarding guide 。写得好的 SKILL.md，本质上是一份高质量的经验教材：把关键不变量、关键步骤、关键风险、常见坑与例外处理压缩成可读结构，让“做对”变得更可重复。这种“把经验写成清单/手册”的价值，在人类世界早就被反复验证。以外科安全清单为例，WHO 在新闻稿中总结：引入 checklist 后，重大并发症从 11% 降到 7%，住院死亡从 1.5% 降到 0.8%（这组数据来自多中心研究与其后续传播材料）。这并不是让医生更聪明，而是在复杂系统里减少“明明知道却没做到”的错误。skills 对 agent （以及对新人）的作用，也非常接近这一点：把容易忘、容易省、容易误解的经验固定成外部记忆，让执行更可靠。三、写下规则不等于会用规则，维特根斯坦式的提醒skills 大量内容是规则与流程，但维特根斯坦传统的 rule-following 讨论提醒我们：规则并不自动携带其应用方式；同一条规则永远可能被不同地解释，而“遵循规则”最终依赖共同体的用法与实践语境。把这点放回 skills ，会得到一个极其工程化的结论：降低误用的关键，不是把步骤写得更长，而是把“用法边界”写得更硬。Agent Skills 的开放规范几乎是在把这条哲学翻译成写作建议：正文推荐包含 step-by-step instructions 、inputs/outputs examples 、common edge cases ，并提醒正文会在激活时整体加载，太长就拆到 references 。从这里往前推一小步，就很自然了：当 skills 规模化，examples/counterexamples 会越来越像“单元测试”；边界情况与失败模式会越来越像“回归用例”。一个成熟的 skill 体系会逐渐长出这些东西：写作上，它不再是“说明书”，而是“带样例的可执行契约”：输入是什么、输出是什么、什么情况下必须停下、什么情况下必须升级、什么情况下宁可慢也不能赌。运维上，它不再是“放在那儿的文件夹”，而会被监控：触发率、成功率、失败原因的聚类、常见误触发路径、回滚策略——像监控 API 一样监控 skill 。哲学上，这意味着规则不再被当作“意义的来源”，而是被当作“行动的边界装置”：它不保证正确，但它把错误收敛到可见、可修、可复盘的范围内。四、technê 能被手册化，phronêsis 不能亚里士多德区分 technê（可重复的技艺/制作之知）与 phronêsis （实践智慧）。在 Aristotle 的伦理学讨论里，一个关键判断是：practical wisdom 不能仅靠学习一般规则获得，还需要通过实践形成“在每个场景里看见什么选择更好”的能力。这句话几乎就是 skills 的哲学上限：skills 非常擅长固化 technê——流程、模板、清单、工具用法；但它不可能把 phronêsis 完整写成规则。成熟的 skills 体系反而应该承认这一点，并把最昂贵的经验写在“判断点”上： 什么时候必须停下来问人（例如合规、隐私、对外口径、不可逆变更）。 什么时候必须升级（例如影响面超过阈值、跨团队协调、风险等级提升）。 什么时候宁可慢也不能赌（例如资金、生产、法律与安全相关动作）。 也因此，“更高级的 skill”往往不是更长的 SOP ，而是更清晰的停机点与升级条件——把判断空间留出来，让流程为实践智慧服务，而不是让行动变成盲目执行。五、当经验可分发、可触发，Skills 更需要治理当 skills 进入组织化使用场景，它不只是知识传播，也在规定什么叫“正确做法”。福柯讨论 modern power 时强调 governmentality （治理理性）以及规范、技术与程序在现代世界中的作用：治理不只是命令，更是通过细密机制塑形行动。skills 的“规范化”能力越强，它就越像一种微观治理装置：把“组织认为应该怎样做事”固化成默认路径，让偏离变得显眼、甚至变得困难。这种治理面向，最直观地体现在安全与供应链上。Anthropic 在安全注意事项里明确警告：恶意 skills 可能引导数据外泄或执行非预期动作，因此建议只安装可信来源；对不那么可信的来源要先审计内容与代码依赖，留意外部网络连接指令。当 skills 能捆绑脚本、能引导工具调用时，风险会从“写错提示词”升级为“能力供应链风险”。而规范里的 allowed-tools 恰好像一个 manifest 的雏形：声明该 skill 预批准可用哪些工具，但是否强制执行取决于实现。换句话说：skills 的规模化，必然呼唤更厚的治理外壳——权限最小化、审计、签名、发布分级、回滚机制、可追溯变更记录——这些不会是“锦上添花”，而会成为系统能否被放心使用的底座。也正是在这里，“技能写得好不好”不再只是写作问题，而是组织治理能力的一部分：谁能发布、谁能审核、谁能启用、出了事故怎么追责、怎么回滚，这些都会被 skills 的形态逼出来。六、Skills 、/prompts、slash commands ，从“个人快捷键”到“组织经验资产”把对比说清楚并不复杂：一类是显式调用的宏命令，一类是可发现、可按需加载的经验包。OpenAI Codex 的 Custom Prompts 属于前者：把 Markdown 文件变成 slash command ，但需要显式调用；并且默认存放在本地（例如 ~/.codex），不随仓库共享。官方文档甚至直接写明：如果想共享 prompt ，或想让 Codex 隐式调用它，就用 skills 。Claude Code 的 custom slash commands 也几乎同构：把常用 prompts 存成 Markdown 文件，按项目/个人 scope 组织，项目命令放在 .claude/commands/，用 /<command-name> [arguments] 显式调用。skills 属于后者：在 Codex 的技能文档里，skill 被定义为以 SKILL.md 捕获能力的目录，并允许包含 scripts/resources/assets ；它同样强调 progressive disclosure ，并明确给出显式调用与隐式调用两种激活方式（例如显式用 /skills 选择，或由系统根据任务匹配自动触发）。同时，Codex 还引入了 scope 与覆盖优先级：同名 skill 会由高优先级 scope 覆盖低优先级 scope 。从哲学角度看，这不是“功能差异”而已，而是对象性质不同：宏命令更像个人技巧（自己用得顺手即可）； skills 更像组织经验资产——可传承、可治理、可争论、可回滚。它把“做事方式”从人的习惯变成了可以进入工程体系的工件。七、面向未来：当 Skills 变得越来越像 AI 时代的 package如果要给读者一个更抓手的想象，我个人倾向，skills 的未来很可能会接近软件世界的 package：可安装、可版本化、可依赖管理、可维护、可审计——它不是一句提示词，而是一套可以分发与演进的能力单元。这个类比之所以成立，是因为 skills 从形态上就已经像 package：有明确的目录边界，有入口文件（SKILL.md），有元信息（ license/compatibility/metadata/version 等字段），还能捆绑脚本与资源。当然，类比永远不是同构：软件 package 的接口由编译器/解释器严格执行； skills 的接口仍很大程度由自然语言驱动、由模型解释，确定性更多来自“脚本化的那部分”以及 runtime 的权限与验证机制。正因为不完全等价，这个类比才真正有用：它提醒我们未来的增量会落在哪些“工程刚需”上。第一层会出现的，是更标准化的分发与装配，而不是手工复制文件夹。既然 Agent Skills 已被作为开放标准强调跨平台可移植，生态成熟后就会自然走向“安装、升级、锁版本、回滚、禁用”的体验。第二层会更强调版本、兼容性与依赖。规范已经给出 compatibility 与 metadata/version 等字段，也建议脚本自包含或清晰声明依赖；当组织工作流天然是组合式的，这些字段会从“可选信息”变成“默认要求”。更进一步，会出现“skills 依赖 skills”的显式关系：一个高层 skill 负责编排，一个基础 skill 专注于某个环节（读数仓、做图、生成文档、审校口径），形成稳定的能力图谱。第三层会把“写作建议”推到“可验证能力”。规范推荐 examples 与 edge cases ；当 skills 成为组织依赖，最值钱的是可预期性：发布前跑最小回归样例，升级后再跑一遍；线上记录失败模式，形成迭代闭环。第四层会让权限与副作用声明从“软建议”走向“硬机制”。allowed-tools 像 manifest 的雏形，而 Anthropic 的安全警告则说明了供给链风险的现实性；当 skills 生态繁荣，“信任”会从人际关系迁移到机制：签名、审核、分级发布、最小权限、沙箱、审计追踪。这一步完成后，skills 才会真正成为“敢让 agent 自动化执行”的基础设施。第五层会让“给人学习”从副产品变成目的之一。因为 skills 的写作形态本来就是 onboarding guide ，它天然会反哺组织培训：新人学 skills ，就是在学组织的做事方式；老员工改 skills ，就是在把经验显式化并固化进组织记忆。最后留一个反方向的提醒：海德格尔谈 Gestell （ enframing ）时指出，技术时代会把世界越来越多地框定为“可调度资源”，从而压扁意义与语境。skills 的 package 化会强烈推动工作流脚本化与模块化：可靠性上升、效率上升，但也可能把“可辩护的判断”误写成“可执行的默认”。一个成熟的 skills 生态，应该主动为 phronêsis 留空间：在关键处强制慢下来、要求解释理由、要求二次确认，让“可执行”不吞掉“可辩护”。结语如果只把 skills 当作“又一种 prompt 工程”，它确实没那么值得写。但把它当作一种把经验外置成可调用记忆的装置——能被分发、能被组合、能被审计、还能反过来教育人——它的哲学含义就清晰起来了：skills 不是在给模型加聪明，而是在改变经验如何存在、如何传承、如何进入行动，并最终如何塑形组织。参考资料 Anthropic 工程博客：Equipping agents for the real world with Agent Skills （含 progressive disclosure 、onboarding guide 类比、安全提示、未来方向） Agent Skills 开放规范（ SKILL.md 格式、recommended sections 、optional dirs 、allowed-tools 、progressive disclosure ） OpenAI Codex：Agent Skills 文档（显式/隐式调用、scope 覆盖优先级、目录结构） OpenAI Codex：Custom Prompts （显式调用、本地目录、不随 repo 分享；与 skills 的对照） Claude Code：Slash commands （自定义命令、项目/个人 scope 、.claude/commands/） Stiegler 与 tertiary retention （技术性记忆外置） WHO 与外科安全清单数据总结 Haynes 等（ 2009 ）外科安全清单研究摘要/论文入口 维特根斯坦“规则遵循”讨论（ SEP ） Aristotle 实践智慧 phronêsis （ SEP ） Foucault 与 governmentality （ SEP ） Heidegger 与 Gestell / enframing （ SEP ） Ryle：knowing-how / knowing-that （ SEP ） Polanyi：Tacit Dimension （“we can know more than we can tell”） [推荐阅读清单] 1. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills 2. https://agentskills.io/specification 3. https://developers.openai.com/codex/skills/ 4. https://developers.openai.com/codex/custom-prompts/ 5. https://code.claude.com/docs/en/slash-commands 6. https://pmc.ncbi.nlm.nih.gov/articles/PMC7903928/ 7. https://www.who.int/news/item/11-12-2010-checklist-helps-reduce-surgical-complications-deaths 8. https://pubmed.ncbi.nlm.nih.gov/19144931/ 9. https://plato.stanford.edu/entries/rule-following/ 10. https://plato.stanford.edu/entries/aristotle-ethics/ 11. https://plato.stanford.edu/entries/foucault/ 12. https://plato.stanford.edu/entries/heidegger/ 13. https://plato.stanford.edu/entries/ryle/knowing-how.html 14. https://plato.stanford.edu/entries/knowledge-how/ 15. https://press.uchicago.edu/ucp/books/book/chicago/T/bo6035368.html
Agent Skills 落地实战：拒绝“裸奔”，构建确定性与灵活性共存的混合架构
摘要随着 Anthropic 开源 skills 仓库，"Code Interpreter"（代码解释器）模式成为 Agent 开发的热门方向。许多开发者试图采取激进路线：赋予 LLM 联网和 Python 执行权限，让其现场编写代码来解决一切问题。但在构建企业级“智能文档分析 Agent”的实践中，我们发现这种“全托管”模式在稳定性、安全性和可控性上存在巨大隐患。本文将分享我们如何摒弃激进路线，采用 Java (确定性 ETL) + DSL 封装式 Skills + 实时渲染 的混合架构，在保留 LLM 灵活性的同时，确保系统的工业级稳定性。一、 背景：当文档分析遇到“复杂生成”在我们的“文档处理 Agent”项目中，基础的问答功能（RAG）已经解决得很好。但随着用户需求升级，我们面临了新的挑战：用户场景：“这是 2024 和 2025 年的两份经营数据报表，请对比 DAU 和营收的同比增长率，并生成一个 Excel 表格给我。另外，把总结报告导出为 PDF。”这类需求包含两个特征：逻辑计算：需要精确算术（LLM 弱项）。文件 IO：需要生成物理文件（LLM 无法直接做到）。引入 Skills（让 LLM 调用 Python 代码）似乎是唯一解。但在具体落地时，我们走了一段弯路。二、 弯路：激进的“纯 Skills”路线起初，我们参考了开源社区做法，采用了 完全的 Code Interpreter 模式。我们将 requests、pandas、reportlab 等库的权限全部开放给 LLM，并在 Prompt 中告诉它：“你是一个 Python 专家，请自己写代码解决所有问题。”这种“裸奔”模式在生产环境中遭遇了三次暴击：输入端不可控：LLM 对非结构化数据（如无后缀 URL、加密 PDF）的处理极其脆弱，经常陷入报错死循环。输出端崩坏：让 LLM 从零绘制 PDF/Word 是灾难。经常出现中文乱码、表格对不齐、使用了过期的库 API 等问题。安全黑洞：数据流完全在沙箱内闭环，Java 主程序失去了对内容的控制权，无法拦截敏感词或违规数据。三、 变革：Java 主控 + DSL Skills 的混合架构为了解决上述问题，我们重构了架构。核心思想是：收回 LLM 的“底层操作权”，只保留其“逻辑调度权”。我们制定了新的架构分工：Java 负责确定性的数据流转与安检，LLM 负责意图理解与代码组装，Python 沙箱 负责在受控环境下执行具体计算。3.1 架构设计概览我们将系统重新划分为四个逻辑层级：ETL 层 (Java)：负责下载、MIME 识别、OCR、敏感词检测。这是“确定性管道”。Brain 层 (LLM)：负责阅读纯文本，进行逻辑推理，并生成调用代码。Skills 层 (Python Sandbox)：提供高度封装的 SDK（DSL），而非裸库。Delivery 层 (Java)：负责将 Markdown/HTML 实时渲染为 PDF/Word。3.2 输入侧：回归 Java 流水线 (ETL)我们不再让 LLM 去下载和解析文件。所有输入文件，先经过 Java 的 DocPipeline。利用 Apache Tika 进行精准解析，并立即进行敏感词检测和文本截断。这一步保证了喂给 LLM 的数据是干净、安全、标准化的纯文本。3.3 中间层：DSL 封装模式 (The Wrapper Pattern)这是我们对 Skills 实践最大的改进。我们禁止 LLM 直接写 import pandas 进行底层操作，而是预置了一套高度封装的 DSL。Python 端封装 (excel_tool.py)：import pandas as pdimport osdef create_excel(data_list, filename="report.xlsx", output_dir="/workspace"): try: df = pd.DataFrame(data_list) save_path = os.path.join(output_dir, filename) # 【封装价值体现】自动处理格式、列宽、引擎兼容性，屏蔽 LLM 的幻觉风险 with pd.ExcelWriter(save_path, engine='openpyxl') as writer: df.to_excel(writer, index=False, sheet_name='Sheet1') # 自动调整列宽 (LLM 很难写对的工程细节) worksheet = writer.sheets['Sheet1'] for idx, col in enumerate(df.columns): max_len = max(df[col].astype(str).map(len).max(), len(str(col))) + 2 worksheet.column_dimensions[chr(65 + idx)].width = min(max_len, 50) return save_path except Exception as e: return f"Error: {str(e)}"复制代码Skill 说明书 (SKILL.md)：我们在 Prompt 中通过“接口契约”强行约束 LLM 的行为，明确了何时该写代码，何时该纯输出文本。# File Generation Skill (Standardized)你拥有生成专业格式文件（Excel, Word, PDF）的能力。沙箱中已预装了封装好的 `excel_tool` 库。**核心决策树**：1. 如果是 **统计数据/表格** -> 必须生成 **Excel** -> **写 Python 代码**。2. 如果是 **分析报告/文档** -> 必须生成 **Word/PDF** -> **禁止写代码**，走渲染路径。---### 场景 1：生成 Excel (.xlsx)**规则**：禁止使用 `pandas` 底层 API，必须调用封装函数。**数据结构**：必须是【字典列表】，每个字典代表一行。**Python 调用示例**：```pythonimport excel_tool# 1. 准备数据 (从文档中提取)data = [ {'年份': '2024', 'DAU': 1000, '营收': '500万'}, {'年份': '2025', 'DAU': 1500, '营收': '800万'}]# 2. 调用封装函数 (自动处理样式、列宽)excel_tool.create_excel(data, filename='analysis.xlsx')```---### 场景 2：生成 Word / PDF (.docx / .pdf)**规则**：**严禁编写 Python 代码**（如 `reportlab` 或 `python-docx`）。**执行动作**：1. 请直接输出内容丰富、排版精美的 **Markdown** 文本。2. 在 Markdown 的**最后一行**，务必添加对应的动作标签，系统会自动将其渲染为文件。**输出示例**：# 2024 年度经营分析报告## 一、 数据概览本季度营收同比增长 20%...| 指标 | Q1 | Q2 || :--- | :--- | :--- || DAU | 100w | 120w |...(此处省略 2000 字内容) ...<<<ACTION:CONVERT|pdf>>>复制代码3.4 输出侧：渲染与交付的分离对于不同类型的文件，我们采取了截然不同的交付策略：Excel（强结构化）：走 Skills 路线。LLM 组装数据 -> 调用 excel_tool -> 沙箱生成物理文件。Word/PDF（富文本）：走 渲染路线。严禁 LLM 写代码生成。LLM 只输出高质量的 Markdown 并在末尾打上 <<>> 标签。Java 后端拦截该标签，利用 OpenHTMLtoPDF 或 Pandoc 将 Markdown 实时转换 为精美的 PDF/Word。四、 硬核代码实现 (Spring AI)以下是我们在 Spring AI 体系下实现这套混合架构的关键逻辑。4.1 动态技能注入 (SkillManager)我们实现了一个 SkillManager，支持按需加载技能。为了提升性能，我们设计了 Session 级的“防抖机制”，确保同一个会话中只需上传一次 Python 脚本，避免重复 IO。@Servicepublic class SkillManager{ // 缓存技能脚本: 技能名 -> { 文件路径 -> 内容 } private final Map<String, Map<String, String>> skillScripts = new ConcurrentHashMap<>(); // 防止重复注入的防抖 Set private final Set<String> injectedSessions = ConcurrentHashMap.newKeySet(); /** * 核心逻辑：根据需要的技能列表，动态注入脚本到沙箱 */ public void injectToSandbox(String sessionId, List<String> neededSkills) { // 1. 防抖检查：如果该 Session 已注入，直接跳过，避免重复 IO if (injectedSessions.contains(sessionId)) return; // 2. 注入 Python 包结构 (__init__.py) sandboxService.uploadFile(sessionId, "/workspace/skills/__init__.py", ""); // 3. 批量上传该技能所需的 DSL 脚本 for (String skillName : neededSkills) { Map<String, String> scripts = skillScripts.get(skillName); if (scripts != null) { scripts.forEach((path, content) -> sandboxService.uploadFile(sessionId, path, content) ); } } injectedSessions.add(sessionId); } // ... 省略加载 Resource 的代码 ...}复制代码4.2 业务调度与意图分流 (Handler)串联 Java ETL、LLM 推理和最终的交付分流。@Servicepublic class DocumentAnalysisRequestHandler{ public Flowable<Response> processStreamingRequest(Request req) { // 1. 【Java ETL】确定性解析与安检 // 无论 URL 还是文件，先转为纯文本，并做敏感词过滤 List<ParseResult> parsedDocs = etlPipeline.process(req.getUrls()); // 2. 【技能注入】 List<String> neededSkills = List.of("file_generation"); skillManager.injectToSandbox(req.getSessionId(), neededSkills); // 3. 【LLM 执行】Context Stuffing String prompt = buildPrompt(parsedDocs, skillManager.getPrompts(neededSkills)); // 调用 LLM，挂载 ToolContext 以实现多租户隔离 Flowable<AgentOutput> agentFlow = chatClient.prompt() .system(prompt) .user(req.getUserInstruction()) .toolContext(Map.of("projectId", req.getSessionId())) .stream() .content(); // 4. 【结果分流】 return agentFlow .toList() // 收集完整回复 .flatMap(this::handlePostGenerationAction); } /** * 核心分流逻辑：决定是返回沙箱文件(Excel) 还是 调用Java渲染(PDF) */ private Single<AgentOutput> handlePostGenerationAction(List<String> rawChunks) { String text = String.join("", rawChunks); // 分支 A：检测到 Python 生成了 Excel (Skills 产物) // 格式：[FILE_GENERATED: /workspace/report.xlsx] if (FILE_GENERATED_PATTERN.matcher(text).find()) { String path = extractPath(text); return Single.just(new AgentOutput(path, OutputType.FILE)); } // 分支 B：检测到转换指令 (渲染产物) // 格式：<<<ACTION:CONVERT|pdf>>> if (text.contains("<<<ACTION:CONVERT|pdf>>>")) { // Java 侧实时渲染：Markdown -> PDF // 优势：完美控制字体和样式，避免 Python 生成乱码 String pdfPath = docConverterService.convertAndSave(text, "pdf"); return Single.just(new AgentOutput(pdfPath, OutputType.FILE)); } // 分支 C：普通文本 return Single.just(new AgentOutput(text, OutputType.TEXT)); }}复制代码4.3 拦截与交付 (SandboxTools)在 Tool 执行层做最后一道防线：输出内容的二次安检。@Componentpublic class SandboxTools{ @Tool(name = "execute_command", description = "在沙箱中执行 Shell 命令") public String executeCommand(ExecuteCommandRequest req, ToolContext context) { String projectId = (String) context.getContext().get("projectId"); try { // 1. 执行 Python 脚本 Map<String, Object> result = sandboxMcpService.executeCommand(projectId, req.command()); String stdout = (String) result.get("stdout"); // 2. 【关键】输出侧安检 // 防止 LLM 通过代码计算出违规内容，绕过输入侧检查 if (banwordService.hasBanWords(stdout)) { log.warn("Banword detected in sandbox output!"); throw new BanwordException("敏感内容阻断"); } // 3. 超长截断 (防止 LLM 上下文爆炸) if (stdout.length() > MAX_TEXT_LENGTH) { return stdout.substring(0, MAX_TEXT_LENGTH) + "\n[SYSTEM: TRUNCATED]"; } return stdout; } catch (Exception e) { return "Execution Error: " + e.getMessage(); } }}复制代码五、 总结Skills 技术让 LLM 拥有了“手”，但这双手必须戴上“手套”。通过这次架构演进，我们得出的核心经验是：不要高估 LLM 的 Coding 能力：它是一个优秀的逻辑推理引擎，但在工程细节（排版、库依赖、环境配置）上非常糟糕。DSL 封装是必须的。不要丢掉 Java 的确定性：解析、下载、格式转换、安全检查，这些传统代码擅长的领域，不要交给概率性的 LLM 去做。架构分层：Input: Java (Standardization & Security)Thinking: LLM (Reasoning)Action: Python (Calculation via DSL)Output: Java (Rendering & Delivery)这种混合架构，既保留了 Agent 处理复杂动态需求的能力（如自定义计算涨跌幅），又守住了企业级应用对稳定性与合规性的底线。
本文內容：MCP+PTC：會「連招」的 Agent 工具箱Skills：給 Agent 配備的「知識膠囊」Subagents：「分而治之」的 Agent 架構聯繫、區別與協同📌 转载信息来源： https://linux.do/t/topic/1487408原作者： xiaola1转载时间： 2026/1/20 10:15:18
Skill 与 MCP 深度对比首先，官方文档非常值得细细品味，看完官方文档倒也可以考虑不用看其他的文章了（针对 skill，mcp 这一块感觉描述一般，mcp 太多东西了）：# Agent Skills# Agent Skills 概览# 通过 MCP 将 Claude Code 连接到工具一、Token 占用对比，这个大家应该都知道，不过多描述1.1 MCP：全量加载模式MCP 在会话启动时全量加载所有工具定义到上下文：会话启动 → 加载所有 MCP 服务器 → 注入全部工具定义（JSON-Schema） 就拿我使用的 mcp 来说： MCP 服务器工具数Token 占用 auggie-mcp1~1kgrok-search5~3kmemory9~5ksequential-thinking1~2k多服务器叠加-轻松突破 10k+ 随便用几个占用就非常大了1.2 Skill：按需加载模式Skill 采用渐进式披露，仅在需要时加载： 阶段加载内容Token 占用 启动时仅 name + description 索引~10-100 tokens/skill触发时完整 SKILL.md 内容~1,000-5,000 tokens/skill 我使用的 skill：90K 的 Skills 目录，/context 仅显示 513 tokens，和 mcp 对比起来，非常直观。1.3 简单对比 维度MCPSkill 启动时占用全量（10k+ tokens）索引（~500 tokens）使用时增量无（已加载）按需逐步加载 二、设计模式对比2.1 MCP：全量注入 + JSON-Schema什么是 MCP？MCP（Model Context Protocol）即模型上下文协议，采用 Host-Client-Server 三层架构：Host (Claude Code) │ ├── Client ←──JSON-RPC──→ context7 Server ├── Client ←──JSON-RPC──→ sequential-thinking Server └── Client ←──JSON-RPC──→ your Server 角色是什么 HostAI 应用程序（比如 Claude Code、VS Code、Cursor 等）Client通信管道，负责与 Server 建立连接、发送 JSON-RPC 请求、接收响应Server提供工具 / 上下文的程序（== 日常说的「安装 MCP」就是安装 Server==）JSON-RPCClient 与 Server 之间传输的数据格式（所有 MCP 都遵守此协议）Tool Schema启动时 Server 返回的「工具说明书」，告诉 Claude 有哪些工具、怎么调用 Host 和 Client 由应用自动管理，开发者 / 使用者只需关注 Server。再比如 FastMCP 框架会自动处理协议细节。MCP Server 目录结构（这里以 Python 为例）my-mcp-server/ ├── pyproject.toml # 包定义（必需） │ ├── name = "mcp-server-xxx" │ └── version = "1.0.0" ├── src/ │ ├── server.py # 入口，初始化 FastMCP │ ├── tools.py # Tool 定义（单文件，适合 <10 个工具） │ ├── tools/ # Tool 定义（多文件，按功能拆分） │ │ ├── __init__.py │ │ ├── search.py │ │ └── fetch.py │ └── resources.py # Resource 提供者（可选） └── README.md tools.py 和 tools/ 二选一，可根据数量决定。Tool 定义示例从这里就可以看出，其实和接口非常像，请求 -> 回调数据，实际上多数的 mcp 也都可以理解成三方接口。from mcp.server.fastmcp import FastMCP mcp = FastMCP("weather") @mcp.tool() async def get_weather(location: str) -> str: """Get weather for a location.""" return f"Weather in {location}: 72°F, Sunny" if __name__ == "__main__": mcp.run(transport="stdio") 客户端配置结构（mcpServers）配置示例：{ "args": [ "-y", "@upstash/context7-mcp" ], "command": "npx", "type": "stdio" } mcp 服务器的 json 格式，让配置起来非常方便，cv 万岁2.2 Skill：渐进式披露 + Markdown什么是 Skill？Skill 是 Claude Code 的知识 / 流程包，本质是一个 Markdown 文件夹，用于：注入领域知识（如代码规范、业务逻辑）定义工作流程（如代码审查 SOP、部署流程）封装可复用的脚本和模板 ==（这直接导致 Skill 与 MCP 在使用体验上趋于相似）==额外说明：Skill 只能提供指导，无法执行外部 API 调用、网络请求、会话管理等操作，毕竟只是 md 文件夹，但是能指导 cc 运行脚本，包括但不限于自带的脚本资源，这句话应该会有嚼头。Skill 目录结构（双层架构）以下规范取自 skill-creator Skill, 我觉得配置比 cc 官方文档里面的描述更详细skill-name/ ├── SKILL.md (必需) │ ├── YAML frontmatter ──→ 索引层（始终加载，~100 words） │ │ ├── name: (必需) │ │ └── description: (必需，唯一触发机制) │ └── Markdown 正文 ────→ 内容层（触发时加载，建议 <500 行） └── Bundled Resources (可选) ──→ 内容层（按需加载） ├── scripts/ - 可执行脚本（Python/Bash） ├── references/ - 参考文档（Claude 判断需要时加载） └── assets/ - 输出资源（模板、图片，不加载到上下文） 双层架构说明：索引层：YAML frontmatter 中的 name/description，始终在上下文中内容层：SKILL.md 正文 + 捆绑资源，仅在触发时选择性加载核心设计原则description 是唯一触发机制# ✅ 好的 description（包含触发场景） description: > Comprehensive document creation and editing with tracked changes. Use when Claude needs to work with .docx files for: (1) Creating new documents, (2) Modifying content, (3) Working with tracked changes, (4) Adding comments # ❌ 差的 description（太模糊） description: A useful document tool 渐进式披露模式是不是觉得模式 1,3 非常相似？我也觉得。不过 skill-creator 还是分成了这三种，就全罗列出来了模式 1：高层指南 + 引用# PDF Processing ## Quick start [核心代码示例] ## Advanced features - **Form filling**: See [FORMS.md](references/FORMS.md) - **API reference**: See [REFERENCE.md](references/REFERENCE.md) Claude 仅在需要时加载 FORMS.md 或 REFERENCE.md。模式 2：按领域 / 变体组织cloud-deploy/ ├── SKILL.md (工作流 + 选择指南) └── references/ ├── aws.md ← 用户选 AWS 时才加载 ├── gcp.md └── azure.md模式 3：条件详情## Editing documents For simple edits, modify XML directly. **For tracked changes**: See [REDLINING.md](references/REDLINING.md) **For OOXML details**: See [OOXML.md](references/OOXML.md) 工作流程用户请求 → Claude 扫描所有 Skill 的 description → 匹配 → 加载 SKILL.md 正文 → 按需加载 references → 执行 特点：宽松定义：Markdown 格式，自然语言描述懒加载：渐进式加载可编排：Markdown 可表达流程顺序和条件分支本质：流程 / 知识包（SOP 手册）三、版本管理与更新便利性结论先行：MCP 在版本管理上绝对优于 Skill。3.1 MCP：成熟的包管理生态核心机制MCP 直接复用 npm/PyPI 成熟生态，版本管理由包管理器自动处理。工作原理：MCP 服务器以 npm 包（js/ts）或 PyPI 包（Python）形式发布使用 npx 或 uvx 命令启动时，包管理器会自动处理下载和缓存版本号定义在 package.json（npm）或 pyproject.toml（PyPI）中更新行为： 模式行为启动速度适用场景 默认使用本地缓存，不查询 registry快日常使用强制更新每次查询 registry，版本变化时才下载（@latest 或 --refresh）慢需要最新版本时 获取方式对比： 获取方式配置示例更新机制 npx (npm)npx -y @pkg/server默认用缓存，需 @latest 或清缓存强制更新uvx (pip)uvx mcp-server-fetch默认用缓存，需 --refresh 或清缓存强制更新本地命令auggie --mcp需手动 pip install --upgrade 配置示例：// ~/.claude.json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] } } } 如何更新推荐方式：手动清理缓存当 MCP 服务器有新版本时，清理缓存即可：# 清理 npx 缓存 rm -rf ~/.npm/_npx #（不推荐！不推荐！不推荐！） # 清理 uvx 缓存 uv cache clean #（不推荐！不推荐！不推荐！） # 上述的清理会清理系统中所有的缓存，但mcp的缓存位置各有不同，需要主动寻找，且无规律可言，最好还是让cc自己来吧 工作流程：清理缓存重启 Claude Code自动下载最新版本优点：日常启动快，需要更新时才清理缓存不推荐使用 @latest 或 --refresh虽然可以自动更新，但会显著影响启动速度（每次都查询 registry）。配置示例：{ "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory@latest"] // npx 使用 @latest }, "fetch": { "command": "uvx", "args": ["--refresh", "mcp-server-fetch"] // uvx 使用 --refresh } } } 3.2 Skill：普遍缺乏版本管理现状：一般来说 Skill 没有版本管理与 MCP 不同，一般来说 Skill 没有任何版本管理机制：没有版本号定义没有版本锁定手动管理Skill 在某些时候更像可以随意定制的小玩具，在原本的基础上又能随意修改Skill 的获取与更新方式： 获取方式更新方式版本控制 GitHub 克隆git pull 手动更新依赖 Git commit hash下载 ZIP 文件手动替换文件无CC 直接生成即时生效无 问题：用户不知道 Skill 是否有新版本无法回滚到特定版本（除非使用 Git）例外：官方 Marketplace（需登录）唯一的版本管理方案是官方 Marketplace，但有严格限制：必须登录：API Key 用户无法使用非标准化：没有强制的版本号格式Marketplace 版本管理示例：// marketplace.json { "name": "my-plugins", "plugins": [ { "name": "review-plugin", "source": "./plugins/review-plugin", "version": "2.1.0" // ← 需要手动维护 } ] } 限制：仅适用于官方 Marketplace 中的 Skill无法用于自定义或第三方 SkillAPI Key 用户完全无法使用ps：这一块应该是这样的吧，没有官号诶Skill 的独特优势尽管缺乏版本管理，Skill 还有一个 MCP 无法比拟的优势：即时生效：修改 Skill 文件后无需重启服务，下次触发时自动加载最新内容。对比 MCP：MCP：修改后需重启 Claude Code 才能生效Skill：适合快速迭代和调试，改完即用适用场景：个人定制化 Skill（频繁调整）快速原型验证四、我推荐：使用 Slash Command 稳定触发事先声明： 这里的 /ccg 不是使用的 skill，我才发现，哎呀！！但是我都按照这个写了，不想再改了。/ccg 的工作流程是 /cmd → 自己的脚本请你们假装 是 /cmd → skill → skill 的脚本4.1 Skill 的触发不确定性问题Skill 依赖 Claude 自动匹配描述，存在以下问题：该触发时未触发（描述不够精准）不该触发时误触发（描述过于宽泛）实际体验：虽然 Skill 理论上能够自动触发，但实际触发率较低。比如我即使在 CLAUDE.md 中明确写了 "让 Codex 和 Gemini 参与协作"，Claude 偶尔还是会忽略。所以之前我都会主动在需求后面添加这句话。解决方案：使用 cmd 可以 100% 稳定触发。例如：/ccg:feat 需求描述 总比主动描述或者期待 cc 记得安心。4.2 最佳实践：Skill + Command 工作流组合为什么需要 Command：Skill 可能包含复杂的命令调用和参数配置，这些细节难以通过自然语言稳定触发。例如：外部工具调用：/home/nobug/.claude/bin/codeagent-wrapper --backend gemini带参数的指令：--backend codex、--SESSION_ID xxx多阶段工作流：需要按特定顺序执行多个步骤这些精确的指令和参数通过语言描述很难稳定触发，而 Command 可以将这些细节明确定义在文件中。模式 1 示例（简单流程）：场景：应用主题到 Artifact ├── ~/.claude/skills/theme-factory/ │ └── SKILL.md # 主题定义、应用指南 └── ~/.claude/commands/ └── theme-factory.md # 内容："Execute the theme-factory skill" 用户输入 /theme-factory 应用深色主题 ↓ Command 触发 → Claude 加载 SKILL.md → 自主执行 模式 2 示例（复杂流程）：场景：前端专项开发 └── ~/.claude/commands/ccg/ └── frontend.md # 完整工作流定义 用户输入 /ccg:frontend 实现响应式导航栏 ↓ Claude 加载 frontend.md 内容 ↓ 按照 Command 中定义的 6 个阶段执行： 1. Prompt 增强（可选） 2. 研究（代码检索） 3. 构思（调用 Gemini 分析） 4. 计划（调用 Gemini 规划） 5. 执行（Claude 实施） 6. 优化（调用 Gemini 审查） 外部工具说明：像 codeagent-wrapper 这样的工具是外部可执行文件（位于 ~/.claude/bin/），不是 Skill。Skill 只能提供指导，无法执行外部 API 调用、网络请求、会话管理等操作，这些必须由外部工具完成。核心原则：稳定性优先：复杂流程用 Command 定义，确保稳定执行外部工具必须用 Command：Skill 无法执行外部命令简单场景用 Skill：减少维护成本，提高灵活性第一次写文章，本来只是想说 mcp 的包管理很爽 ，其他的都是为了这碟醋包的饺子📌 转载信息来源： https://linux.do/t/topic/1485159原作者： Shuiyell转载时间： 2026/1/19 17:52:41
Skills 的底层逻辑：从提示词到架构模式最近 Skills 功能上线了，看到大家都在分享使用教程。我就不凑热闹发教程了，今天给各位大佬分享一点更底层的东西：Skills 的本质到底是什么？学不会？没事，学中干，干中学各位，没必要非要知道原理，只要会用即可！！！下面我用很简答易懂的话讲解了，还不懂就评论问吧！！！什么是 Skills？Skills 的本质：Agent 时代的通用架构模式Skills 不属于任何模型，不属于 MCP，也不属于任何一家科技巨头。它是 Agentic AI ( 智能体 AI) 发展过程中诞生的一种通用设计 模式 (Design Pattern)。抛开所有无用的内容，来看看具体实现，Skills 的核心逻辑其实很简单，可以用下面这个永恒的公式概括：Skills = System Prompt (系统提示词) + Trigger (自动触发器) + Executable (可执行文件)1. 手动模式 vs 自动模式为了理解 Skills 的适用性，我们回溯到人与 AI 交互的最基本形式。比如当你想要 AI 帮你写出一段高质量代码时，你通常可能会输入这样一段话：“你现在是一个资深 Python 架构师，精通设计模式和性能优化。请帮我审查这段代码…”在这个瞬间，你所输入的对话，其实就是在手动执行一个 Skill。你通过手动输入，给 AI 设定了角色 (Role) 和 上下文 (Context)。所谓的 Skills，就是把这个过程 “代码化” 或 “自动化” 了。无论是在 Gemini CLI、Claude Code 还是现在的这些 IDE 中，逻辑都是一样的：用户将这段 “资深 Python 架构师” 的设定（Prompt）封装成一个独立的模块。系统告诉模型：“如果用户问代码问题，你就自动加载这个模块，不需要用户每次都手敲。”2. 为什么系统提示词 (System Prompt) 也能调用 Skills？你可能会问：模型是怎么知道我有这些 Skills 的？这就涉及到了 System Prompt 的隐形机制。在对话开始之前，IDE 已经在后台偷偷做了一件事：它把所有可用 Skills 的名字和描述，写进了发给模型的第一条系统提示词里。这就像是考试前，老师（IDE）给学生（模型）塞了一张小纸条：“考试须知：如果你遇到不懂的代码题，你可以申请查阅‘Python 架构师手册’（即调用 skill: python-architect）。”正因为系统提示词里预埋了这些指令，模型才能在遇到问题时，理直气壮地 “调用” Skills。所以，System Prompt 不仅是 Skills 的载体，更是 Skills 的 “目录” 和 “导航”。这也是为什么我在 IDE 不支持的情况下能够将 skills 实现，很早就写出提示词来实现了 skills 这个功能。3. 进阶：Skill 包的解剖学 (Scripts & Assets)很多高级 Skill（比如 ui-ux-pro-max-skill）不仅仅是一个 Markdown 文件，它往往是一个文件夹。一个完整的 Skill 包结构通常是这样的：my-complex-skill/ ├── SKILL.md # 大脑：提示词和指令 ├── scripts/ # 手脚：Python/Node.js 脚本 │ ├── audit.py │ └── generate.js └── assets/ # 素材：图片、模板 └── logo.png 当 AI 决定调用这个 Skill 时，它不仅会读取 SKILL.md，还会获得执行 scripts/ 下脚本的权限。 比如，AI 可能会运行 python scripts/audit.py 来扫描你的代码，而不是自己瞎猜。4. 环境悖论：没有 Node 环境会怎样？这是一个非常现实的问题：“如果我在 Skills 中设定了调用 Node.js 脚本，但我电脑上没有安装 Node，Skills 会自动下载吗？”答案是：通常不会。Skills 是运行在你本地环境 (Local Environment) 中的。Skill 就像是一张游戏光盘。你的电脑 就像是游戏机。Node/Python 环境 就像是操作系统。如果你买了游戏光盘（下载了 Skill），但没买游戏机（没装 Node），游戏是跑不起来的。 Agent 尝试运行 node script.js 时，会直接收到系统的报错：command not found: node。虽然现在的 Agent 很聪明，它可能会检测到报错，然后建议你：“检测到未安装 Node.js，请先安装。”但它通常不敢（也不应该）擅自帮你下载安装这种系统级的 Runtime，因为这涉及巨大的安全风险和兼容性问题。 如何保证能够让 skills 实现下载 node 环境呢？这里有一个专业的术语，叫 “Runtime Bootstrapping” (运行时引导)。你不应该简单地说 “下载 Node”，而应该在 Skill 的定义中加入一段 “自愈式 (Self-Healing)” 的指令。专业的话术建议：“Prerequisite Check & Environment Setup” (前置检查与环境搭建)“在执行任何脚本之前，请先运行 node -v 验证运行时环境。如果环境缺失，请不要直接报错，而是根据用户的操作系统（Windows/macOS/Linux），生成对应的安装命令（如 winget install 或 brew install），并引导用户完成安装。”这样做，你的 Skill 就从一个 “会报错的脚本”，变成了一个 “会照顾用户的智能体”。这也是为什么 ui-ux-pro-max-skill 这个 skills 会有那么多人是使用，因为人在 skills 中照顾到了所有的群体，没有环境，那我就下环境，可以看这个 skills 来实现自己的 skills。5. 核心辨析：Skills vs MCP vs RAG在 Agent 的架构中，很多人容易混淆这三个概念。其实它们构成了智能体的 “能力铁三角”： 概念本质人体比喻作用 RAG数据 (Data)记忆 / 书本告诉 AI 它不知道的事实（如公司规章、私有文档）。MCP接口 (I/O)手和脚让 AI 连接外部世界（如读取数据库、操作 GitHub、发送 Slack）。Skills方法论 (Behavior)大脑皮层教 AI 处理问题的专业思维（如代码审计流程、苏格拉底教学法）。 一句话总结它们的关系：一个强大的 Agent，会用 Skills (专业思维) 去指挥 MCP (手脚)，并参考 RAG (记忆) 来完成任务。Skills 往往是那个指挥官。它定义了流程，而 MCP 是它调用的工具。6. 痛点：为什么有些模型 (如 GLM-4.7) 跑 Skills 效果不好？这其实是目前 Agent 开发中最大的坑：Skills 对模型是有门槛的。你可能会发现，同样的 Skill，在 gemini 3 flash 上跑得行云流水，但在 GLM-4.7 或 DeepSeek 上却经常 “卡壳” 或 “乱答”。这背后的原因主要有三点：A. Function Calling (工具调用) 的微调差异Skills 的触发依赖于模型输出极其精准的 JSON 格式 指令。Claude/Gemini：经过了海量的 Tool Use 专项微调，它们知道什么时候该 “闭嘴去调工具”。普通模型：往往有 “抢答” 的毛病。它们看到了 Skill 的描述，却选择直接用自己的通用知识去回答用户，而不是去调用 Skills。B. System Prompt 的权重问题Skills 的指令通常是写在 System Prompt 里的。有些模型在训练时，过分强调了 User Prompt (用户输入) 的权重，导致它忽略了 System Prompt 里的设定。结果就是：你明明加载了 “资深架构师” 的 Skill，它却还是像个 “普通客服” 一样回答你。这也就是为什么在国内模型中需要设定很严格的提示词规则！！！C. 复杂推理链 (Reasoning Chain) 的断裂执行一个 Skill 往往需要多步操作（思考 → 选工具 → 看结果 → 再思考）。很多模型在第一步之后就 “累” 了，或者丢失了上下文，导致 Skill 执行到一半就中断了。结论：Skills 是一种高级玩法，它需要 Agentic Model (代理级模型) 的支持，而不仅仅是 Chat Model (聊天模型)，并且要上下文够长才能支持的更好。6. Skills 是如何跑起来的？这个模式的成功，依赖于现代 LLM (大语言模型) 进化出的两个通用素质：A. Tool Use / Intent Recognition (意图识别能力)这是 Skills 的开关。模型必须具备一种元能力：不仅仅是 “回答问题”，而是能 “判断该用什么方法回答问题”。当模型意识到：“用户的问题超出了我的通用知识，我需要激活 python-architect 这个专业模块” 时，Skill 就被触发了。B. Long Context / In-Context Learning (上下文学习能力)这是 Skills 的容器。当 Skill 被激活时，系统会瞬间将几千字甚至上万字的专业指令（即那个封装好的 Prompt）注入到对话流中。模型必须有足够大的容量来接纳这些新规则，并立即改变自己的行为模式。7. 最后的最后Skills 是 Prompt Engineering (提示词工程) 走向 Software Engineering (软件工程) 的必然产物。它解决了 AI 应用开发中的一个根本矛盾：通用性与专业性的矛盾。我们不需要一个在每一秒都精通所有领域的臃肿 AI。我们需要的是一个灵活的调度器，它能根据你的需求，在毫秒级的时间内，从口袋里掏出那个最正确的剧本（Skill），瞬间变身为那个领域的专家。这就是 Skills。它是流动的知识，是按需分配的智慧。 感谢各位观看！！！如果有用请多多评论！！！📌 转载信息来源： https://linux.do/t/topic/1468447原作者： Y_yuHou转载时间： 2026/1/16 16:49:05
在这里，我分享一下如何万能的创建属于你自己的 skill 和对应的 hooks 搭配，不过在分享之前，我要声明，我并非原创发现，我只是从各个地方学习到了知识，然后整合分享给大家一。如何创建自定义的 skill1. 安装 skill 插件与 MCPgithub 仓库地址： anthropics/skills: Public repository for Agent Skills这里我直接把命令拿过来方便直接使用，在 Claude code 里面输入/plugin marketplace add anthropics/skills（两个哪个都行，安装一次就行）/plugin install document-skills@anthropic-agent-skills/plugin install example-skills@anthropic-agent-skills运行后选择 Install for you (user scope)提示✓ Installed document-skills. Restart Claude Code to load new plugins. 就是安装成功了，然后重启 Claude Code这里安装 skill 插件是为了有 skill-creator，它的作用是创建或更新 skills 的指南2. 安装 **chrome-devtools-mcp** 和 upstash/context7: Context7 MCP Server – Up-to-date code documentation for LLMs and AI code editors（可选项）直接配置这两个 MCP 就行，这里不演示了2. 此时就可以创建 skill 了情景一：需要把 API 文档做成 skill举例：OpenAI 兼容协议文档❶与 Claude 对话：请你使用 context7mcp 去查找 OpenAI 兼容协议文档，详细的告诉我它的全部内容❷请你根据刚刚查询到的全部内容，参考 skill-creator 来帮我生成 skill现在就创建成功了，只不过我发现他放的地方不对那个文件夹是项目级别（当前项目专用），应该放在.claude\skills 这个文件夹里，这个手动移动一下就行，.skill 文件是打包好的把这个 .skill 文件移动到全局 skills 目录，所有项目都可以使用。这时候一个 skill 就创建好了情景二：需要把 context7 查不到的文档做成 skill举例：智谱的 API 文档❶与 Claude 对话：请你使用 chrome-devtools-mcp 访问 使用概述 - 智谱 AI 开放文档（链接放在这里变成蓝链了，对话的时候直接粘贴链接就行，别粘贴文字）❷与 Claude 对话：请你使用 chrome-devtools-mcp 把 cURL；Python SDK；Java SDK；Python SDK (旧) 这几个调用示例的具体内容查一下，还有关于 GLM 编码套餐的端点差异也查看一下（我这里只是举例子，你看你自己的文档，你需要什么内容，你就把你需要的内容让他再次去查看）❸与 Claude 对话：请你根据刚刚查询到的全部内容，参考 skill-creator 来帮我生成 skill创建成功依旧是需要手动一下位置，但是问题不大情景三：把 MCP 做成 skill举例：把 context7 做成 MCP❶与 Claude 对话：请你把 context7 这个 MCP 的调用参考 skill-creator 来帮我生成 skill，我的要求是，在新增或修改代码之前，使用此 mcp 去查询最新的、特定版本的文档和代码示例，放入上下文进行参考万能创建 skill 总结：1. 安装 skill-creator（skill 官方的生成技能）2. 根据自己的需求，先让 Claude code 完成你的任务，先完成一次，然后让他根据上下文参考 skill-creator 去创建一个新的 skill注：MCP 查询到的结果可以写入 skill,mcp 本身的调用也可以写入 skill, 哪怕我刚刚举的例子里没有也是可以做到的。比如说让它先打开浏览器，然后在浏览器里搜索北京今日天气，然后获取当前页面结构，获得到今天的天气，然后让他去创建一个 md 文档，命名为今日日期，内容为今日天气；在整个流程跑完之后，让他参考 skill-creator 去创建一个这样的一个流程 skill3. 如果对现有的 skill 需要进行修改，那直接把 skill 文件夹拉到对话框里，然后告诉他，请你参考 skill-creator 进行修改，我需要修改的内容是：******（这里你可以修改触发条件，你也可以修改任何内容，就只要你想修改的东西都可以这样改）二。如何创建自定义的 hooks（我贴一下学习来源的原文链接： 25% → 90%！别让 Skills 吃灰：Hooks + Commands + Agents 协同激活 AI 全部能力：Claude Code 工程化实践_hooks + commands + agents + skills-CSDN 博客）1. 创建文件.claude/hooks/ 目录下创建一个文件：skill-forced-eval.js2. 编辑内容// skill-forced-eval.js 核心逻辑 const instructions = `## 指令：强制技能激活流程（必须执行） ### 步骤 1 - 评估 针对以下每个技能，陈述：[技能名] - 是/否 - [理由] 可用技能列表： - crud-development: CRUD/业务模块开发 - api-development: API设计/RESTful规范 - database-ops: 数据库/SQL/建表 - ui-pc: 前端组件/AForm/AModal - ui-mobile: 移动端/WD UI组件 ...（共26个技能） ### 步骤 2 - 激活 如果任何技能为"是" → 立即使用 Skill() 工具激活 如果所有技能为"否" → 说明"不需要技能"并继续 ### 步骤 3 - 实现 只有在步骤 2 完成后，才能开始实现。`; console.log(instructions); 这里把技能列表改成你自己的 skill 就行这个 hooks 就可以大幅提升 skill 的使用率了，具体的 hooks 如何去编写，规范如何，我自己还在学习中，学习完成后续也会做教程给大家分享出来📌 转载信息来源： https://linux.do/t/topic/1467359原作者： huanchong转载时间： 2026/1/16 13:03:58
这个开源项目精选了超级多的 skills，从文档处理，工具调用，市场分析，数据分析，系统安全等 各大精选的 skill 都有。 github.com GitHub - libukai/awesome-agent-skills: Agent Skills 权威中文指南：快速入门、推荐技能、最新资讯与实战案例Agent Skills 权威中文指南：快速入门、推荐技能、最新资讯与实战案例 📌 转载信息来源： https://linux.do/t/topic/1462309转载时间： 2026/1/15 18:29:29
vercel 把他们 react+nextjs 知识点浓缩成了 1 个 skills感觉编码以后会越来越容易了github 地址：GitHub - vercel-labs/agent-skills📌 转载信息来源： https://linux.do/t/topic/1461170原作者： uoyc转载时间： 2026/1/15 10:52:31