Skill开发学习指南Skill 开发学习指南 > 基于 Superpowers 插件真实案例分析 > Skill 是一

Skill 开发学习指南

基于 Superpowers 插件真实案例分析

1. 什么是 Skill

Skill 是一个 Prompt 模板，当 Claude 判断任务相关时会自动加载。它不是用户输入的命令（那是 Commands），而是给 Claude 提供处理特定任务的指导。

类比：

Command = 用户说"做 X" → Claude 执行
Skill = Claude 判断"这像 X 场景" → 自动加载最佳实践

2. 插件结构

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── skill-a/
│   │   └── SKILL.md
│   └── skill-b/
│       ├── SKILL.md
│       ├── scripts/
│       ├── references/
│       └── examples/
├── commands/
├── hooks/
└── agents/

最小结构只需要：

// plugin.json
{
  "name": "my-plugin",
  "version": "1.0.0"
}

// skills/my-skill/SKILL.md (唯一必需文件)

3. SKILL.md 核心结构

---
name: skill-name
description: Use when...
version: 1.0.0
---

# Skill Name

## Overview
[核心内容一句话]

## When to Use
[场景列表]

## Core Pattern
[步骤/代码/模板]

## Checklist
- [ ] 步骤1
- [ ] 步骤2

## Red Flags
[常见错误]

4. Description 写法（最重要）

核心规则

Description = 触发条件，不 = 工作流程

# ❌ 错误：描述了工作流程
description: Use when creating skills - write test first, then skill

# ✅ 正确：只写触发条件
description: Use when creating new skills, editing existing skills, or verifying skills work

为什么要这样？

测试发现：当 description 总结工作流程时，Claude 会直接按照描述执行，而跳过 SKILL.md 的完整内容。

好的 Description 特征

以 "Use when" 开头
描述触发症状/场景，不描述过程
包含关键词（错误信息、工具名）
使用第三人称
保持简洁（<500字符）

示例对比

场景	❌ 错误	✅ 正确
TDD	"Use for TDD - write test first, watch it fail, write minimal code"	"Use when implementing any feature or bugfix, before writing implementation code"
调试	"Use when debugging - find root cause first, don't guess"	"Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes"
头脑风暴	"Use before building - explore requirements, propose designs, get approval"	"You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior"

5. Skill 类型

5.1 Discipline（纪律型）

特点： 必须严格遵守，有明确规则

示例： TDD、Verification Before Completion

结构特征：

铁律（Iron Law）用代码块强调
Red Flags 列表
Common Rationalizations 表格

## The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"

5.2 Technique（技术型）

特点： 有具体步骤方法

示例： Brainstorming、Systematic Debugging

结构特征：

清晰的流程图
分阶段步骤
Checkpoint 检查点

5.3 Reference（参考型）

特点： 提供信息查询

结构特征：

清晰的分类
示例丰富

5.4 Pattern（思维型）

特点： 思维方式/心智模型

结构特征：

核心原则
应用场景
反例说明

6. 高级元素

6.1 流程图（Graphviz）

digraph tdd_cycle {
    red [label="RED", shape=box, style=filled, fillcolor="#ffcccc"];
    green [label="GREEN", shape=box, style=filled, fillcolor="#ccffcc"];
    refactor [label="REFACTOR", shape=box, style=filled, fillcolor="#ccccff"];

    red -> green -> refactor -> red;
}

6.2 强制标签

<HARD-GATE>
Do NOT invoke any implementation skill, write any code...
</HARD-GATE>

6.3 子 Skill 引用

**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development

7. 开发流程

TDD 方法应用于 Skill

RED:  Run scenario WITHOUT skill → 记录失败方式
GREEN: Write minimal skill → Fix those failures
REFACTOR: Close loopholes → Re-test

创建步骤

识别场景 — 什么情况下应该触发？
写 Description — 只写触发条件
写 SKILL.md — 核心指导内容
测试 — 模拟触发场景
迭代 — 根据反馈改进

8. 真实案例分析

案例 1: test-driven-development

Description:

description: Use when implementing any feature or bugfix, before writing implementation code

关键元素：

Iron Law 代码块强调
彩色流程图（红绿蓝）
Good/Bad 代码对比表格
Rationalization 表格
Red Flags 列表
具体 Bug 修复示例

案例 2: systematic-debugging

Description:

description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

结构特点：

四阶段流程（Phase 1-4）
每个阶段有明确的"成功标准"
多组件系统的诊断方法
3+ 失败后的架构质疑机制

案例 3: verification-before-completion

Description:

description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs

设计亮点：

Gate Function 模式
"Not Sufficient" 表格
Evidence before assertions 原则

案例 4: brainstorming

Description:

description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior."

设计亮点：

HARD-GATE 标签强制执行
9 步检查清单
DOT 流程图

9. 常见错误

❌ Description 包含工作流程

# 会导致 Claude 跳过 SKILL.md
description: Use when doing TDD - write test first, then code

❌ Description 太模糊

# 无法触发
description: For async testing

# ✅ 具体场景
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

❌ 缺少 Red Flags

纪律型 Skill 必须有，防止 Claude 找借口跳过。

❌ 流程图用于线性步骤

流程图只用于决策点和循环。

附录：快速参考

SKILL.md 模板

---
name: my-skill
description: Use when [specific triggering conditions]
---

# My Skill

## Overview
[One sentence core principle]

## When to Use
- [Scenario 1]
- [Scenario 2]

## Core Pattern
[Steps / Code / Template]

## Checklist
- [ ] Step 1
- [ ] Step 2

## Red Flags
STOP if you catch yourself:
- [Rationalization 1]

关键文件位置

~/.claude/plugins/
├── cache/claude-plugins-official/superpowers/*/skills/
│   ├── brainstorming/
│   ├── test-driven-development/
│   ├── systematic-debugging/
│   └── verification-before-completion/

Skill开发学习指南