---
name: vaycentsun/sw-writing-skills
source: https://app.decimal.ai/s/vaycentsun-sw-writing-skills@1/SKILL.md
source_sha256: ad815e9a54d0
---

# Writing Skills - 编写 Skill

创建、编辑和验证 Agile Development 风格的 Skill。

## 核心原则

**编写 Skill = 将 TDD 应用于流程文档**

- 先测试，后编写 Skill
- 观察失败，理解问题
- 编写 Skill 解决那些失败
- 验证，然后重构

## 铁律

```
NO SKILL WITHOUT A FAILING TEST FIRST
```

编写 Skill 前先测试？删除它。重新开始。

**没有例外：**
- 不要直接编写 Skill
- 不要"参考"现有 Skill
- 不要"先写一个草案"

## 什么是 Skill

**Skill 是：**
- 可复用的技术、模式、工具
- 参考指南
- 塑造 Agent 行为的代码

**Skill 不是：**
- 你如何解决问题的叙事
- 一次性解决方案
- 项目特定的约定

## TDD 应用于 Skill

| TDD 概念 | Skill 创建对应 |
|---------|---------------|
| **测试用例** | 压力场景 + 子 Agent |
| **生产代码** | Skill 文档 (SKILL.md) |
| **测试失败 (RED)** | Agent 违反规则（基线） |
| **测试通过 (GREEN)** | Agent 遵守 Skill |
| **重构** | 关闭漏洞，保持合规 |
| **先写测试** | 在编写 Skill 前先运行基线压力场景 |
| **观察失败** | 记录 Agent 的确切借口和行为 |
| **最小编写** | 编写 Skill 只解决观察到的失败 |
| **观察通过** | 带 Skill 重新运行，验证 Agent 合规 |
| **重构循环** | 发现新借口 → 添加对策 → 重新验证 |

## Skill 创建流程

```mermaid
flowchart TD
    Start([开始]) --> Identify[1. 识别需求<br/>什么行为需要塑造？]
    Identify --> Create[2. 创建压力场景<br/>3+ 种压力组合]
    Create --> Baseline[3. 运行基线测试<br/>无 Skill 观察失败]
    Baseline --> Document[4. 记录失败<br/>确切行为和借口]
    Document --> Write[5. 编写 Skill<br/>解决特定失败]
    Write --> RunWith[6. 带 Skill 运行<br/>验证合规]
    RunWith --> Passes{通过？}
    Passes -->|否| Close[7. 关闭漏洞<br/>找到新借口，添加对策]
    Close --> RunWith
    Passes -->|是| Refactor[8. 重构<br/>保持合规，改进清晰]
    Refactor --> Deploy[9. 部署<br/>提交到 git]
    Deploy --> Done([完成])
```

## 详细步骤

完整步骤参见 [skill-creation-workflow.md](skill-creation-workflow.md)。

**概要：**

1. **识别需求** — 何时创建 Skill，何时不创建
2. **创建压力场景** — 模拟 Agent 在压力下的行为（时间、沉没成本、权威、疲劳）
3. **运行基线测试** — 无 Skill 观察 Agent 失败
4. **记录失败** — 记录确切行为和借口
5. **编写 Skill** — 解决观察到的特定失败
6. **验证合规** — 带 Skill 重新运行，验证 Agent 遵守
7. **关闭漏洞** — 找到新借口，添加对策，重新验证
8. **重构** — 改进清晰性，不改变行为
9. **部署** — 提交到 git

## Skill 文件结构

```
skills/skill-name/
├── SKILL.md                    # 主 Skill 文件（必需）
└── subagent-prompts/           # 子 Agent 提示词（可选）
    └── subagent-prompt.md
```

## SKILL.md 结构

```markdown
---
name: Skill-Name-With-Hyphens
description: "Use when [具体触发条件和症状]"
---

# Skill 名称

## 铁律
[关键规则，不可违反]

## 流程
[流程图和详细步骤]

## 详细说明
[每个步骤的详细解释]

## 红旗 - 立即停止

| 想法 | 现实 |
|------|------|
| "先写 Skill 再补测试" | 违反 NO SKILL WITHOUT A FAILING TEST FIRST。没有压力场景验证的 Skill 会失效 |
| "描述里简要总结工作流程就够了" | 描述是 Skill 发现的关键。总结工作流程 → Agent 只读描述不读正文，行为错误 |
| "这个 Skill 很通用，适用于很多场景" | Skill 必须具体。通用 Skill 无法塑造明确行为，等于没有 Skill |
| "多语言示例覆盖更多用户" | 多语言稀释质量。优先用一种语言写出高质量示例 |
| "反例太具体，写抽象点" | 反例需要具体可复用。抽象叙事无法指导行为 |
| "先批量创建多个 Skill，再统一测试" | 每个 Skill 必须先单独测试、部署。批量 = 未验证的 Skill 进入代码库 |
| "Skill 超过 600 行也没关系" | 超过行数限制必须拆分。冗长 Skill 不被加载，规则再对也无效 |
| "占位符以后补" | 占位符、TODO、TBD 不能进入主分支。不完整 = 不可信 |

## 常见借口表
| 借口 | 现实 |
|------|------|
| [借口] | [反驳] |

## 示例
[具体示例]

## 集成
[前置和后续 Skill]

## 输出示例
[期望的输出格式]
```

## 描述字段（关键）

**Claude Search Optimization (CSO)**

描述字段是 Skill 发现的关键。Agent 使用它来决定是否加载你的 Skill。

**核心原则：**
- 描述**触发条件**，不是 Skill 的功能
- 以 "Use when..." 开头
- 使用第三人称
- 包含关键词（错误消息、症状、工具名）
- **绝不**总结工作流或流程

