# writing-skills

> 创建新 skill、编辑现有 skill 或在部署前验证 skill 时使用

- Author: weidwonder
- Repository: weidwonder/general-task
- Version: 20260123120027
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/weidwonder/general-task
- Web: https://mule.run/skillshub/@@weidwonder/general-task~writing-skills:20260123120027

---

---
name: writing-skills
description: "创建新 skill、编辑现有 skill 或在部署前验证 skill 时使用"
---

# 编写 Skills

## 概述

**编写 skills 就是将测试驱动开发应用于流程文档。**

你编写测试用例（压力场景+子代理），观察它们失败（基线行为），编写 skill（文档），观察测试通过（代理遵循），然后重构（堵住漏洞）。

**核心原则:** 如果你没有看到代理在没有 skill 时失败，你就不知道 skill 是否教对了东西。

## 什么是 Skill？

**Skill** 是经过验证的技术、模式或工具的参考指南。帮助未来的 Claude 实例找到并应用有效的方法。

**Skill 是:** 可复用的技术、模式、工具、参考指南

**Skill 不是:** 关于你如何解决某个问题的叙事

## TDD 映射

| TDD 概念 | Skill 创建 |
|---------|-----------|
| **测试用例** | 压力场景 + 子代理 |
| **生产代码** | Skill 文档 (SKILL.md) |
| **测试失败 (RED)** | 代理在没有 skill 时违反规则（基线） |
| **测试通过 (GREEN)** | 代理在有 skill 时遵循 |
| **重构** | 堵住漏洞同时保持遵循 |

## 何时创建 Skill

**创建当:**
- 技术不是直觉上显而易见的
- 你会跨项目再次引用它
- 模式广泛适用（不是项目特定的）
- 其他人会受益

**不要创建:**
- 一次性解决方案
- 标准做法（其他地方有良好文档）
- 项目特定约定（放在 CLAUDE.md）

## 目录结构

```
skills/
  skill-name/
    SKILL.md              # 主参考文档（必需）
    supporting-file.*     # 仅在需要时
```

## SKILL.md 结构

**Frontmatter (YAML):**
- 只支持两个字段: `name` 和 `description`
- 总共最多 1024 字符
- `name`: 只用字母、数字和连字符
- `description`: 第三人称，只描述何时使用（不是做什么）

```markdown
---
name: skill-name-with-hyphens
description: "在 [具体触发条件和症状] 时使用"
---

# Skill 名称

## 概述
这是什么？核心原则用 1-2 句话。

## 何时使用
症状和用例的要点列表
何时不使用

## 核心模式（用于技术/模式）
前后代码对比

## 快速参考
表格或要点便于扫描常见操作

## 常见错误
什么会出错 + 修复方法
```

## Description 优化

**关键:** 未来的 Claude 需要找到你的 skill

**Description = 何时使用，不是 Skill 做什么**

```yaml
# ❌ 差: 总结了工作流 - Claude 可能只看这个不看 skill 内容
description: "执行计划时使用 - 每个任务分派子代理并在任务间进行代码审查"

# ✅ 好: 只有触发条件，没有工作流总结
description: "在当前会话中执行有独立任务的实施计划时使用"
```

**内容:**
- 使用具体的触发条件、症状和情况
- 描述问题而非特定技术症状
- 第三人称书写
- **绝不总结 skill 的流程或工作流**

## 铁律

```
没有先失败的测试，就没有 SKILL
```

这适用于新 skills 和对现有 skills 的编辑。

先写 skill 再测试？删除它。重新开始。
编辑 skill 不测试？同样违规。

## RED-GREEN-REFACTOR

### RED: 编写失败测试（基线）

在没有 skill 的情况下用子代理运行压力场景。记录确切行为：
- 他们做了什么选择？
- 他们用了什么借口（原文）？
- 哪些压力触发了违规？

### GREEN: 编写最小 Skill

编写针对那些具体借口的 skill。不要为假设的情况添加额外内容。

用 skill 运行相同场景。代理现在应该遵循。

### REFACTOR: 堵住漏洞

代理找到新借口？添加明确的反驳。重新测试直到无懈可击。

## 防止合理化

### 明确封堵每个漏洞

不要只陈述规则 - 禁止具体的变通方法：

```markdown
# ❌ 差
先写代码再写测试？删除它。

# ✅ 好
先写代码再写测试？删除它。重新开始。

**没有例外:**
- 不要保留它作为"参考"
- 不要在写测试时"调整"它
- 删除就是删除
```

### 建立借口表

从基线测试中捕获借口。代理找的每个借口都进表：

```markdown
| 借口 | 现实 |
|------|------|
| "太简单不需要测试" | 简单的代码也会出问题。测试只需 30 秒。 |
| "我之后再测试" | 立即通过的测试证明不了什么。 |
```

### 创建危险信号列表

```markdown
## 危险信号 - 停下来重新开始

- 先写代码再写测试
- "我已经手动测试过了"
- "之后测试目的一样"
- "这是关于精神不是仪式"

**以上都意味着: 删除。用 TDD 重新开始。**
```

## Skill 创建检查清单

**RED 阶段 - 编写失败测试:**
- [ ] 创建压力场景
- [ ] 在没有 skill 的情况下运行场景 - 原文记录基线行为
- [ ] 识别借口/失败的模式

**GREEN 阶段 - 编写最小 Skill:**
- [ ] 名称只用字母、数字、连字符
- [ ] YAML frontmatter 只有 name 和 description
- [ ] Description 以"在...时使用"开头，包含具体触发条件
- [ ] 关键词便于搜索
- [ ] 清晰的概述和核心原则
- [ ] 针对 RED 中识别的具体失败
- [ ] 用 skill 运行场景 - 验证代理现在遵循

**REFACTOR 阶段 - 堵住漏洞:**
- [ ] 识别测试中的新借口
- [ ] 添加明确的反驳
- [ ] 建立借口表
- [ ] 创建危险信号列表
- [ ] 重新测试直到无懈可击

**部署:**
- [ ] 提交 skill 到 git 并推送

## 底线

**创建 skills 就是流程文档的 TDD。**

同样的铁律: 没有先失败的测试就没有 skill。
同样的循环: RED（基线）→ GREEN（写 skill）→ REFACTOR（堵漏洞）。

如果你对代码遵循 TDD，对 skills 也要遵循。同样的纪律应用于文档。