OMC - 12 把 Claude Code 变成「可编程开发同事」：oh-my-claudecode 技能系统深度解析

Pre

OMC - 01 用 19 个 Agent 打造你的 Claude Code“工程团队”：oh-my-claudecode 深度解析与实战指南

OMC - 02 五分钟起步，走向多智能体协作：深入解析 oh-my-claudecode 快速开始与架构设计

OMC - 03 从 0 到高效：Oh My ClaudeCode 安装与实践全指南

OMC - 04 用好 Oh-My-ClaudeCode 的 30 个会话技能：从“帮我写点代码”到端到端自动交付

OMC - 05 从单人到多 Agent：Oh-my-claudecode 的插件架构解析

OMC - 06 从“大模型管家”到“十九人专家团队”：oh-my-claudecode 的多 Agent 工程实践

OMC - 07 把「选模型」当成一门工程学：oh-my-claudecode 的三层模型路由实践

OMC - 08 在多 Agent 时代，如何优雅地「分工协作」：oh-my-claudecode 委托分类体系深度解读

OMC - 09 oh-my-claudecode 的多 Agent 编排实战

OMC - 10 从创意到“免看管生产力”：深入解析 Oh-My-ClaudeCode 的 Autopilot 与 Ralph 模式

OMC - 11 跨供应商 CCG 合成：让 Claude、Codex、Gemini 一起给你“做代码评审”

在现代 AI 开发工作流里，一个大模型助手能不能真正“懂项目、懂上下文、懂团队协作”，关键不在模型本身，而在于你如何给它“长技能”。oh-my-claudecode 的技能系统，正是围绕这个目标设计的一套可扩展编排层：用 Markdown 定义技能、用触发器激活技能、用 Hook 管道把技能注入到对话上下文中，从而把 Claude Code 从一个通用助手，升级为一个具备项目记忆、工具链意识和团队分工的开发编排器。

本文面向有一定实践经验的开发者、研究人员和技术爱好者，系统拆解这一技能系统的架构、实现细节和使用方式，并结合实践视角讨论如何把它当作自己的“可编程开发同事”。

一、技能系统到底解决了什么问题？

在真实的开发场景中，单次对话的“聪明”远远不够，更关键的是：

• 能不能复用前人踩过的坑和经验，沉淀成可调用的工作流
• 能不能像团队协作一样，把复杂任务拆成有边界、有接口的阶段
• 能不能在不同项目、不同人之间，复用一套行为标准和最佳实践

oh-my-claudecode 的技能系统围绕这些痛点做了几件事：

1. 把“如何做”抽象为技能模板
   每个技能是一个带 YAML 前置元数据的 Markdown 文件，既描述“什么时候触发、交给谁做、怎么接力”，又包含具体的操作指南和行为约束。

2. 通过三阶段管道自动注入合适技能
   当用户输入提示词时，先跑关键词检测器处理内置技能，再由技能注入器对项目级、用户级技能做模糊匹配和会话去重，最后把最相关的技能内容注入到 Claude 的上下文。

3. 用作用域和优先级管理“谁说了算”
   同一个技能名在项目、Agent、用户、内置四个层级都可以定义，但真正生效的总是“越靠近当前项目和场景的那一个”。

4. 支持自我学习和工作流固化
   Learner 和 Skillify 可以从真实对话里提取难得一见的专业经验和可复用工作流，自动生成新的技能文件，逐步把系统变成一个越来越懂你的开发伙伴。

从使用者角度看，这套技能系统更像是“为大模型设计的一套插件框架”，但这个插件不是代码，而是高度结构化的提示工程资产。

二、整体架构：三阶段技能注入管道

技能系统的核心是一条挂在UserPromptSubmitHook 上的三阶段管道：每次你在 Claude Code 里敲下回车，它都会完整跑一遍。

1. 触发链路总览

流程可以概括为：

1. 用户提交 prompt（携带 session_id、工作目录 cwd 等信息）。
2. keyword-detector 脚本在 5 秒超时内运行，使用硬编码正则扫描是否命中内置技能关键词。
3. 若命中，则直接从skills/目录加载对应SKILL.md文件，作为 additionalContext 注入模型。
4. skill-injector 脚本随后在 3 秒超时内运行，从项目、用户技能目录中递归扫描技能文件，通过 TypeScript 编译的 bridge 模块做模糊匹配、会话去重和打分排序。
5. 得分最高的前 5 个技能以 additionalContext 形式附加到模型调用中。