```yaml
# ❌ 错误：描述中总结了工作流程
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ 正确：只描述触发条件
description: Use when executing implementation plans with independent tasks in the current session
```

**为什么重要：** 描述总结工作流时，Agent 可能只读描述而不读完整 Skill，导致行为错误。

**完整 CSO 指南：** 参见 [cso-guide.md](cso-guide.md) 获取详细的描述编写规则、关键词覆盖策略、命名规范和 Token 效率技巧。

## 测试方法

### 子 Agent 测试

```markdown
**测试场景**: [描述]

**输入**: [给子 Agent 的指令]

**期望行为**: [期望它做什么]

**通过标准**: [如何验证通过]
```

### 压力类型

| 压力类型 | 描述 | 示例 |
|----------|------|------|
| **时间** | "快点完成" | "我们在赶时间" |
| **沉没成本** | "已经花了 X 小时" | "删除这么多工作是浪费" |
| **权威** | "用户说..." | "用户说直接修复" |
| **疲劳** | "最后一步了" | "就剩这一点了" |
| **简单** | "这很简单" | "只是个小修复" |

### 组合压力

最有效的测试组合多种压力：
- 时间 + 沉没成本
- 权威 + 简单
- 疲劳 + "这只是次要的"

## 按 Skill 类型测试

不同 Skill 类型需要不同的测试方法：

### 纪律执行型 Skill（规则/要求）

**示例**: TDD、完成前验证、设计先行

**测试方式**:
- 学术问题：是否理解规则？
- 压力场景：压力下是否合规？
- 组合压力：时间 + 沉没成本 + 疲劳
- 识别借口并添加明确反驳

**成功标准**: Agent 在最大压力下仍遵守规则

### 技术型 Skill（操作指南）

**示例**: 条件等待、根因追踪、防御式编程

**测试方式**:
- 应用场景：能否正确应用技术？
- 变体场景：能否处理边界情况？
- 信息缺失测试：指令是否有缺口？

**成功标准**: Agent 成功将技术应用于新场景

### 模式型 Skill（思维模型）

**示例**: 降低复杂度、信息隐藏

**测试方式**:
- 识别场景：是否识别模式适用时机？
- 应用场景：能否使用思维模型？
- 反例：是否知道何时不适用？

**成功标准**: Agent 正确识别何时/如何应用模式

### 参考型 Skill（文档/API）

**示例**: API 文档、命令参考

**测试方式**:
- 检索场景：能否找到正确信息？
- 应用场景：能否正确使用找到的信息？
- 缺口测试：常见用例是否覆盖？

**成功标准**: Agent 找到并正确应用参考信息

## Skill 类型

| 类型 | 说明 | 示例 |
|------|------|------|
| **Technique** | 具体方法步骤 | condition-based-waiting |
| **Pattern** | 思维方式 | flatten-with-flags |
| **Reference** | API/工具文档 | office-docs |

## 反模式

### ❌ 叙事示例
```markdown
"In session 2025-10-03, we found empty projectDir caused..."
```
**为什么坏**: 太具体，不可复用

### ❌ 多语言稀释
```markdown
example-js.js, example-py.py, example-go.go
```
**为什么坏**: 质量平庸，维护负担

### ❌ 流程图中的代码
```text
step1 = "import fs"
step2 = "read file"
```
**为什么坏**: 不能复制粘贴，难读

### ❌ 通用标签
```text
helper1, helper2, step3, pattern4
```
**为什么坏**: 标签应该有语义意义

## 输出示例

### Skill 创建完成

```markdown
## Skill 创建完成

**名称**: sw-my-skill
**位置**: ./skills/sw-agiledevelopment/my-skill/SKILL.md

### 测试结果
- 基线测试: ✅ 观察到 5 种失败模式
- Skill 测试: ✅ 所有场景通过
- 漏洞关闭: ✅ 3 个新借口已添加对策

### Skill 信息
- 大小: 8.5KB
- Token: ~2000
- 描述: "Use when ..."

### 使用方式
```
参考 sw-my-skill Skill 处理这个场景
```
```

## 集成

**前置 Skill**: 无（这是元 Skill）

**后续 Skill**: 
- 创建好的 Skill 可用于后续工作流

**使用此 Skill 创建:**
- sw-requirements-clarification
- sw-test-driven-dev
- sw-subagent-development
- 其他所有 Skill

## 创建检查清单

- [ ] 识别真实需求
- [ ] 创建 3+ 压力场景
- [ ] 运行基线测试（无 Skill）
- [ ] 记录确切失败行为
- [ ] 编写 Skill 解决那些失败
- [ ] 带 Skill 运行测试
- [ ] 关闭所有漏洞
- [ ] 重构改进清晰性
- [ ] 提交到 git

## STOP: 在完成下一个 Skill 之前

**编写任何 Skill 后，必须 STOP 并完成部署流程。**

**禁止：**
- 批量创建多个 Skill 而不逐个测试
- 在当前 Skill 未验证前进入下一个
- 跳过测试因为"批量更高效"

**部署检查清单是强制性的。**

部署未测试的 Skill = 部署未测试的代码。这是质量标准的违反。

## 发现工作流

未来 Agent 如何找到你的 Skill：

1. **遇到问题**（"测试不稳定"）
2. **找到 SKILL**（描述匹配）
3. **扫描概述**（是否相关？）
4. **读取模式**（快速参考表）
5. **加载示例**（仅在实现时）

**优化此流程** — 将可搜索关键词前置并频繁使用。

## 最佳实践

1. **先测试，后 Skill** - 没有例外
2. **具体，不是通用** - 解决观察到的失败
3. **保护性设计** - 假设 Agent 会找漏洞
4. **简洁** - 频繁加载的 Skill < 200 词
5. **可搜索** - 使用关键词，错误消息，症状