标签 Agent Skills 下的文章

(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核心头条

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)

2GitHub 热门开源项目

本周 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)

3前沿研究与行业风向

  • 物理 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 × 智谱 BigModel 实战集成指南》中,我们已经完成了一次完整的项目实战。项目可以正常运行,但在后续代码 Review 时,一个问题逐渐暴露出来:

生成的代码虽然能跑,但大量 API 和用法已经过时,与最新官方文档存在明显偏差。

这在 AI 辅助开发中其实非常常见——模型的训练数据更新速度,往往赶不上框架和 SDK 的迭代速度。

正巧这时,一位朋友向我推荐了 Anthropic 最新发布的 Agent Skills,通过 plugins 的方式,让 Claude 在生成代码时 动态读取最新官方文档和工具能力,从而显著降低“写得像,但跑不通”的概率。

本文就是这次探索的完整记录。


一、Agent Skills 是什么?

官方仓库地址:

https://github.com/anthropics/skills

Agent 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 打开了“官方增强模式”。

PixPin_2026-01-22_10-07-25.png


三、安装 context7 插件(关键步骤)

接下来是本文的重点:context7

1️⃣ 打开插件管理

在 Claude Code 中输入:

/plugins

然后使用键盘 ➡️ 进入 Discover

2️⃣ 搜索并安装 context7

在搜索框中输入 context7,完成安装。

context7 本质上是一个 MCP(Model Context Protocol)插件,
能让 Claude 直接参考并对齐最新的官方文档内容

PixPin_2026-01-22_10-09-22.png


四、使用 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

不要靠“印象”写代码,而是以当前官方文档为准

PixPin_2026-01-22_10-29-45.png


五、实际体验与问题分析

真实结论只有一句话:

效果明显提升,但依然不能“一次生成直接可用”。

优点

  • 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 开头,至少包含 namedescription; 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

摘要

随着 Anthropic 开源 skills 仓库,"Code Interpreter"(代码解释器)模式成为 Agent 开发的热门方向。许多开发者试图采取激进路线:赋予 LLM 联网和 Python 执行权限,让其现场编写代码来解决一切问题。但在构建企业级“智能文档分析 Agent”的实践中,我们发现这种“全托管”模式在稳定性、安全性和可控性上存在巨大隐患。本文将分享我们如何摒弃激进路线,采用 Java (确定性 ETL) + DSL 封装式 Skills + 实时渲染 的混合架构,在保留 LLM 灵活性的同时,确保系统的工业级稳定性。

一、 背景:当文档分析遇到“复杂生成”

在我们的“文档处理 Agent”项目中,基础的问答功能(RAG)已经解决得很好。但随着用户需求升级,我们面临了新的挑战:

用户场景

“这是 2024 和 2025 年的两份经营数据报表,请对比 DAU 和营收的同比增长率,并生成一个 Excel 表格给我。另外,把总结报告导出为 PDF。”

这类需求包含两个特征:

  1. 逻辑计算:需要精确算术(LLM 弱项)。

  2. 文件 IO:需要生成物理文件(LLM 无法直接做到)。

引入 Skills(让 LLM 调用 Python 代码)似乎是唯一解。但在具体落地时,我们走了一段弯路。

二、 弯路:激进的“纯 Skills”路线

起初,我们参考了开源社区做法,采用了 完全的 Code Interpreter 模式。我们将 requestspandasreportlab 等库的权限全部开放给 LLM,并在 Prompt 中告诉它:“你是一个 Python 专家,请自己写代码解决所有问题。”

这种“裸奔”模式在生产环境中遭遇了三次暴击:

  1. 输入端不可控:LLM 对非结构化数据(如无后缀 URL、加密 PDF)的处理极其脆弱,经常陷入报错死循环。

  2. 输出端崩坏:让 LLM 从零绘制 PDF/Word 是灾难。经常出现中文乱码、表格对不齐、使用了过期的库 API 等问题。

  3. 安全黑洞:数据流完全在沙箱内闭环,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 输出侧:渲染与交付的分离

对于不同类型的文件,我们采取了截然不同的交付策略:

  1. Excel(强结构化):走 Skills 路线。LLM 组装数据 -> 调用 excel_tool -> 沙箱生成物理文件。

  2. Word/PDF(富文本):走 渲染路线严禁 LLM 写代码生成。

  3. LLM 只输出高质量的 Markdown 并在末尾打上 <<>> 标签。

  4. Java 后端拦截该标签,利用 OpenHTMLtoPDFPandoc 将 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 拥有了“手”,但这双手必须戴上“手套”。

通过这次架构演进,我们得出的核心经验是:

  1. 不要高估 LLM 的 Coding 能力:它是一个优秀的逻辑推理引擎,但在工程细节(排版、库依赖、环境配置)上非常糟糕。DSL 封装是必须的。

  2. 不要丢掉 Java 的确定性:解析、下载、格式转换、安全检查,这些传统代码擅长的领域,不要交给概率性的 LLM 去做。

  3. 架构分层

  4. Input: Java (Standardization & Security)

  5. Thinking: LLM (Reasoning)

  6. Action: Python (Calculation via DSL)

  7. Output: Java (Rendering & Delivery)

这种混合架构,既保留了 Agent 处理复杂动态需求的能力(如自定义计算涨跌幅),又守住了企业级应用对稳定性与合规性的底线。

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~1k
grok-search5~3k
memory9~5k
sequential-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.pytools/ 二选一,可根据数量决定。

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)形式发布
  • 使用 npxuvx 命令启动时,包管理器会自动处理下载和缓存
  • 版本号定义在 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自己来吧 

工作流程

  1. 清理缓存
  2. 重启 Claude Code
  3. 自动下载最新版本

优点:日常启动快,需要更新时才清理缓存

不推荐使用 @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
  • 无法用于自定义或第三方 Skill
  • API 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 的包管理很爽 ,其他的都是为了这碟醋包的饺子


📌 转载信息
原作者:
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。

它是流动的知识,是按需分配的智慧。 感谢各位观看!!!如果有用请多多评论!!!


📌 转载信息
原作者:
Y_yuHou
转载时间:
2026/1/16 16:49:05

在这里,我分享一下如何万能的创建属于你自己的 skill 和对应的 hooks 搭配,不过在分享之前,我要声明,我并非原创发现,我只是从各个地方学习到了知识,然后整合分享给大家

一。如何创建自定义的 skill

1. 安装 skill 插件与 MCP

github 仓库地址: 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 去创建一个这样的一个流程 skill
3. 如果对现有的 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.js

2. 编辑内容

// 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 如何去编写,规范如何,我自己还在学习中,学习完成后续也会做教程给大家分享出来


📌 转载信息
原作者:
huanchong
转载时间:
2026/1/16 13:03:58

这个开源项目精选了超级多的 skills,从文档处理,工具调用,市场分析,数据分析,系统安全等 各大精选的 skill 都有。


📌 转载信息
转载时间:
2026/1/15 18:29:29