# 问题反馈：插件技能的附属文档被误注册为独立技能

[franciewang]

What version of Kimi Code is running?

0.29.0（macOS）

Which open platform/subscription were you using?

Kimi Code (OAuth)

Which model were you using?

No response

What platform is your computer?

No response

What issue are you seeing?

问题反馈：插件技能的附属文档被误注册为独立技能

• 反馈日期：2026-07-24
• Kimi Code CLI 版本：0.29.0（macOS）
• 涉及功能：插件（Plugins）的技能加载

一句话描述

插件清单 skills 字段只注册了 22 个技能，但会话中实际出现约 43 个技能——Kimi Code 把技能目录内的附属参考文档（如 teach/GLOSSARY-FORMAT.md）也识别并注册成了独立技能。

环境与实践方式

• 插件：mattpocock-skills（https://github.com/mattpocock/skills 的本地克隆）
• 清单位置：<plugin_root>/.kimi-plugin/plugin.json
• 安装方式：/plugins install <本地路径>（installed.json 中 source: "local-path"），随后 /reload
• 清单 skills 字段显式列出 22 个技能目录，形如：

"skills": [
  "./skills/engineering/ask-matt",
  "./skills/engineering/tdd",
  "./skills/productivity/teach"
]

现象

清单中注册了 22 个技能，但会话的技能列表中明显多于此数。多出的条目是各技能目录下的附属 Markdown 文件，例如 teach 技能目录中的 GLOSSARY-FORMAT.md 被注册为名为 GLOSSARY-FORMAT 的技能。

这些附属文件均为纯参考文档（被 SKILL.md 引用查阅），没有任何 YAML frontmatter，按 flat-form 规则被以"文件名作技能名、正文首行作 description"的方式注册。

复现步骤

1. 构造一个插件，其中某个技能目录同时包含：
   • SKILL.md（目录式技能主文件，含合法 frontmatter）
   • 一个或多个附属参考文档，如 GLOSSARY-FORMAT.md（无 frontmatter）
2. 在清单 skills 字段中指向该技能目录，如 "./skills/teach"
3. /plugins install <路径> → /reload → 新会话查看技能列表
4. 预期：只出现 teach 一个技能；实际：teach 与 GLOSSARY-FORMAT 等附属文档都出现在技能列表中

根因分析（推测）

官方技能文档对目录式（directory form）技能的定义是：主文件为 SKILL.md，"place scripts, reference materials, and other supporting files in the same directory"——即附属文件与 SKILL.md 同目录存放是官方认可的标准结构。

但插件加载器在处理清单 skills 字段的每个路径时，似乎把该目录当作普通的"技能扫描目录"，对其中所有 .md 文件一律按 flat-form 注册，而没有先识别"该目录本身即一个含 SKILL.md 的目录式技能，其余 .md 均为附属文件"。

同一问题的另一表现：若 skills 指向的是技能桶目录（如 ./skills/productivity/，其下各子目录各含 SKILL.md），22 个技能可以正确注册，但桶目录下的 README.md 也会被注册成一个名为 README 的 flat-form 技能。

影响

• 技能列表膨胀近一倍：本例中 22 个注册技能 → 实际出现约 43 个（21 个为附属文档），污染模型挑选技能的上下文。
• 干扰自动路由：flat-form 注册的"技能" disableModelInvocation 默认为 false，模型可能自动调用这些纯参考文档，干扰正常技能（如本仓库的路由技能 ask-matt）的分发。
• 潜在的命名冲突：技能名大小写不敏感，误注册的名字可能与用户级/项目级技能冲突。

期望行为（建议，按优先级）

1. skills 路径指向的目录若直接包含 SKILL.md，应按目录式单技能处理，同目录其余 .md 一律视为附属文件不予注册——与官方"supporting files"语义一致。
2. 或者：插件场景下只认目录式技能（SKILL.md），不做 flat-form 注册；至少要求 flat-form 文件带有合法 frontmatter 才注册。
3. 在 /plugins info <id> 的诊断信息中列出该插件实际注册的全部技能名，便于插件作者自查此类问题。

附录：本插件受影响文件清单（21 个附属文档）

技能	被误注册的附属文档
productivity/teach	GLOSSARY-FORMAT.md, LEARNING-RECORD-FORMAT.md, RESOURCES-FORMAT.md, MISSION-FORMAT.md
productivity/writing-great-skills	GLOSSARY.md
engineering/tdd	tests.md, mocking.md
engineering/prototype	UI.md, LOGIC.md
engineering/triage	AGENT-BRIEF.md, OUT-OF-SCOPE.md
engineering/codebase-design	DEEPENING.md, DESIGN-IT-TWICE.md
engineering/improve-codebase-architecture	HTML-REPORT.md
engineering/setup-matt-pocock-skills	issue-tracker-local.md, issue-tracker-github.md, issue-tracker-gitlab.md, triage-labels.md, domain.md
engineering/domain-modeling	ADR-FORMAT.md, CONTEXT-FORMAT.md

以上 21 个文件均无 YAML frontmatter，是各 SKILL.md 引用的格式规范/参考材料。

What steps can reproduce the bug?

自定义插件时发现的问题

What is the expected behavior?

No response

Additional information

No response