避坑指南：手把手教你写出顶级Claude Skills

创建Claude Skills时最容易犯的错不是写得不够复杂，而是一上来就想把技能做成万能工具。下面7个坑是最常见也最该避开的。

坑1：把Skill做成万金油

最常见的错误——试图创建一个什么都能干的Skill。

一个技能既负责UI审计，又负责提出redesign方案，还要生成设计文档。表面看起来很全能，实际使用时输出很容易变得泛泛而谈。

核心原则：一个任务，一个职责。

# ❌ 错误：万能Skill
一个Skill既做UI审计，又写UI文档

# ✅ 正确：拆分成独立Skill
- figma-ui-audit.md：专门做UI审计
- figma-ui-docs.md：专门写UI文档

Composable skills通常比万能技能更可靠。职责越清楚，Claude越知道自己应该优化什么。

坑2：忽略真实上下文

Skill的核心价值是让Claude更贴近你的具体工作场景。但很多人只写了宽泛指令，没有告诉Claude产品是什么、约束是什么、设计系统是什么。

以Figame UX审计Skill为例，至少包含：

上下文	说明
设计系统规则	tokens、组件、间距
平台限制	iOS、Android或Web
产品类型	B2B dashboard还是consumer app
用户目标	用户打开界面想完成什么

## Context
- Use the provided design system tokens and components
- Evaluate screens in the context of a B2B SaaS dashboard
- Assume users prioritize speed and clarity over aesthetics

## Inputs
- Figma frames
- Design system references
- Product constraints

## Expected behavior
- Focus on usability over visual experimentation
- Prioritize clarity and task completion

没有上下文，Claude可能会给出"视觉更大胆一点""增加动效"之类对B2B产品不合适的建议。

坑3：结构混乱，Claude不知道从哪开始

# ❌ 错误：平铺直叙
帮我审计UI，检查对比度、字体大小、间距、颜色一致性、交互反馈...

# ✅ 正确：结构化
## Step 1: 检查视觉一致性
## Step 2: 检查可访问性
## Step 3: 检查交互反馈
## Step 4: 汇总问题

Claude在步骤化结构下的执行质量远高于平铺指令。

坑4：缺少输入验证

如果Claude没有拿到期望的输入，它不会告诉你"缺东西了"，而是会"猜"着继续执行。

# ✅ 添加输入验证
## Required Inputs
- `design_system`: Figma design system file
- `screens`: Array of Figma frame IDs
- `platform`: "iOS" | "Android" | "Web"

## Validation
If any required input is missing, STOP and report which inputs are needed.

坑5：输出结构模糊

Claude的输出质量很大程度上取决于你期望的格式。

# ✅ 明确输出格式
## Output Format
For each issue found, return:
1. **位置**: Frame name + component path
2. **问题**: One-line description
3. **严重程度**: Critical | Major | Minor
4. **建议**: Specific fix suggestion
5. **依据**: Which design system rule is violated

坑6：重复造轮子

❌ 错误做法	✅ 正确做法
Skill里写"用Python处理数据"	定义输入输出，让Claude自己决定语言
Skill里写死具体路径	用参数化输入
Skill里包含项目特定信息	保持通用，上下文外部提供

Skill应该跨项目可复用，不引用特定路径、技术栈或业务逻辑。

坑7：不与现有工具配合

一个孤立运行的Skill，远不如能和Claude Code现有能力配合使用的Skill。

# ✅ Skill中声明依赖/配合
## Dependencies
- Requires `@claude/read-file` for reading design tokens
- Uses `@claude/screenshot` for capturing UI states
- Outputs compatible with `@claude/review` command

总结：好Skill的检查清单

检查项	说明
☐ 单一职责	一个Skill只做一件事
☐ 上下文完整	产品、平台、用户目标齐全
☐ 步骤化结构	Claude知道从哪开始到哪结束
☐ 输入验证	缺少输入时主动报告
☐ 输出明确	格式可解析，可落地
☐ 可复用	不引用项目特定内容
☐ 可组合	能与其他Skill/工具配合

把一个Skill做专，比做全能重要得多。

---

关键词：Claude Skills, Skills开发, Skill设计, 避坑指南, Figma UI审计, Skills最佳实践, 技能设计