整个过程对用户几乎是“无感”的，但对模型来说，这是一次“带着技能上阵”的上下文增强。

2. keyword-detector：专管内置技能

关键词检测器主要特点：

• 只处理内置技能（即插件随包发布、只读的那一批），存放在插件根目录的skills/<skill-name>/SKILL.md。
• 用硬编码正则表达式匹配关键词，例如"autopilot"、"deep interview"、"ultrawork"、"deslop"等。
• 命中后直接从磁盘加载SKILL.md内容，绕过了后面的 TypeScript bridge 和复杂注入逻辑，保证鲁棒性与性能。

这意味着：即便后续注入器或桥接模块有问题，基础的 autopilot 这类关键能力仍然可以依靠关键词触发正常工作。

3. skill-injector：负责“学习来的”和项目级技能

技能注入器则面向用户自定义、自动学习和项目内的技能，职责包括：

• 调用编译后的skill-bridge.cjs，执行递归目录扫描和元数据加载。
• 基于技能的matching、triggers等前置元数据，结合用户当前 prompt 做精确+模糊打分。
• 对同一会话做去重控制，一小时内防止同一技能反复注入刷屏。
• 最终把选中的技能串成 additionalContext，交给 Claude 执行。

这两级处理叠加起来，形成了一套“默认内置 + 项目可扩展 + 用户可个性化”的统一技能注入机制。

三、技能作用域与存储：谁离问题最近，谁说了算

为了支持项目、个人、Agent 等不同粒度的定制，技能被划分为多个作用域，每个作用域有自己的存储路径、可变性和优先级。

1. 作用域一览

以下是各作用域的关键差异：

几个重要设计点：

• 优先级从近到远：优先使用项目级技能，其次是 Agent 级、用户级，最后才是内置技能。
• 全部支持版本控制：除了内置技能，只要路径落在项目目录内，就可以纳入 git 管理，方便多人协作审查和回滚。
• 向后兼容旧路径：保留~/.omc/skills，避免老版本升级时出现能力“消失”的情况。

2. 递归发现与安全约束

技能文件的发现由 bridge 模块负责，其findSkillFiles()做了几件事：

• 支持深度最多 10 层的递归扫描，兼顾嵌套结构与性能。
• 使用realpathSync解析符号链接，对比真实路径去重，防止同一文件通过多个符号链接被重复计数。
• 做目录边界检查，防止利用符号链接或路径穿越从项目目录逃逸到系统其他位置，降低安全风险。

这一层设计让“用 Markdown 写技能”这件事既简单，又不至于引入不必要的漏洞面。

四、技能文件结构：用一个 Markdown 定义行为、触发与管道

每个技能都是一个 Markdown 文件，但并不是随便写写说明，而是有严格的结构规范。

1. YAML 前置元数据：技能的“身份证”

文件以 YAML frontmatter 开头，大致形态如下：

***name:skill-namedescription:Brief description of what this skill doestriggers:-"keyword1"-"keyword2"argument-hint:" [optional-arg]"level:4agent:executor# 可选：偏好的 Agentmodel:sonnet# 可选：模型覆盖matching:fuzzy# 可选："exact" 或 "fuzzy"pipeline:[step-a,step-b]# 可选：多技能 pipelinenext-skill:follow-up# 可选：显式交接目标next-skill-args:--direct# 可选：传给后继技能的参数handoff:.omc/plans/foo.md# 可选：交接的制品路径***

关键字段含义：

• name / description：技能标识与简要说明。
• triggers：触发短语列表，既用于关键词匹配，也用于模糊匹配打分。
• matching：exact仅做子串匹配，fuzzy则启用 Levenshtein 相似度，容忍拼写错误或近似表达。
• agent / model：指明优先使用哪个 Agent 和模型，例如把重活交给更强的模型。
• pipeline / next-skill / handoff：为技能之间的接力提供结构化元信息，后文详述。

YAML 之后的所有内容都会被视作技能的“提示模板”，在注入时原样进入 Claude 的上下文。

2. 正文结构：既给模型看，也给人看

正文推荐使用两类结构之一：

• XML 风格语义标签（如<Purpose>、<Workflow>、<Config>等）
• 普通 Markdown 标题结构（如# Purpose、# Workflow、# Configuration）

