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