技能作家

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

适用场景

新建项目级或个人级 skill 压缩过长的 SKILL.md 将百科式文档拆成 SKILL.md + reference/ 重写 description,提升 skill 路由命中率 统一一批 skill 的结构、命名和风格

不适用场景

只是补一两行普通说明,不涉及 skill 结构调整 只是新增业务知识,但不需要形成可复用 skill 用户要修改的是 rule、hook、普通文档,而不是 skill

快速指导

先确定 skill 的单一职责。一个 skill 只解决一类问题,不要把总览、教程、百科和脚本说明混在一起。 把 description 当成路由触发器,而不是功能简介。优先写“用户在什么场景下会需要它”。 主 SKILL.md 只保留高信号内容: 适用场景 不适用场景

高信号规则

路由优先于百科,触发条件优先于背景介绍 主文件优先告诉模型“何时用、怎么走、别踩什么坑”,而不是“完整知识全貌” 操作型 skill 更要克制,主文件不要承载具体 payload、状态表和长步骤 同类 skill 之间的边界必须硬,避免路由重叠 反复出现的 AI 误用案例,优先沉淀到 ai/evals/,确认稳定后再调整 skill

验收清单

name 与目录名一致,且只使用小写、数字、连字符 description 简短、第三人称、可路由 主 SKILL.md 通常控制在约 40-80 行,特殊导航型 skill 可略宽,但不应回到手册化正文 主文档中只保留高信号指导,不堆积百科内容 主文档默认包含 适用场景 / 不适用场景 / 快速指导 / 高信号规则 / 关键陷阱 / 延伸阅读

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@TencentBlueKing · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Skill Writer

## 适用场景

- 新建项目级或个人级 skill
- 压缩过长的 `SKILL.md`
- 将百科式文档拆成 `SKILL.md + reference/`
- 重写 `description`,提升 skill 路由命中率
- 统一一批 skill 的结构、命名和风格

## 不适用场景

- 只是补一两行普通说明,不涉及 skill 结构调整
- 只是新增业务知识,但不需要形成可复用 skill
- 用户要修改的是 rule、hook、普通文档,而不是 skill

## 快速指导

1. 先确定 skill 的单一职责。一个 skill 只解决一类问题,不要把总览、教程、百科和脚本说明混在一起。
2. 把 `description` 当成路由触发器,而不是功能简介。优先写“用户在什么场景下会需要它”。
3. 主 `SKILL.md` 只保留高信号内容:
   - 适用场景
   - 不适用场景
   - 快速指导
   - 高信号规则
   - 关键陷阱
   - 延伸阅读入口
4. 默认假设模型已经知道通用常识。只保留项目特有约定、容易出错的边界、历史坑点和明确偏好。
5. 主 `SKILL.md` 的目标不是“尽量短”,而是“短到只剩路由和行动指导”。在当前仓库里,主文件通常应收紧到约 `40-80` 行。
6. 重内容放到 `reference/`:
   - 大段背景知识
   - 长表格
   - 代码目录
   - 完整案例
   - FAQ
   - payload 示例
   - 状态枚举
   - 确认模板
7. 只有在流程高度确定、稳定且容易出错时,才把逻辑下沉到 `scripts/` 或模板文件。
8. 所有链接尽量保持一层深度,避免主 skill 还要继续跳很多层目录。
9. 同 skill 内部优先使用相对路径;跨 skill 优先写 skill 名称,不要写死仓库目录路径。
10. 新增或重构时,优先清理遗留 frontmatter 字段,如 `token_estimate`、`core_files`、`related_skills`,除非仍有明确消费方依赖。

## 推荐骨架

```markdown
# 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`

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。