这使得同一份内容同时满足两个目标：

• 对人类开发者足够可读，方便审查与维护；
• 对模型来说结构清晰，易于解析成“任务目标 + 步骤 +约束条件”。

3. 精确匹配与模糊匹配

matching字段直接影响桥接模块如何计算技能与当前 prompt 的相关性：

• exact（默认）：只要 prompt 中包含任意一个 trigger 作为子串，就认作命中，并给对应技能增加固定加分。
• fuzzy：基于 Levenshtein 距离，对 prompt 中拆分出的每个单词与 trigger 比较，计算相似度，提供 0～100 的得分，再折算纳入总分。

为了性能，模糊匹配还配有一个 LRU 缓存，最多缓存 1000 个键值对，键使用规范化排序避免重复计算。

这一套设计的本质，是在不要求用户死记硬背命令名的前提下，让系统尽可能“猜出你想要哪个技能”。

五、内置技能家族：从执行模式到自我提升

oh-my-claudecode 自带 30 多个内置技能，并按功能分为多个类别。

1. 内置技能分类概览

几个重要例子：

• autopilot：典型执行模式技能， orchestrate 一个 6 阶段生命周期：扩展 → 规划 → 执行 → QA → 验证 → 清理，将复杂需求拆成可验证的阶段。
• ultrawork：强调最大化并行执行，专为大规模任务设计。
• ralph：强调“不停下直到验证通过”的循环模式，适合需要持续改进的任务场景。
• ai-slop-cleaner：用于“去 AI 味”，把粗糙或啰嗦的内容清理成更严谨、更人类风格的输出。
• cancel：通过关键词快速中断当前长流程，避免 autopilot 这类长任务“跑飞”。

对使用者来说，理解这几个代表型技能的职责，大致就把握住了整个系统的行为基调。

六、技能注入生命周期：快、稳、可控

当用户提交 prompt 时，技能注入器按固定顺序完成一次“筛技能、加上下文”的过程。

1. 生命周期关键步骤

注入过程的核心步骤包括：

1. 从 stdin 接收 prompt、session_id、cwd 等上下文信息。
2. 加载技能元数据缓存（项目维度，TTL 30 秒）以避免每轮都读文件系统。
3. 读取会话去重状态，过滤掉上次已经注入过、且未过期的技能。
4. 对所有候选技能按照以下策略打分：
   • 精确子串匹配每次贡献固定加分（例如 +10 分）。
   • 若技能启用模糊匹配，则以 Levenshtein 相似度按比例贡献额外得分。
5. 按得分降序排序，取前 5 个技能。
6. 更新会话去重状态，将本轮注入的技能路径记录到.omc/state/skill-sessions.json，并清理超过一小时的历史记录。
7. 将选中的技能文本合并为 additionalContext，交给 Claude。

整个过程被严格限制在 3 秒之内完成，以免拖慢主对话的响应时间。

2. 三重性能优化

为了防止注入器成为瓶颈，系统额外做了三层优化：

• 技能元数据缓存：以项目根目录为键，缓存解析后的技能元数据 30 秒，减少反复加载 YAML 的开销。
• Levenshtein LRU 缓存：模糊匹配结果缓存到一个上限为 1000 条的 LRU 容器，避免热点触发词被频繁重复计算。
• 会话级去重：用 JSON 状态文件持久化{sessionId → {injectedPaths, timestamp}}映射，在一小时窗口内避免重复注入同一技能。

这在工程上有个关键背景：每次UserPromptSubmit都会启动一个新的 Node.js 进程，进程内存天然无法跨轮次复用，因此必须依靠文件持久化和轻量缓存来维持“会话记忆”。

七、模糊匹配与国际化：让技能理解你的自然表达

如果技能只能被“死命令”触发，那对于非英文母语用户、或者喜好自然语言表达的开发者来说，体验会大打折扣。技能系统在匹配层做了两点扩展。

1. Levenshtein 模糊匹配

当技能将matching设为fuzzy时，桥接模块会对 trigger 与 prompt 内容做逐词匹配：

• 精确单词匹配得分 100，子串包含得分 80。
• 对拼写错误或近似词，基于 Levenshtein 距离计算一个 0～100 的相似度得分。
• 对于一个技能的所有触发器，把命中的得分按一定规则累加，精确匹配提供额外固定加分，模糊匹配则按分值折算。
• 最终与其他技能一同排序，决定是否进入前 5。

