从teach SKILL看如何将教学封装为可复用智能体技能模块

1. 从“教人写代码”到“把教学本身做成一个可复用模块”MattPocock 这个名字做 TypeScript 和前端工程化的人基本都不陌生。他早年是 TypeScript 团队的核心贡献者后来做 Total TypeScript、AI Hero 这些教学产品属于那种“自己写代码很猛同时还能把复杂东西讲明白”的选手。最近他在社区里抛出的一个概念挺有意思——teach SKILL直译过来就是“把教学这件事做成一个 SKILL”。这个说法乍一听有点抽象但如果你最近在折腾 Claude Code、Codex、Cursor 这类带 SKILL 机制的智能体工具就会立刻反应过来他说的不是“写一个教编程的教程”而是把“教学”这个行为本身抽象成一个可被智能体调用的技能模块。我先把结论摆在这这件事的价值不在于“又多了一个 SKILL”而在于它示范了一种思路——任何重复性的、有固定套路的智力劳动都可以被封装成 SKILL。教学恰好是最典型的一种。你想想一个老师或者一个技术博主每天干的事情是什么判断学生当前水平、找到知识缺口、设计一个刚好够得着的练习、给出反馈、再根据反馈调整下一步。这套流程高度结构化而且反复发生。把它做成 SKILL意味着智能体可以在你写文档、做课程、甚至 review 别人代码的时候自动以“教学者”的姿态介入而不是简单地丢一段答案给你。热搜词里那一堆claude code skill、codex skill、agent skill、skill和agent的区别、skill怎么编写其实都指向同一个困惑大家知道 SKILL 这个东西存在但不太清楚它到底该怎么设计、怎么落地。MattPocock 这个 teach SKILL 正好是一个极佳的解剖样本。它不复杂但足够完整能让你看清一个 SKILL 从 frontmatter 到 workspace 再到具体执行逻辑的全貌。这篇文章我打算按“为什么这么设计 → 核心结构拆解 → 手把手复现 → 踩坑与排查”这条线走。不管你是想给自己的教学产品加一个 SKILL还是单纯想搞明白skill脚本、skill插件到底怎么写都能直接抄作业。我会尽量把每个设计决策背后的“为什么”讲透因为光知道怎么写没用换个场景你就不会了。2. 为什么“教学”值得被做成一个 SKILL2.1 教学的本质是一套可复用的决策流程很多人对教学有个误解觉得它是“知识输出”。其实不是。知识输出是搜索引擎干的事教学的核心是决策我现在该讲什么、讲多深、用什么例子、讲完之后怎么判断对方懂了没有。这套决策流程有几个特点让它特别适合被 SKILL 化。第一它有明确的输入和输出。输入是“学习者当前的状态”和“目标状态”输出是“一系列缩小两者差距的动作”。第二它有稳定的中间步骤比如诊断、拆解、示范、练习、反馈。第三它需要反复调用一个老师带一百个学生这套流程要走一百遍。第四它依赖上下文同样的知识点对新手和对老手讲法完全不同。这四点加起来就是一个 SKILL 的理想候选。你把它写成 SKILL智能体在需要的时候就能调用这套决策流程而不是每次从零开始“即兴发挥”。即兴发挥的问题在于不稳定——今天讲得深明天讲得浅用户体感很差。SKILL 的价值就是把这种不稳定收敛成可预期的行为。2.2 SKILL 和 Agent 到底差在哪热搜里skill和agent的区别这个问题出现频率很高我用自己的理解说清楚。Agent 是“谁来做”SKILL 是“怎么做”。Agent 是一个有自主性的执行主体它能规划、能调用工具、能多轮迭代。SKILL 更像是一份“操作手册 能力封装”它告诉 Agent 在特定场景下应该遵循什么流程、调用什么资源、产出什么格式。打个比方Agent 是一个新入职的员工SKILL 是公司给他的一本《标准作业程序》。员工有能力自己摸索但有 SOP 在手他做出来的东西质量更稳定、更符合预期。MattPocock 的 teach SKILL本质就是给智能体一本《如何教人》的 SOP。这也解释了为什么skill怎么编写会成为高频问题。写 SKILL 不是写代码更像是写一份给聪明但没经验的同事看的操作指南。你得把隐性知识显性化把“我凭感觉这么做”变成“第一步做什么、第二步做什么、遇到什么情况怎么分支”。2.3 把教学 SKILL 化能解决什么真实痛点我自己在做技术内容的时候最大的痛点是一致性。同一个概念我今天状态好讲得深入浅出明天赶时间就丢一段干巴巴的定义。读者感受到的质量是波动的。teach SKILL 解决的第一个问题就是这个——它把“怎么讲”固化下来让每次输出都维持在一个基准线以上。第二个痛点是适配成本。给小白讲和给老手讲准备工作完全不同。如果每次都要手动判断对方水平、手动调整讲法效率极低。SKILL 可以把“水平诊断”做成一个标准环节智能体先问几个问题或者看几段代码自动判断该从哪个层次切入。第三个痛点是反馈闭环。传统教学里讲完就完了学生懂没懂全靠他自己说。teach SKILL 可以内置“检验环节”比如让学习者复述、做一个小练习、或者解释一段代码通过输出反推理解程度。这个闭环一旦建立教学质量会有质的提升。3. teach SKILL 的核心结构拆解3.1 frontmatterSKILL 的“身份证”和“触发条件”任何 SKILL 文件的开头都有一段 frontmatter用---包起来。这段东西决定了 SKILL 叫什么、什么时候被激活、需要什么权限。热搜词里frontmatter单独被拎出来说明很多人卡在这一步。我拿 teach SKILL 的典型结构举例说明。--- name: teach description: 当用户需要学习某个概念、理解一段代码、或请求教学式解释时激活。以诊断-拆解-示范-检验的流程进行教学。 version: 1.0.0 tags: - education - explanation - mentoring ---这里每个字段都有讲究。name是 SKILL 的唯一标识智能体调用时用的就是它。description是最关键的一行它决定了 SKILL 什么时候被触发。写 description 有个技巧不要写“这个 SKILL 是干什么的”要写“什么情况下应该用它”。因为智能体是根据当前对话上下文去匹配 description 的你写“用于教学”它可能不知道什么时候算教学你写“当用户请求教学式解释时激活”匹配就精准得多。version和tags属于辅助信息方便管理和检索。有些平台还支持allowed-tools字段用来限制这个 SKILL 能调用哪些工具这是安全边界后面会细说。注意frontmatter 的 YAML 语法对缩进极其敏感用空格不用 Tab。我见过太多人因为一个 Tab 导致整个 SKILL 加载失败排查半天。3.2 workspaceSKILL 的“工作台”和上下文容器workspace这个词在热搜里反复出现还伴随着一堆报错比如workspace still starting、setting up workspace: loading packages...卡住。这说明 workspace 是 SKILL 运行时的核心概念也是最容易出问题的地方。简单说workspace 是 SKILL 执行时的隔离环境。它包含这个 SKILL 需要的所有资源参考文档、示例代码、模板文件、甚至依赖包。当 SKILL 被激活智能体会在一个独立的 workspace 里工作不会污染主对话的上下文。teach SKILL 的 workspace 通常包含这几类东西。第一是知识库比如某个技术栈的常见误区清单、渐进式练习题库。第二是模板比如“概念解释模板”“代码 review 教学模板”。第三是诊断脚本用来分析学习者提供的代码或问题判断水平层次。为什么要隔离因为教学场景经常需要加载大量参考资料如果全塞进主上下文会挤占对话空间还会让智能体分心。workspace 让这些资源“按需加载”用到才读读完就释放。这也是为什么 workspace 启动会慢——它在后台准备环境。3.3 执行流程诊断、拆解、示范、检验四步走teach SKILL 的正文部分核心就是一套执行流程。我把它归纳成四步这也是 MattPocock 教学理念的精华。诊断是第一步也是最容易被跳过的一步。很多人一上来就讲结果讲深了对方听不懂讲浅了对方觉得浪费时间。诊断的做法可以是提问“你之前接触过 X 吗”也可以是看产出让学习者贴一段代码或一段文字。关键是不要假设对方水平。拆解是把一个复杂概念切成若干个小块然后判断哪些块是当前必须的哪些可以往后放。这里有个原则叫“最小必要知识”——只讲理解当前问题所必需的部分剩下的等用到再说。贪多嚼不烂教学大忌。示范是给出一个具体例子最好是可运行的、可验证的。抽象概念配具体例子理解成本会大幅下降。示范的时候要“出声思考”把解题时的内心独白讲出来这比只给答案有价值得多。检验是让学习者输出。可以是复述、可以是改一段代码、可以是解决一个变体问题。检验的目的不是考试是暴露理解盲区。盲区暴露得越早纠正成本越低。这四步不是线性的是循环的。检验发现问题回到诊断重新判断再拆解、再示范。teach SKILL 把这个循环写进流程智能体就会自动迭代而不是讲完就撒手。4. 手把手复现一个 teach SKILL4.1 环境准备与目录结构先说环境。不同平台的 SKILL 存放位置不一样但结构大同小异。以常见的约定为例SKILL 通常放在一个专门的目录下每个 SKILL 一个文件夹。skills/ teach/ SKILL.md # 主文件含 frontmatter 和流程说明 workspace/ knowledge/ # 知识库 common-mistakes.md exercises.md templates/ # 模板 explain-concept.md review-code.md scripts/ # 诊断脚本 assess-level.py这个结构的好处是清晰。SKILL.md是入口workspace 里的东西按类型分目录。智能体读 SKILL.md 知道流程需要具体资源时再去 workspace 里找。提示如果你的平台报workspace requires the virtual machine platform这类错误通常是底层隔离环境没装好。这不是 SKILL 本身的问题是运行环境的问题。先确认平台要求的虚拟化组件是否启用再回来调试 SKILL。4.2 编写 SKILL.md 的完整流程SKILL.md 分两部分frontmatter 和正文。frontmatter 前面讲过了这里重点说正文怎么写。正文的核心是用自然语言描述流程但要有结构。不要写成散文要写成“步骤 判断条件 输出要求”。我给出 teach SKILL 正文的一个可复现版本。## 执行流程 ### 第一步诊断学习者水平 - 如果用户提供了代码或文字产出先分析其复杂度、用词准确性、结构完整性 - 如果用户没有提供产出提出 2-3 个递进式问题来判断水平 - 将水平分为三档入门、进阶、熟练 - 输出一句话总结当前判断并说明依据 ### 第二步拆解知识点 - 识别当前问题涉及的核心概念 - 列出理解该问题所需的“最小必要知识” - 按依赖关系排序先讲被依赖的 - 输出一个有序的知识点清单 ### 第三步示范与讲解 - 为每个知识点提供一个具体例子 - 例子要可运行、可验证 - 讲解时展示推理过程不只给结论 - 输出例子 推理过程 一句话总结 ### 第四步检验理解 - 提出一个变体问题或小练习 - 等待用户回答 - 根据回答判断是否需要回到第一步 - 输出练习 反馈 下一步建议这份流程看起来简单但威力在于它把教学的隐性决策显性化了。智能体照着走就不会出现“上来就丢一大段定义”这种典型问题。4.3 workspace 资源的准备与加载workspace 里的资源不是越多越好是越精准越好。我建议从三类开始准备。第一类是常见误区清单。比如教 TypeScript 的时候any的滥用、类型断言和类型守卫的混淆、泛型约束的理解偏差这些都是高频误区。把它们写成一个 markdown 文件智能体在诊断阶段可以对照检查。第二类是渐进式练习题库。每个知识点配 2-3 个难度递增的练习。入门题验证概念理解进阶题验证应用能力熟练题验证迁移能力。题库不用大但要覆盖核心知识点。第三类是输出模板。教学输出最怕格式混乱今天这样讲明天那样讲。模板能保证一致性。比如“概念解释模板”可以规定先给一句话定义再给一个生活类比再给一个代码例子最后给一个常见误区。加载策略上我建议按需加载。SKILL.md 里只写“需要时读取 workspace/knowledge/common-mistakes.md”不要一上来就把所有文件读进上下文。这样既省 token又让智能体聚焦。4.4 参数选择与触发条件调优SKILL 的触发条件直接写在 frontmatter 的 description 里但光写还不够还要调。调优的方法是观察误触发和漏触发。误触发是指不该用 teach SKILL 的时候用了。比如用户只是问“这个函数返回什么”智能体却启动了一整套教学流程这就很烦。解决办法是在 description 里加排除条件比如“当用户仅请求事实性答案时不要激活”。漏触发是指该用的时候没用。比如用户说“我不太懂这个概念”智能体却只丢了一段文档链接。解决办法是把 description 写得更贴近用户的自然表达把“我不懂”“能讲讲吗”“为什么”这些信号词纳入匹配范围。这个调优过程没有捷径就是用、观察、改、再用。我自己的经验是一个 SKILL 的 description 至少要迭代五到十次才能稳定。5. 常见问题与排查技巧实录5.1 SKILL 不触发或触发错误怎么办这是最高频的问题。排查顺序我总结成一张表。现象可能原因排查方法完全不触发frontmatter 语法错误用 YAML 校验工具检查缩进和引号完全不触发description 太抽象改成“什么情况下用”的表述误触发description 太宽泛加入排除条件和场景限定触发但不执行流程正文流程描述不清把步骤写成有序列表加判断条件触发后卡住workspace 资源加载失败检查文件路径和权限我踩过最坑的一次是 frontmatter 里description用了中文冒号YAML 解析直接失败但平台没报错只是静默不加载。排查了半小时才发现。所以标点符号一定要用英文半角这是血泪教训。5.2 workspace 启动失败的典型场景热搜里workspace still starting、loading packages...卡住这类问题我遇到过几次。原因通常有三类。第一类是网络问题。workspace 启动时如果需要拉取依赖包网络不通就会卡住。解决办法是提前把依赖预置到本地或者配置好镜像源。第二类是资源过大。workspace 里塞了几百兆的参考资料启动时全量加载自然慢。解决办法是精简资源按需加载。第三类是环境隔离组件缺失。有些平台需要特定的虚拟化支持才能启动隔离环境如果系统层面没启用就会报requires the virtual machine platform这类错误。这个得在操作系统层面解决不是 SKILL 能处理的。注意遇到 workspace 问题先看日志。大部分平台会把启动过程写到日志文件里卡在哪一步一目了然。盲目重启是最低效的做法。5.3 教学效果不稳定的调优思路SKILL 能跑起来只是第一步跑得好不好是另一回事。教学效果不稳定通常出在三个地方。一是诊断环节被跳过。智能体为了“快”直接进入讲解结果讲的内容和用户水平不匹配。解决办法是在流程里加硬性要求比如“未完成诊断不得进入下一步”。二是拆解粒度不合适。拆得太粗用户还是不懂拆得太细用户觉得啰嗦。这个需要根据诊断结果动态调整。入门用户拆细一点熟练用户拆粗一点。三是检验环节缺失。讲完就结束没有闭环。解决办法是把检验写成必选步骤而且检验结果要反馈到流程里形成循环。我自己的调优习惯是每次用完 SKILL 都记一笔这次哪里好、哪里不好、下次改什么。积累十几条之后SKILL 的质量会有明显提升。5.4 从 teach SKILL 延伸出的通用方法论最后说点更宏观的。teach SKILL 给我的最大启发不是“怎么教”而是怎么把任何专业能力 SKILL 化。这套方法论可以迁移到很多场景。第一步识别重复性决策。你的工作里哪些判断是反复做的比如写代码时的命名决策、做设计时的配色决策、写文档时的结构决策。这些都可以 SKILL 化。第二步显性化隐性知识。把你“凭感觉”做的事情拆成步骤。这一步最难因为很多决策你自己都没意识到。办法是录屏或者写日记观察自己实际怎么做的。第三步设计输入输出。SKILL 要有明确的触发条件和产出格式。触发条件决定什么时候用产出格式决定用得稳不稳。第四步建立反馈循环。SKILL 不是写完就完了要持续观察效果、迭代 description 和流程。热搜里那些ppt skill、会议纪要 skill、论文 skill、科研 skill本质上都是这个方法论的应用。会议纪要 SKILL 的核心是“提取决策项、行动项、待定项”这套流程论文 SKILL 的核心是“文献检索、结构搭建、论证检验”这套流程。流程一旦固化智能体的输出质量就会稳定在一个可预期的水平。MattPocock 把教学做成 SKILL示范的是一种思维方式不要问“智能体能做什么”要问“我希望智能体在什么场景下、按什么流程、产出什么”。想清楚这三个问题你就能写出好用的 SKILL。至于具体用哪个平台、哪个模型反而是次要的。工具会变方法论不会。