Kimi Code CLI 统一 Skills 发现机制KLIP-8深度解析分层合并、目录查找与跨工具兼容【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读本篇以 Kimi Code CLI 的设计提案 KLIP-8: Unified Skills Discovery 为核心结合当前仓库中 Agent Skills 文档 与 Skill 发现源码 的实现完整讲解 Kimi Code CLI 如何发现、合并和加载 Skills。读完本文你将掌握Skills 发现的分层合并 目录查找两级逻辑、用户级与项目级候选目录的精确优先级、--skills-dir与extra_skill_dirs的差异以及merge_all_available_skills配置对品牌目录合并行为的控制并能在自己的项目中正确规划 Skills 目录布局实现与 Claude、Codex 等工具的 Skills 共享。一、背景为什么需要统一 Skills 发现编码 Agent 生态长期处于碎片化状态不同工具Kimi、Claude、Codex 等各自定义了专有的 Skills 目录布局。其结果正如 KLIP-8 Motivation 中所指出的——用户必须为同一份 Skills 维护多份副本或者使用 symlink 技巧才能在多个客户端之间复用。这既增加了维护成本也容易在同步时产生版本漂移。KLIP-8 的目标是统一 Skill 发现机制使其与现有工具兼容让一份 Skill 定义可以无需修改即可被多个编码 Agent 客户端使用。该提案当前状态为Implemented已实现其在仓库中的落地点是 src/kimi_cli/skill/init.py 中整套发现/加载工具以及 docs/zh/customization/skills.md 中的用户文档。设计边界KLIP-8 明确划定了自己的 Scope 与 Non-goals理解这一点有助于区分统一 Skills 发现与 Kimi 自身的配置体系Scope仅包含 Skills 发现mcp.json的标准化留作未来工作不在本 KLIP 范围内。Non-goals明确不做~/.kimi/config.toml等 Kimi 专属配置以及~/.local/share/kimi/数据目录。这些仍然是 Kimi 特有的运行时数据不参与跨工具统一。也就是说统一的是Skills 在哪里被找到这一层而不是把 Kimi 的全部配置体系推倒重来。二、两级发现逻辑分层合并 × 目录查找KLIP-8 提出的 Skills 发现机制由两个正交的维度组成它们共同决定了最终加载到哪些 Skills第一级分层合并Layered Merge不同来源的 Skills 目录按作用域分层加载builtin → user → project 全部加载同名 Skill 由更靠后的层覆盖。这一后层覆盖前层的语义在用户文档中被进一步细化为更具体的作用域优先级Project User Extra Built-in即项目级最优先、内置级优先级最低。分层合并不是只取一层而是每一层都可能贡献 Skills只是当不同层出现同名 Skill 时更具体的层胜出。第二级目录查找Directory Lookup在每一层内部按优先级依次检查候选目录停在第一个存在的目录first existing directory wins。这一查找语义对应源码中的 find_first_existing_dir 实现async def find_first_existing_dir(candidates: Iterable[KaosPath]) - KaosPath | None: for candidate in candidates: if await candidate.is_dir(): return candidate return None两个维度的组合效果用一句话概括两级逻辑的配合每个作用域层内用目录查找确定具体目录多个作用域层之间用分层合并叠加并仲裁同名冲突。值得注意的是KLIP-8 的原始设计中用户层的优先级顺序是~/.config/agents/skills/规范、推荐→~/.kimi/skills/遗留回退→~/.claude/skills/遗留回退项目层是.agents/skills/。当前仓库的实现在此基础上做了演进——详见下一节。三、当前实现中的目录候选与优先级源码级演进对比 KLIP-8 的原始提案当前实现src/kimi_cli/skill/init.py将每个作用域层内部的候选目录拆分成了**品牌组brand group与通用组generic group**两个互斥小组分别查找后合并结果品牌组特异性更高、优先级更高。用户级 Skills用户级目录存放在用户主目录对所有项目生效。源码 find_user_skills_dirs 展示了完整的查找逻辑品牌组互斥选一按优先级~/.kimi/skills/~/.claude/skills/~/.codex/skills/通用组互斥选一按优先级~/.config/agents/skills/推荐 —— 这正是 KLIP-8 指定的canonical目录也是跨工具共享的关键~/.agents/skills/两组分别选出第一个存在的目录后独立合并加载。当同名 Skill 同时存在于品牌组与通用组时品牌组的版本优先因为它特异性更高更接近用户对特定工具的意图。项目级 Skills项目级目录存放在项目内仅在该项目生效。候选路径以项目根为起点——即工作目录向上最近的包含.git的祖先目录找不到.git时回退到工作目录本身。这样即使从 monorepo 的某个子 package 内启动 kimi-cli仓库根目录下的 Skills 也能被正确识别。项目级同样分为两组品牌组互斥选一.kimi/skills/→.claude/skills/→.codex/skills/通用组.agents/skills/项目根的解析在 find_project_skills_dirs 中完成它内部调用 utils/path.py 的find_project_root来定位.git祖先目录。内置 Skills随软件包安装的 Skills 优先级最低。内置目录的解析见 get_builtin_skills_dirPyInstaller 冻结环境下使用_MEIPASS定位打包资源常规环境下指向包内的skills目录。当前仓库内置了两个 Skills见 src/kimi_cli/skills/kimi-cli-helpSKILL.md解答安装、配置、斜杠命令、键盘快捷键、MCP 集成、供应商、环境变量等问题skill-creatorSKILL.md创建或更新 Skill 的指导与最佳实践。KLIP-8 特别强调内置 Skills 仅在 KAOS 后端为LocalKaos或ACPKaos时加载。这一条件对应源码中的 _supports_builtin_skills它检查当前 KAOS 后端名称是否为local_kaos.name或acp因为只有这些后端才能可靠读取随包分发的资源目录。四、--skills-dir与extra_skill_dirs覆盖 vs 追加KLIP-8 规定--skills-dir覆盖用户/项目自动发现仅使用指定目录内置 Skills 在受支持时仍然加载。当前实现忠实地贯彻了这一语义同时额外引入了追加式的extra_skill_dirs配置。--skills-dir覆盖式指定CLI 参数定义见 cli/init.py可重复指定kimi --skills-dir /path/to/my-skills --skills-dir /path/to/more-skills在 resolve_skills_roots 中一旦传入skills_dirs就不再执行用户级与项目级的自动发现仅使用指定的目录但这些目录处于优先级的最顶端其 Skills 优先于其他来源且内置 Skills 在受支持的后端上仍会照常加载——与 KLIP-8 的设计完全一致。extra_skill_dirs追加式声明如果你希望在内置 / 用户级 / 项目级自动发现的基础上追加自定义目录而不是替代它们可在配置文件中设置extra_skill_dirs配置项定义见 config.pyextra_skill_dirs [ ~/my-skills-collection, # ~ 会展开为 $HOME .claude/plugins/my-skills, # 相对路径以“项目根”为基准解析 /opt/team-shared/skills, # 绝对路径原样使用 ]每一项可以是绝对路径、~前缀路径或相对于项目根即 work_dir 向上第一个包含.git的目录的相对路径。不存在的条目会被静默跳过源码中_resolve_extra_skill_dir对不可解析、不可 stat 的条目逐一容错。从这些目录发现的 Skills 在系统提示中归入Extra作用域。两者在优先级中的位置resolve_skills_roots中 Roots 按优先级从高到低排列同名 Skill 由discover_skills_from_roots按首次出现者胜出first wins解析。最终排序为Project User Extra(config) Extra(plugins) Built-in其中--skills-dir指定的目录以extra作用域置于最顶端显式意图优先extra_skill_dirs追加在自动发现的 project/user 之后插件目录plugin/manager.py 的get_plugins_dir也作为extra来源参与但排在配置声明的 extras 之下。五、源码实现剖析从根目录到系统提示作用域标记ScopedSkillsRootScopedSkillsRoot 将Skills 目录与其所属作用域builtin/user/project/extra绑定在一起。作用域标记贯穿整个发现流程最终用于系统提示的分组渲染让模型能区分项目里的 skill与用户级的 skill。去重与规范化resolve_skills_roots内部的_append对每个根目录做去重先对本地后端做Path.resolve()解析 symlink再做KaosPath.canonical()规范化..与尾部斜杠从而避免 symlink、..段或尾部斜杠造成系统提示中出现幽灵重复条目。单目录内的两种 Skill 形态discover_skills 在一个 Skills 目录内并行支持两种布局子目录形式canonicalskills_dir/name/SKILL.md扁平.md形式skills_dir/name.mdname默认取文件名去掉.md适合从其他用扁平 Markdown 存 Skills 的工具迁移的用户。两遍扫描分别处理两种形态第一遍收集子目录形式第二遍收集扁平形式并跳过已被子目录占用名字的条目若同名冲突子目录胜出并记录警告日志。位于目录顶层的裸SKILL.md会被视为游离标记文件而非 Skill。description 的三级解析链无论子目录还是扁平形式parse_skill_text 对每个 Skill 的description走同一条链Frontmatter 的description:字段推荐遵循 SKILL.md 规范正文第一个非空行回退超过 240 字符截断并追加省略号见_DESCRIPTION_FALLBACK_MAX_LENNo description provided.兜底。系统提示中的分组渲染format_skills_for_prompt 将发现的 Skills 按作用域分组注入系统提示输出布局如下### Project - name - Path: skill_md_file - Description: description ### User - ...空分组不渲染。分组顺序固定为 Project → User → Extra → Built-in与作用域优先级一致让模型在回答项目里的 skill这类问题时能准确区分来源。六、merge_all_available_skills品牌目录合并策略KLIP-8 的原始设计是每层内停在第一个存在的目录而当前实现在此基础上提供了更灵活的品牌目录合并策略由配置项merge_all_available_skills控制定义见 config.py默认true合并所有存在的品牌目录kimi / claude / codex同名 Skill 按 kimi claude codex 的优先级解析通用组不受影响。这样在多个品牌目录中都维护了 Skills的用户开箱即用就能看到全部内容设为false恢复旧的仅取优先级最高的那个品牌目录行为——只使用 kimi缺失时回退到 claude再缺失时回退到 codex。# 默认值合并所有已存在的品牌目录 merge_all_available_skills true # 恢复 first-match-only 行为 merge_all_available_skills false该配置对用户级与项目级 Skills 同样生效对应 find_user_skills_dirs 与 find_project_skills_dirs 中的merge_brands参数为True时逐个检查并收集所有存在的品牌目录为False时仅取第一个存在的目录。七、测试验证行为即契约仓库的 tests/core/test_skill.py 完整覆盖了上述发现语义是理解first wins与分组优先级的最佳佐证test_discover_skills_from_roots_prefers_earlier_dirs/test_discover_skills_from_roots_first_wins验证同名 Skill 出现在多个根目录时更早更高优先级的根目录胜出test_find_user_skills_dirs_empty_generic_does_not_shadow_brand验证通用组为空时不会遮蔽品牌组结果test_find_user_skills_dirs_only_brand/test_find_user_skills_dirs_only_generic验证品牌组与通用组独立查找、互不干扰test_discover_skills_parses_frontmatter_and_defaults/test_discover_skills_parses_flow_type验证 Frontmatter 解析、name/description 默认值与flow类型解析以及 flow 解析失败时回退为standard的容错行为。这些测试同时印证了 tests/core/test_config.py 中merge_all_available_skills与extra_skill_dirs的配置默认值true与空列表。八、实战在项目中规划 Skills 目录综合 KLIP-8 设计与当前实现推荐的 Skills 布局策略如下跨工具共享的团队规范放在通用组~/.config/agents/skills/或.agents/skills/——这是 KLIP-8 推崇的 canonical 位置Kimi、Claude、Codex 均可直接发现无需复制或 symlink特定工具的个性化 Skills放在品牌目录如~/.kimi/skills/、.kimi/skills/利用品牌组特异性在冲突时优先团队私有仓库通过extra_skill_dirs追加例如/opt/team-shared/skills让所有成员共享一份只读规范临时或隔离的测试使用--skills-dir覆盖自动发现确保只加载你指定的目录单个 Skill 采用name/SKILL.md子目录结构Frontmatter 至少声明name与description正文控制在 500 行以内细节内容放入scripts/、references/、assets/子目录。需要特别注意Skills 路径独立于KIMI_SHARE_DIR。KIMI_SHARE_DIR只影响配置、会话、日志等运行时数据的存储位置不影响 Skills 搜索路径——因为 Skills 是跨工具共享的能力扩展与应用运行时数据是不同类型的数据。如需自定义 Skills 路径请使用--skills-dir参数或extra_skill_dirs配置。结语KLIP-8 用两个简洁的原则——分层合并与目录查找——解决了编码 Agent 生态中 Skills 布局碎片化的问题使同一份 Skill 可以被多个工具直接使用。当前仓库不仅完整实现了提案中的两级发现逻辑还演进出了品牌组/通用组分组、merge_all_available_skills合并策略与extra_skill_dirs追加机制并通过 tests/core/test_skill.py 将first wins与作用域优先级固化为契约。深入理解这套机制你就能在 Kimi Code CLI以及兼容的 Claude、Codex 等工具之间优雅地共享、分层管理 Skills彻底告别复制与 symlink 维护。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
