Kimi Code 内置 sub-skill 技能：Skill 技能库的分层重组与归档指南

AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载sub-skill是 Kimi Code CLI本仓库packages/agent-core-v2内置的一组容器型技能用于对本地技能清单进行审查、分组与重组把零散的技能整理为has-sub-skill: true父技能 子技能的分层结构。通过阅读本文你将掌握子技能分层机制has-sub-skill/isSubSkill的底层发现逻辑以及sub-skill.review只读提案与sub-skill.consolidate备份后落地两个子技能的完整操作流程能够在实际项目中安全地归档与整理技能库。背景为什么需要子技能分层随着 Agent 工作区中积累的技能Skill越来越多技能清单会变得杂乱存在大量松散相关、职责重叠的技能单条技能过于细粒度例如一个 CLI 标志一个技能或某些技能过于宽泛无法归入任何单一领域。sub-skill技能正是为解决这类问题而设计的当用户要求审查、重组或整合技能时当存在许多松散相关、可能受益于分层归组的技能时当用户想评估一个新技能是否应当成为某个现有技能的子技能时。该技能的前置元数据packages/agent-core-v2/src/features/skill/catalog/builtin/sub-skill/SKILL.md声明了disable-model-invocation: true与has-sub-skill: true前者表示它只能由用户主动触发模型不能自行调用后者表示它本身是一个允许承载子技能的分层父技能。技能分层机制的源码实现子技能分层并不是一个纯文档约定而是由技能发现discovery逻辑真实驱动的。在 fileSkillDiscovery.ts 中hasSubSkillEnabled()会同时识别has-sub-skill与hasSubSkill两种写法并兼容嵌套在metadata字段内的写法function hasSubSkillEnabled(skill: SkillDefinition): boolean { const nested skill.metadata[metadata]; const nestedFlag typeof nested object nested ! null ? (nested as Recordstring, unknown)[has-sub-skill] true || (nested as Recordstring, unknown)[hasSubSkill] true : false; return ( skill.metadata[has-sub-skill] true || skill.metadata[hasSubSkill] true || nestedFlag ); }在目录遍历逻辑中fileSkillDiscovery.ts发现器会先扫描当前目录下每个含SKILL.md的子目录凡是hasSubSkillEnabled为真的目录被记入allowedSubSkillBundles随后递归子目录时只有本身就是子技能包或位于子技能包内部的目录才会被继续深入扫描子技能名称会通过qualifySubSkillName规范为父技能名.子技能名的形式如sub-skill.review。runtimeSkillDiscovery.ts中实现了等价逻辑runtimeSkillDiscovery.ts保证运行态下的技能注册与磁盘发现行为一致。对应地isSubSkill: true会被写入子技能的元数据见 types.ts 中的isSubSkill字段并在summarizeSkill中随摘要暴露给上层使用。三个内置技能的注册位于 sub-skill.ts父技能sub-skillbuiltin://sub-skill带has-sub-skill: true两个子技能sub-skill.review与sub-skill.consolidate带isSubSkill: true全部disable-model-invocation: true。它们经由 builtin.ts 的BUILTIN_SKILLS列表进入内置技能目录。技能的 frontmatter 解析由 parser.ts 完成支持when-to-use、disable-model-invocation等连字符写法的别名归一化目录型技能SKILL.md要求name与description为必填字段否则抛出SkillParseErrorparser.ts。两个子技能的分工sub-skill容器技能下挂两个子技能构成先提案、后执行的两阶段工作流sub-skill.review—— 分析当前技能清单提出候选的子技能分组方案。只读只产出提案不移动任何文件。sub-skill.consolidate—— 在用户批准分组方案后执行重组把指定技能移入父技能包并对每个被修改的目录做带时间戳的备份。推荐流程固定为先运行sub-skill.review得到只读提案用户在确认方案后再运行sub-skill.consolidate。没有用户明确授权绝不运行 consolidate。第一步sub-skill.review只读审查与提案对应文档review/SKILL.md适用场景用户要求审查、重组或审计技能清单存在大量松散相关、适合分层归组的技能用户想评估新技能是否应作为现有父技能的子技能。执行流程列出当前清单通过技能注册表或扫描配置的技能根目录获取全部技能的名称、描述与来源范围按领域归类按功能领域分组例如文件操作、Web 工具、协作、可观测性等检测耦合识别经常一起使用、或共享相似whenToUse条件的技能标记粒度问题指出过于细粒度如一个 CLI 标志一个技能或过于宽泛、无法归入任何单一领域的技能提出子技能结构对每个候选分组列出——父技能名称及一行描述应移入其下的子技能每个子技能必须随行的文档、参考、示例、资源或模板目录保证最终目录布局对齐父技能是否需要has-sub-skill: true若希望子技能被发现则需要输出汇总报告以精简分组列表 理由的形式呈现发现然后停止。不修改任何文件—— 那是sub-skill.consolidate的职责。良好分组的判断标准共享上下文子技能处于同一领域或同一工作流内可组合的入口父技能提供自然的顶层入口子技能处理具体细节浅层嵌套优先 2 层父 → 子除非确有必要避免 3 层及以上向后兼容已有技能名称应尽可能保持可被发现从源码看qualifySubSkillName会保证父.子命名下原名称的连续性。提案输出示例Proposed sub-skill: web-research - Parent: web-research (has-sub-skill: true) - Children: - web-search → move under web-research/search - fetch-url → move under web-research/fetch - Documentation alignment: move each childs references/examples/assets with that child. - Rationale: Both deal with online information retrieval and are often chained together.第二步sub-skill.consolidate备份后落地重组对应文档consolidate/SKILL.md适用场景用户已批准分组提案通常来自sub-skill.review并希望落地将独立技能迁移进新建或已有的父技能包。执行流程确认方案在任何文件改动之前复述将要移动的技能及目标位置并请用户确认备份每个原始技能目录移动之前为每个将被修改的技能目录创建带时间戳的备份。对于位于root/skill-name/SKILL.md的技能备份整个skill-name目录cp -r skill-name skill-name.$(date %Y%m%d-%H%M%S).bak保留全部备份绝不覆盖已有备份文件创建或更新父技能包若父技能不存在创建parent-name/SKILL.md并在 frontmatter 中加入has-sub-skill: true若父技能已存在确保其 frontmatter 包含has-sub-skill: true这一点由 fileSkillDiscovery.ts 的子技能包准入逻辑强制要求否则子技能不会被发现将子技能移入父技能包把每个子技能的整个目录移到父技能包下例如web-search/→web-research/web-search/保持文档目录对齐移动文档、参考、示例、资源或其他载荷目录时必须与新技能目录布局对齐。保留SKILL.md到references/、assets/、examples/或模板等文件的相对链接子技能从root/child/移到root/parent/child/时其文档载荷应随子技能一起移动除非批准的方案另有约定不得把文档留在旧位置也不得把无关文档目录合并到一起验证结果列出新目录结构确认每个被移动的技能仍有合法的SKILL.md且包含必需 frontmattername与description检查移动后的文档目录对齐与相对链接汇报变更总结移动了哪些内容、新结构、随行的文档目录以及备份所在位置。明确的禁止项Donts绝不未经备份就移动技能绝不覆盖已有备份—— 始终使用全新的时间戳后缀移动时不得丢弃 frontmatter 或载荷文件—— 整个目录必须完整保留这与 fileSkillDiscovery.ts 按目录识别SKILL.md的机制一致目录被破坏会导致技能无法被发现不得破坏文档目录对齐—— references、assets、examples、模板必须与被使用它们的技能目录保持对齐不要创建深层嵌套3 层及以上除非用户明确要求。与技能调用机制的关系两个子技能均声明disable-model-invocation: true因此在运行时模型无法自行触发。这一限制由技能工具执行层强制在 skillTool.ts 中若目标技能的disableModelInvocation为真工具会直接返回Skill xxx can only be triggered by the user (model invocation is disabled).。这意味着技能库的审查与重组始终是由用户驱动的受控操作符合重组前必须有用户明确授权的安全设计。同时技能调用遵循嵌套查询深度限制MAX_SKILL_QUERY_DEPTH见 skillTool.ts深层嵌套技能会抛出NestedSkillTooDeepError—— 这也是review建议保持 2 层浅嵌套的原因之一。实操要点小结重组前先跑sub-skill.review拿只读提案批准后再跑sub-skill.consolidate父技能 frontmatter 必须含has-sub-skill: true支持hasSubSkill别名否则子技能不会被发现每个目录型SKILL.md必须保留name与description两个必填字段否则解析失败并被跳过移动前务必用date %Y%m%d-%H%M%S时间戳备份整个技能目录且永不覆盖旧备份文档、参考、示例、资源目录必须随所属子技能同步移动保持相对链接有效保持 2 层浅嵌套尊重disable-model-invocation的用户驱动边界。赞分享AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载相关推荐OpenScreen 免费屏幕录制工具教程从录屏到演示视频的完整流程OpenScreen 免费屏幕录制工具教程从录屏到演示视频的完整流程 用录屏做产品演示难的不是按下录制键而是后面的事付费的演示视频工具按月收费纯录屏软桌面应用音视频视频处理屏幕录制Open Interpreter 的 check-kimi-code-docs以“文档优先”回答 Kimi Code 产品问题的内建 SkillOpen Interpreter 的 check kimi code docs以“文档优先”回答 Kimi Code 产品问题的内建 Skill check人工智能大模型AI Agent代码智能体AI 应用CLISkill Seekers Bootstrap Skill 技术深度解析用工具分析自身代码库生成 Claude Code 技能Skill Seekers Bootstrap Skill 技术深度解析用工具分析自身代码库生成 Claude Code 技能 本文基于 docs/featu人工智能AI 应用AI 技能RAGMCP 服务网页爬虫上一篇Wasp 用户名与密码认证从声明式配置到登录注册全流程实战下一篇Key Findings创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考