这意味着你即使打错字或用类似表达，比如 “deep dive” 写成 “deep dvi”，相关技能仍有较大概率被正确激活。

2. 韩语音译支持

在模糊匹配之外，系统还嵌入了一套韩语音译映射表，用于扩展触发器：

• transliteration-map.ts中维护从英文触发短语到对应韩语外来词的映射，例如"deep dive" → "딥다이브"。
• 在 bridge 初始化时一次性加载并扩展 trigger 列表，对运行时性能没有明显影响。
• 映射只针对外来词音译，刻意避免韩语原生词，降低误触发概率。

从设计哲学上看，这相当于在技能层内置了国际化支持的“插槽”，后续也可以扩展到其他语言的类似音译映射。

八、自我改进：Learner 与 Skillify 如何把经验固化成技能

一个真正“越用越聪明”的系统，不能只依靠人手写技能，还需要从真实使用中学习。Learner 和 Skillify 正是负责这条闭环。

1. Learner：提炼难得一见的专业知识

/oh-my-claudecode:learner的定位，是从当前对话中提取难以从搜索引擎获得的、项目特定的专业知识：

• 在提取之前使用严格的门槛规则：
  • 信息必须难以在 Google 上直接搜到。
  • 必须强绑定当前代码库或系统架构。
  • 必须是“来之不易”的经验，而不是基础知识。
• 区分两类抽取对象：
  • 专业知识：特定领域、项目的知识点、陷阱、模式。
  • 工作流：完成某个任务的操作步骤、工具组合和顺序。
• 两种类型以不同后缀保存，方便后续独立演进和组合使用。

其输出是一个格式完备的技能 Markdown 文件，立刻可以被 skill-injector 发现并参与后续匹配。

2. Skillify：封装完整的工作流

相较之下，/oh-my-claudecode:skillify更偏向“把一个成功的多步流程打包成技能”：

• 捕获的内容包括：
  • 输入条件
  • 有序步骤
  • 成功标准
  • 关键约束
  • 已知陷阱和边界情况
• 产出是技能草稿，包含完整 YAML 前置元数据和结构化正文，供人工审阅与微调。

可以这么理解：Learner 专注于提炼“一个重要洞见”，Skillify 则封装“一条完整路线图”。两者结合，可以持续把项目演进过程中的隐性知识变成显性的、可被复用的技能资产。

九、用元技能管理技能：/oh-my-claudecode:skill

为了避免手动在文件系统里翻找、复制和编辑 Markdown 文件，系统提供了一个专门的管理元技能/oh-my-claudecode:skill。

1. 四大子命令

该元技能提供四个核心子命令：

list 命令会明确标出哪些是内置技能（只读），哪些是项目或用户技能（可编辑、可删除），避免误改系统核心能力。

2. 命名与存储约定

为了在文件系统层保持一致性，这个元技能还 enforce 了一套命名与路径规范：

• 技能名称全部小写，并使用连字符分隔，例如deep-interview、ai-slop-cleaner。
• 用户技能存放在~/.claude/skills/omc-learned/<name>/SKILL.md，项目技能存放在.omc/skills/<name>.md或对应子目录下。
• 由 Learner 自动生成的技能既可以是扁平文件，也可以是嵌套目录，递归扫描都会被发现。

这一层“轻约束”既方便人脑快速识别技能，又让工具脚本能在约定位置可靠地找到目标文件。

十、技能链接与多阶段管道：像搭流水线一样搭技能

单个技能解决的是局部问题，而复杂任务往往需要多个阶段协作。技能系统支持通过管道把多个技能按顺序或条件组合起来。

1. 三种链接方式

技能之间的链接由以下三个前置元数据字段驱动：

• pipeline：一个技能名数组，表示推荐的后续步骤序列。
• next-skill：明确指定当前技能完成后应该交接给哪个技能。
• handoff：指定交接制品的路径，比如.omc/plans/foo.md，用于在技能间传递结构化成果。

当这些字段存在时，系统会在技能提示内容末尾附加一个标准化的“管道交接块”，帮助模型显式理解“接下来该由谁接手、接什么东西”。

2. 典型三阶段管道示例

官方给出的典型管道是一个三阶段链路：

