# Writing Skills

当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用

- Repository: https://github.com/jnMetaCode/superpowers-zh (8437 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-26
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add jnMetaCode/superpowers-zh --skill writing-skills -g -a claude-code -y`
Codex: `npx skills add jnMetaCode/superpowers-zh --skill writing-skills -g -a codex -y`
Cursor: `npx skills add jnMetaCode/superpowers-zh --skill writing-skills -g -a cursor -y`
Gemini CLI: `npx skills add jnMetaCode/superpowers-zh --skill writing-skills -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add jnMetaCode/superpowers-zh`

## Description

当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 编写技能

## 概述

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

**个人技能存放在你所用运行环境的技能目录中**（Claude Code 上是 `~/.claude/skills/`）, , 其他运行环境的路径见 [codex-tools.md](../using-superpowers/references/codex-tools.md) 或 [gemini-tools.md](../using-superpowers/references/gemini-tools.md)。Codex、Copilot CLI 和 Gemini CLI 也都认 `~/.agents/skills/`，作为跨运行环境的别名。

你编写测试用例（带子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（智能体遵守规则），然后重构（堵住漏洞）。

**核心原则：** 如果你没有观察到智能体在没有该技能时失败，你就不知道这个技能是否教了正确的东西。

**必需背景：** 在使用此技能前，你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。

**官方指南：** Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。

## 什么是技能？

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

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

**技能不是：** 关于你某次如何解决问题的叙事

## TDD 映射到技能

| TDD 概念 | 技能创建 |
|----------|---------|
| **测试用例** | 带子智能体的压力场景 |
| **生产代码** | 技能文档（SKILL.md） |
| **测试失败（红）** | 智能体在没有技能时违反规则（基线） |
| **测试通过（绿）** | 智能体在有技能时遵守规则 |
| **重构** | 在保持合规的同时堵住漏洞 |
| **先写测试** | 在编写技能之前先运行基线场景 |
| **观察失败** | 记录智能体使用的确切合理化借口 |
| **最小代码** | 编写针对那些具体违规行为的技能 |
| **观察通过** | 验证智能体现在遵守规则 |
| **重构循环** | 发现新的合理化借口 → 堵住 → 重新验证 |

整个技能创建过程遵循红-绿-重构。

## 何时创建技能

**创建条件：**
- 技术对你来说不是直觉上显而易见的
- 你会在不同项目中反复引用
- 模式具有广泛适用性（非项目特定）
- 其他人也会受益

**不要创建：**
- 一次性解决方案
- 其他地方有充分文档的标准实践
- 项目特定的约定（放在 CLAUDE.md 中）
- 机械性约束（如果可以用正则/验证强制执行，就自动化, , 文档留给需要判断的场景）

## 技能类型

### 技术类
有具体步骤的方法（condition-based-waiting、root-cause-tracing）

### 模式类
思考问题的方式（flatten-with-flags、test-invariants）

### 参考类
API 文档、语法指南、工具文档（office docs）

## 目录结构

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

**扁平命名空间** - 所有技能在一个可搜索的命名空间中

**分离文件的情况：**
1. **大量参考内容**（100+ 行）- API 文档、全面的语法说明
2. **可复用工具** - 脚本、实用程序、模板

**保持内联：**
- 原则和概念
- 代码模式（< 50 行）
- 其他所有内容

## SKILL.md 结构

The rest: https://github.com/jnMetaCode/superpowers-zh/blob/HEAD/skills/writing-skills/SKILL.md