# Writing Skills

> 元技能 —— 教你如何编写高质量的 WorkBuddy Skill。用于创建新 Skill 或改进已有 Skill。触发词：写skill、创建技能、改进skill、skill怎么写、writing skills。

- Skill: `yinqd3/writing-skills` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yinqd3/writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yinqd3/writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yinqd3 (https://skillmd.com/u/yinqd3)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yinqd3/writing-skills

---


# 编写 WorkBuddy Skill（元技能）

## 概述

Skill 封装了特定工作流——它不是文档，是**塑造 AI 行为的代码**。

## Skill 的结构

```
skill-name/
├── SKILL.md          # 主文件（必需）
└── references/       # 参考资料（可选）
    ├── guide-1.md
    └── guide-2.md
```

## SKILL.md 模板

```markdown
---
name: skill-name
description: 用途+触发条件+触发词
agent_created: true
---

# Skill 标题

## 概述
[一段话说明这个 skill 做什么]

## 何时使用
- 触发条件 1
- 触发条件 2
- 触发词: xxx、yyy、zzz

## 核心铁律/硬门禁
[如果有不可违反的规则，放这里]

## 步骤/检查清单
1. **步骤 1** — 具体做什么
2. **步骤 2** — 具体做什么
...

## 工作流/流程图
[复杂流程可用文本流程图]

## 关键原则
- 原则 1
- 原则 2

## 反模式/红灯
[常见的错误做法，列出来警示]
```

## Skill 设计原则

### 1. 清晰触发条件
描述什么时候该用这个 Skill，什么时候不该用。触发词要覆盖中英双语。

### 2. 强制流程
用 "MUST"、"强制"、"Hard Gate" 标记不可跳过的步骤。

### 3. 具体可执行
不是说"做代码审查"，而是：
- 运行 `pytest -q`
- 检查 git diff
- 派发审查子代理（附带完整提示模板）
- 按严重程度分类问题

### 4. 处理边界情况
- 出错了怎么办？
- 不通过怎么办？
- 用户想跳过怎么办？（说明后果）

### 5. 给出示例
好的示例和差的示例对比，比纯文字更有效。

### 6. 保持精简
Skill 不是手册——只放 AI 每次执行时需要遵循的关键规则。

### 7. 中英双语
触发词和关键描述中英双语，覆盖不同表达习惯。

## 测试 Skill

写完 Skill 后：
1. 用真实场景触发测试
2. 观察 AI 的行为是否符合预期
3. 收集反例——什么时候 Skill 没触发或触发错了
4. 迭代调优

## 常见错误

| 错误 | 正确做法 |
|:---|:---|
| 描述太模糊（"做好代码审查"） | 给出具体检查清单和命令 |
| 触发条件太宽泛（匹配到不该匹配的任务） | 收紧触发词，加排除条件 |
| 步骤太复杂（AI 执行效率低） | 精简到最小必要步骤 |
| 没有错误处理 | 加"如果失败/不通过怎么办" |
| 纯英文（中文用户触发不了） | 加中文触发词和描述 |