用途:编写、压缩或重构 BK-CI skill,例如收紧 description、统一主文件骨架、将重内容下沉到 reference/,并固化渐进式披露规则。新增或规范化 skill 时优先使用。
适用场景:新建项目级或个人级 skill;压缩过长的 SKILL.md;将百科式文档拆成 SKILL.md + reference/;重写 description 以提升路由命中率;统一一批 skill 的结构、命名和风格。不适用:只补一两行普通说明、只新增业务知识而不形成可复用 skill、修改 rule/hook/普通文档。
主要能力与用法:先确定 skill 的单一职责,一个 skill 只解决一类问题。把 description 当作路由触发器,优先写用户在什么场景下会需要它。主 SKILL.md 只保留高信号内容,通常收紧到约 40-80 行,包含适用场景、不适用场景、快速指导、高信号规则、关键陷阱、延伸阅读入口。默认模型已知通用常识,只保留项目特有约定、易错边界、历史坑点和明确偏好。重内容放入 reference/,如大段背景、长表格、代码目录、完整案例、FAQ、payload 示例、状态枚举、确认模板。仅在流程高度确定、稳定且易出错时,才下沉到 scripts/ 或模板文件。链接尽量保持一层深度,同 skill 内部用相对路径,跨 skill 优先写 skill 名称。新增或重构时清理遗留 frontmatter 字段,如 token_estimate、core_files、related_skills,除非仍有明确消费方依赖。
推荐骨架:Skill 名称、适用场景、不适用场景、快速指导、高信号规则、关键陷阱、延伸阅读。
高信号规则:路由优先于百科,触发条件优先于背景介绍;主文件告诉模型何时用、怎么走、别踩什么坑;操作型 skill 主文件不承载具体 payload、状态表和长步骤;同类 skill 边界要硬,避免路由重叠;反复出现的 AI 误用案例优先沉淀到 ai/evals/,确认稳定后再调整 skill。
验收清单:name 与目录名一致,只用小写、数字、连字符;description 简短、第三人称、可路由;主 SKILL.md 通常约 40-80 行,导航型可略宽;主文档只保留高信号指导;包含上述默认章节;详细资料已拆到 reference/ 或辅助文件;示例 payload、确认模板、状态枚举、长表格已下沉;跨 skill 引用用 skill 名称,内部引用用相对路径;遗留 frontmatter 字段已清理或说明保留理由;同类 skill 边界清晰,不频繁误触发。
延伸阅读:建立 BK-CI 模块导航优先看 00-bkci-global-architecture;压缩现有 skill 先盘点重复概念再决定权威来源;判断 rule、skill、reference 与编辑器适配目录边界参考 ../../HARNESS.md。