自定义技能

概述

创建自定义技能来扩展 Superpowers，定义项目特定的模式、工具和最佳实践。技能是可复用的参考指南，帮助 AI 助手应用有效的方法。

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

技能不是： 一次性问题解决的叙述

技能目录结构

skills/
└── my-skill/
    ├── SKILL.md           # 必需：主要参考文件
    └── supporting-file.*  # 可选：支持文件（脚本、示例等）

目录规则

• 扁平命名空间：所有技能在同一个可搜索的命名空间
• 分离文件的场景：
  • 大型参考资料（100+ 行）
  • 可复用工具（脚本、模板）
• 保持内联的内容：
  • 原则和概念
  • 代码模式（< 50 行）
  • 其他所有内容

SKILL.md 格式

Frontmatter（YAML）

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

字段说明：

字段	必需	说明
name	是	技能名称，仅使用字母、数字、连字符（无括号或特殊字符）
description	是	描述何时使用，以 "Use when..." 开头，第三方视角

重要规则：

• 总字符限制：最多 1024 字符
• description 只描述触发条件，不要总结工作流程
• 以 "Use when..." 开头，聚焦于触发条件

技能类型

类型	说明	示例
Technique	具体方法，有步骤可循	condition-based-waiting, root-cause-tracing
Pattern	思考问题的方式	flatten-with-flags, test-invariants
Reference	API 文档、语法指南、工具文档	office-docs

文档结构模板

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

# Skill Name

## Overview
这是什么？用 1-2 句话说明核心原则。

## When to Use
- 具体症状和使用场景
- 何时不应该使用

## Core Pattern
前后代码对比

## Quick Reference
常用操作表格或列表

## Implementation
简单模式用内联代码
大型参考用文件链接

## Common Mistakes
常见问题及修复方法

命名最佳实践

使用动词优先

✅ creating-skills    而非 skill-creation
✅ condition-based-waiting 而非 async-test-helpers
✅ root-cause-tracing 而非 debugging-techniques

描述你做什么或核心洞察

✅ flatten-with-flags > data-structure-refactoring
✅ using-skills > skill-usage

动名词（-ing）适合流程

creating-skills, testing-skills, debugging-with-logs

Description 编写技巧

关键原则：Description = 何时使用，不是技能做什么

# ❌ 错误：总结工作流程
description: Use when executing plans - dispatches subagent per task with code review

# ✅ 正确：只有触发条件
description: Use when executing implementation plans with independent tasks

内容要求：

• 使用具体的触发器、症状和情境
• 描述问题而非技术特定症状
• 保持技术无关性，除非技能本身是技术特定的
• 第三方视角编写

# ❌ 太抽象
description: For async testing

# ✅ 描述问题
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

搜索优化（CSO）

让 AI 助手能够找到你的技能：

1. 关键词覆盖

使用 AI 会搜索的词汇：

• 错误消息："Hook timed out", "race condition"
• 症状："flaky", "hanging", "zombie"
• 同义词："timeout/hang/freeze"
• 工具：实际命令、库名、文件类型

2. Token 效率

目标字数：

• 入门工作流：< 150 词
• 频繁加载技能：< 200 词
• 其他技能：< 500 词

压缩技巧：

• 使用交叉引用而非重复
• 压缩示例到最小
• 消除冗余

代码示例规则

一个优秀的示例胜过多个平庸示例

• 选择最相关的语言
• 完整可运行
• 注释说明 WHY
• 来自真实场景
• 可直接适配

不要：

• 实现 5+ 种语言
• 创建填空模板
• 编写虚假示例

配置文件位置

平台	内置技能位置	自定义技能位置
Claude Code	~/.claude/plugins/superpowers/skills/	~/.claude/skills/
Cursor	~/.cursor/plugins/superpowers/skills/	~/.cursor/skills/
Codex	~/.codex/superpowers/skills/	~/.agents/skills/
OpenCode	~/.config/opencode/superpowers/skills/	~/.config/opencode/skills/

创建技能示例

# 创建技能目录
mkdir -p ~/.claude/skills/my-feature-workflow

# 创建 SKILL.md
cat > ~/.claude/skills/my-feature-workflow/SKILL.md << 'EOF'
---
name: my-feature-workflow
description: Use when implementing new features in this project
---

# My Feature Workflow

## Overview
Standard workflow for implementing features in this project.

## Process

1. **Design First**
   - Write spec document
   - Get approval before coding

2. **TDD Implementation**
   - Write failing test
   - Implement minimum code
   - Refactor

3. **Code Review**
   - Self-review checklist
   - Submit for team review

## Quick Reference

| Phase | Output |
|-------|--------|
| Design | `docs/specs/{feature}.md` |
| Tests | `tests/{feature}.test.ts` |
| Code | `src/{feature}/` |
EOF

调试技能

验证技能被识别

# 检查技能目录
ls ~/.claude/skills/

# 检查 SKILL.md 格式
head ~/.claude/skills/my-skill/SKILL.md

常见问题

技能未被触发：

• 检查 description 是否清晰描述触发条件
• 确保使用 "Use when..." 开头
• 添加更多关键词

技能内容未被遵循：

• 减少内容长度，提高密度
• 使用结构化格式（表格、列表）
• 添加示例

最佳实践总结

1. 命名：动词优先，使用连字符
2. Description：只描述触发条件，不总结流程
3. 结构：Overview → When to Use → Pattern → Reference
4. 代码：一个优秀示例
5. 长度：保持简洁，< 500 词
6. 测试：验证 AI 能正确触发和遵循

进一步参考

详细技能编写指南请参考 Superpowers 的 writing-skills 技能，包含：

• TDD 方法应用于文档
• 压力测试技能
• 防止合理化的技巧
• 完整的检查清单