Skill 编写 44
概述
- 本 skill 提供 skill 编写规范，适用于创建或修改 skill（SKILL.md、reference.md、模板等）
- 每次编辑按本规范边写边优化、保持简洁，无需事后单独做「优化/简化」
开始时声明：
- 创建："我正在使用 skill-authoring，按编写规范边写边优化。"
- 修改："我正在使用 skill-authoring 修改此 skill，按编写规范边改边优化。"
何时应用
应主动调用（满足任一条件即应用，无需用户明确说「skill-authoring」）：
- 用户要创建新 skill，或修改/优化/收紧/简化已有 skill
- 用户要求对某 skill 或某几节做表述收紧、边写边优化、只聚焦某段、符合编写规范
- 待办/上下文要求对某 skill 应用 skill-authoring（用户只回「继续」「2」等短回复也触发）
- 即将编辑的文件为 SKILL.md、reference.md 等位于 skills 目录下的文件
排除场景：编辑 code-standards 时，不使用本 skill，改用 code-standards-maintenance。
Skill 结构规范
Frontmatter
---
name: skill-name
description: 当 [触发条件] 时使用
alwaysApply: false
---
关键点：
- name: 小写 kebab-case，与目录名匹配
- description: 必须包含「何时使用」触发条件；可简短写「做什么」便于发现；禁止写工作流总结（会令 agent 跳过主体）
- alwaysApply: 大多数设为 false
- 可选：disable-model-invocation: true 表示仅手动触发
Skill 主体
结构：
1. 标题（与 frontmatter name 匹配）
2. 概述（2-3 句话）
3. 处理流程（分步骤）
4. 关键原则 / 记住
风格：
- 层级分明，用标题、列表组织，避免大段堆砌
- 动作导向，简短直接
- 专注做什么，少说为什么
目录结构
- 必选：
skill-name/SKILL.md - 可选：
reference.md（长说明）、examples.md（示例）、scripts/（脚本）、assets/（模板）
渐进式披露
- 核心指引放 SKILL.md；过长内容放
reference.md - 引用只做一层：SKILL.md → reference.md
- SKILL.md 尽量 <500 行
处理流程
创建 Skill
1. 理解需求
- 提取核心功能
- 识别触发条件（"什么时候使用"）
- 确定 skill 类别（工作流、工具使用、最佳实践）
- 确认存放位置（个人 vs 项目）、是否需要
scripts/或reference.md等
2. 参考 superpowers
- 访问 https://github.com/obra/superpowers/tree/main/skills
- 重点参考：
brainstorming、writing-plans、executing-plans - 分析其结构：Frontmatter 格式、主体结构、写作风格
3. 设计结构
- 创建目录
skills/{skill-name}/ - 定义 frontmatter
- 规划主要部分（概述、流程、原则）
4. 编写内容
概述： 2-3 句话说明做什么
处理流程：
- 分为编号步骤或清晰章节
- 每个步骤单一动作
- 子要点用项目列表
- 仅在有助于理解时包含示例
原则/记住：
- 贯穿始终的关键指导
- 需要避免的错误
- 重要的约束或要求
5. 引用其他 Skill
- 使用 "REQUIRED SUB-SKILL:" 标记必需依赖
- 使用 "互补技能：" 标记可选引用
- 使用 skill 名称引用（如 "superpowers:executing-plans"）
修改 Skill
1. 看全貌
- 查看该 skill 的完整结构（SKILL.md 目录与各节）
- 分析关联文件（reference.md、模板、demo 等）
- 判断新增/修改内容应落在何处
2. 确定落点
- 同一段规则只在一处写完整正文（通常选 reference 某节或 SKILL 某节）
- 其余位置用「见 §xxx」或一句概括 + 引用
- 避免同一段内容在多处重复
3. 按规范修改
- 只聚焦当轮要改的一段或一个文件
- 按「编写规范」写该处，不整份重跑
- 确认当前改的 skill 路径/名称，不引入冗余
编写规范
每次编辑（创建或修改）时直接按下面规范写：
- 语义不变：删减或改写不得改变执行效果；有疑虑时保留原表述
- 每句有用：删除冗余解释、不必要示例；保留对执行有影响的示例
- description：以「何时用」为主，无长篇工作流总结
- 结构：层级分明、可扫读；无大段堆砌
- SKILL.md <500 行；过长内容放 reference.md 并一层引用
- 修改 reference/模板时：同样按上述规范，并与 SKILL 引用一致
大改后快速核对： 行数 <500、description 含触发、术语一致、引用仅一层、frontmatter 与主体一致。
关键原则
- 主动识别并调用：满足「何时应用」任一条即主动调用本 skill，不得因用户未明确说而跳过
- 边写边优化、只聚焦改动：直接按规范写，不需事后专门优化；修改时只针对当轮
- description 以何时用为主：含触发条件；禁工作流总结
- 简洁不伤义：不写无助执行的内容；删减不改语义
- 正文一处、其余引用：同一规则只在一处写完整，其余用引用
- 动作优先、列表为主：做什么、少说为什么
常见错误
创建时
| ❌ 错误 | ✅ 正确 |
|---|---|
| description 写工作流总结："创建详细的实施计划..." | 含触发条件："当你有多步骤任务需求时使用" |
| 解释概念的长段落 | 带动作项的简短列表 |
| 组织不清晰、大段堆砌 | 概述 → 流程 → 原则，层级分明 |
修改时
| ❌ 错误 | ✅ 正确 |
|---|---|
| 该调用未调用 | 满足条件即主动调用本 skill |
| 只改不按规范写，越改越长 | 边改边按规范优化 |
| 只改一处却整份重跑 | 只聚焦当轮改动 |
| 同一段在多处重复写 | 正文只放一处，其余引用 |
通用
| ❌ 错误 | ✅ 正确 |
|---|---|
| 简化伤义：删掉关键步骤导致语义改变 | 简化不伤义：只删冗余，语义一致 |
| Windows 路径、时效表述、术语不一 | 路径用 /；无时效表述；术语一致 |
Skill 模板
---
name: skill-name
description: 当 [触发条件] 时使用
alwaysApply: false
---
# Skill 名称
## 概述
2-3 句话说明做什么。
## 处理流程
### 步骤 1：[动作]
- [子动作]
- [子动作]
### 步骤 2：[动作]
- [子动作]
## 记住
- [关键原则 1]
- [关键原则 2]