1. /deep-interview：用苏格拉底式问答澄清需求，把歧义降低到 20% 以下。
2. /ralplan --direct：由 Planner / Architect / Critic 三方协作产出一个经过共识的计划。
3. /autopilot：接收上一步规划结果，跳过扩展和规划阶段，直接进入执行 → QA → 验证 → 清理环节。

这个模式的几个关键优势：

• 每一个阶段都产出一个可审查、可重放的制品文件（如 plan 文件）。
• 下游技能直接消费上游制品，减少重复沟通和信息损失。
• 质量门控是层层递进的，而不是在每个阶段重新开始。

对于构建复杂自动化工作流的团队来说，你可以围绕这种三阶段模式设计自己的“项目模板管道”，比如“需求澄清 → 设计评审 → 自动实现 → 自动测试 → 文档生成”等。

十一、自动激活触发器：让技能在正确的时间自动跳出来

除了主动用斜杠命令调技能，系统还内置了一套关键词触发机制，让一些关键技能在检测到特定语言模式时自动激活。

1. 触发配置示例

关键词检测器维护了一个按优先级排序的触发表，部分示例如下：

优先级从具体到模糊，避免多个技能同时抢占触发权。

2. 内置技能的“直通车”

对于这些内置技能，触发器有一个特点：

• 直接读取skills/<name>/SKILL.md，不经过 bridge 与注入器。
• 这让从 npm 或插件市场安装的版本都能无缝运行，不依赖项目内的构建流程。

从工程实践的角度看，这是一种“关键能力低耦合”的设计：即便你的项目没有正确构建 TypeScript bridge，至少 autopilot、cancel 之类的核心命令仍然可用。

十二、技能桥接的构建与降级策略

skill-bridge 是链接脚本世界（Node.js）与技能配置世界（Markdown / YAML）的关键组件，它本身也有一套构建与降级策略。

1. 构建流程

bridge 源码位于src/hooks/learner/bridge.ts，通过scripts/build-skill-bridge.mjs使用 esbuild 编译成一个独立的 CJS 包dist/hooks/skill-bridge.cjs：

• 入口文件：src/hooks/learner/bridge.ts。
• 输出格式：CJS，方便通过require()在 Node.js 脚本中直接加载。
• Node.js 内置模块被标记为 external，避免被打包进输出文件。

技能注入器在启动时会优先尝试require('../dist/hooks/skill-bridge.cjs')，有则用之。

2. 优雅降级：fallback 模式

如果构建产物不存在（例如首次克隆仓库尚未构建，或者dist/目录被清理），注入器会自动回退到内联实现：

• 使用简化版的目录扫描逻辑。
• 使用更简单的 YAML 解析方法。
• 把会话去重信息写入.omc/state/skill-sessions-fallback.json。

尽管功能稍有缩水，但整个注入流程不会崩溃，保证系统在“构建还没跑完”的情况下也能提供基本能力。

结语：如何在自己的项目中用好技能系统？

如果用一句话概括 oh-my-claudecode 的技能系统，它是一套用 Markdown 和少量脚本，就能为大模型定义「角色、流程和记忆」的轻量级框架。

对开发者而言，可以从以下几个方向尝试实践落地：

1. 先用好内置执行模式
   掌握 autopilot、ralph、ultrawork 等执行模式技能，把日常重复性的开发任务交给它们，让它们变成可靠的“自动流水线”。

2. 围绕项目沉淀定制技能
   在.omc/skills中为每个仓库定义项目专属技能，将团队约定、架构惯例、代码风格统一写进技能模板，由技能系统帮你在每次对话中自动“提醒和纠偏”。

3. 用 Learner / Skillify 把经验“收集起来”
   当某次 Debug 或架构讨论产出了重要洞见时，不要只留在聊天记录里，尝试用 Learner 或 Skillify 把它抽取成技能，交给未来的自己和团队成员复用。

4. 尝试设计自己的技能管道
   仿照 deep-interview → ralplan → autopilot 的三阶段模式，为常见任务（如“从需求到上线”）设计具有明确交接物的技能链，把整条开发链路标准化。

从工具化的视角看，这是一个“把经验和流程资产化”的系统；从团队协作的视角看，它则是一套把“项目知识”内建到 AI 助手中的方法论。只要愿意多花一点时间写 Markdown 和 YAML，就能让 Claude Code 更像一位真正懂项目、懂团队的资深同事，而不是一个永远从零开始的问答机器人。