Claude Code 开箱即用已经很强，但真正让它变成「你的」工具的方法是自定义 Skill。我在日常工作中积累了 30+ 个 Skill，覆盖编码工作流、内容创作、context 管理等场景。这篇教程把我踩过的坑和验证过的模式全部摊开，带你从零搭出第一个可用的 Skill。

什么是 Skill？

Skill 是 Claude Code 的模块化能力扩展。每个 Skill 本质上是一个 Markdown 文件，里面写着 Claude 在特定场景下应该遵循的指令、流程和约束。

跟直接在对话里贴一大段 prompt 不同，Skill 的优势在于：

把 Skill 想成你为 Claude 写的 SOP（标准作业程序）。你不需要每次口头交代流程，写成文件丢进去就行。

1. Skill 文件结构

一个 Skill 由一个目录和一个 SKILL.md 文件组成：

目录结构.claude/
  skills/
    my-first-skill/
      SKILL.md          # Skill 主文件
    coding-workflow/
      SKILL.md
    xiaohongshu-copy/
      SKILL.md

Claude Code 会在两个位置查找 Skills：

SKILL.md 的核心结构是 YAML frontmatter + Markdown 指令：

SKILL.md 基本结构---
name: my-skill-name
description: 一句话说清这个 Skill 干什么、什么时候触发
---

# Skill 标题

## 触发条件
当用户要求 XXX 时使用本 Skill。

## 执行流程
1. 第一步做什么
2. 第二步做什么
3. 第三步做什么

## 输出格式
- 格式要求 A
- 格式要求 B

## 示例
(给 Claude 看的输入输出示例)

两个字段最关键：

2. 创建你的第一个 Skill

动手比看文档有用。我们来做一个「Git 提交规范化」Skill — 让 Claude 每次帮你写 commit message 时遵循固定格式。

Step 1: 创建目录

mkdir -p .claude/skills/git-commit-style

Step 2: 编写 SKILL.md

.claude/skills/git-commit-style/SKILL.md---
name: git-commit-style
description: 规范化 Git commit message 格式。当用户要求提交代码、
  创建 commit、写 commit message 时使用。触发词：提交、commit、
  git commit。
---

# Git Commit Style Guide

## 格式规范
所有 commit message 必须遵循以下格式：

```
<type>(<scope>): <subject>

<body>
```

### type 可选值
- feat: 新功能
- fix: 修复 bug
- refactor: 重构（不改功能、不修 bug）
- docs: 文档变更
- style: 代码格式（不影响逻辑）
- test: 增加测试
- chore: 构建/工具链变更

### scope
用模块名或文件名，例如：auth、api、ui

### subject
- 中文或英文均可，保持项目一致性
- 不超过 50 字符
- 不加句号

## 执行要求
1. 先运行 `git diff --staged` 查看变更
2. 根据变更内容选择 type
3. 写出 commit message 并展示给用户确认
4. 用户确认后执行 `git commit`

## 示例
输入：用户说"帮我提交一下"
输出：
```
feat(auth): 添加 OAuth2 登录支持

- 集成 Google OAuth2 provider
- 新增 /api/auth/callback 端点
- 添加 session token 生成逻辑
```

Step 3: 测试

在 Claude Code 中修改一些代码，然后说「帮我提交」。观察 Claude 是否自动使用了你的 commit 格式。如果没有触发，检查 description 是否包含了你说的关键词。

第一次测试建议用 /git-commit-style 手动调用，确认 Skill 内容被正确加载后，再测试自动触发。

3. 实战案例 — 从 30+ Skills 中精选

光看模板学不到设计思路。下面三个是我实际使用的 Skill，每个代表一种典型模式。

01
coding-workflow-default

统一编码工作流 — 强制分支开发 + 测试 + 提交标准

设计动机：Claude Code 默认会直接在当前分支改代码，没有分支隔离。当你同时做多个任务时很容易搞乱。这个 Skill 强制 Claude 走「分支 → 开发 → 测试 → 提交」的标准流程。

frontmatter 片段---
name: coding-workflow-default
description: Unified default skill for all programming tasks.
  Use by default for any coding, debugging, refactor, release,
  or project setup task.
---

指令核心要点：

  • 任何代码变更必须在新分支上进行
  • 提交前必须运行测试
  • commit message 遵循 Conventional Commits
  • 完成后提示用户创建 PR 或合并

关键设计决策：description 写了 Use by default for any coding task，这意味着几乎所有编码相关的对话都会触发。这是有意为之 — 编码工作流应该是全局默认行为，不需要用户记得去调用。

02
xiaohongshu-copywriting

生成小红书爆款文案（标题 + 正文 + 标签）

设计动机：小红书文案有一套独特的语感和结构 — 标题要有数字和情绪词，正文要口语化但不低质，标签要覆盖搜索词。每次跟 Claude 解释这些规则太烦了，写成 Skill 一劳永逸。

frontmatter 片段---
name: xiaohongshu-copywriting
description: 为商品生成爆款小红书风格文案（标题+正文+标签）
---

指令核心要点：

  • 标题公式：数字 + 痛点/好奇 + 品类词，控制在 20 字以内
  • 正文结构：hook → 痛点 → 解决方案 → 使用感受 → CTA
  • 语气约束：像朋友聊天，禁止「首先其次最后」结构
  • 标签要求：5-8 个，包含大词 + 长尾词 + 场景词

关键设计决策：在 Skill 内容里放了 3 个完整的「好文案 vs 坏文案」对比示例。这比写 10 条规则都有效 — Claude 从示例中学到的模式比从抽象规则中学到的更精确。

03
context-checkpoint

Context 快满时自动导出进度，防止信息丢失

设计动机：Claude Code 的 context window 有上限，长对话会触发 auto-compaction（自动压缩），可能丢失关键信息。这个 Skill 在 context 接近上限时，自动把当前任务状态、决策和待办导出到文件，然后 /clear 重新加载。

frontmatter 片段---
name: context-checkpoint
description: Context 管理技能。当 context 接近上限时，自动将
  当前任务状态、决策和待办导出到 checkpoint 文件，然后 /clear
  重新加载。防止 auto-compaction 造成关键信息丢失。
  触发词：/checkpoint、context 快满了、保存进度
---

指令核心要点：

  • 导出内容：当前任务描述、已完成步骤、进行中步骤、待办、关键决策
  • 文件位置：.claude/checkpoints/YYYY-MM-DD-HHMMSS.md
  • 恢复机制：配套的 resume-cp Skill 读取最新 checkpoint 继续工作

关键设计决策：description 中同时写了自动触发条件（「context 接近上限」）和手动触发词（「/checkpoint」）。这样 Claude 在感知到 context 压力时会主动提议保存，用户也能随时手动触发。

4. Skill 设计最佳实践

写了 30+ 个 Skill 之后，以下是我验证过的设计原则：

单一职责

一个 Skill 只做一件事。如果你发现自己在一个 Skill 里塞了「代码审查 + 提交 + 部署」三个流程，拆成三个 Skill。原因：Claude 对焦点清晰的指令执行力远好于大杂烩。

description 是灵魂

description 决定了 Claude 什么时候自动触发这个 Skill。写法要覆盖三个维度：

  1. 功能描述 — 这个 Skill 做什么
  2. 触发场景 — 用户说了什么话时应该触发
  3. 反例（可选） — 什么情况下不应该触发
好的 description 示例description: 生成小红书风格文案。当用户提到"小红书"、"文案"、
  "标题"、"爆款"、"种草"时触发。当用户只是讨论小红书平台趋势
  或运营策略时不触发 —— 只在需要实际生成文案时激活。

放示例，不堆规则

Claude 从具体示例中学到的模式比抽象规则精确得多。与其写 10 条排版规则，不如给 2 个好示例 + 1 个坏示例（标注为什么不好）。

控制长度

每个 Skill 控制在 500-2000 字。超过 2000 字说明你在一个 Skill 里塞了太多东西，考虑拆分。低于 500 字可能指令不够明确，Claude 会自由发挥。

迭代调优

Skill 不是写完就定稿的。每次使用后看 Claude 的输出：

5. 踩坑记录

以下是我（和社区里的用户）实际踩过的坑：

目录名 vs name 字段不匹配
目录叫 my-skill，但 frontmatter 里 name: mySkill。用户输入 /my-skill 时匹配不上。保持一致：目录名 = name 字段，用短横线分隔。
description 写得太模糊
description: 帮助用户完成各种任务 — 这等于没写。Claude 不知道「各种任务」是什么，结果是永远不触发。description 要具体到使用场景和触发关键词。
Skill 内容过长吃掉 context
有人把整本风格指南塞进一个 Skill（5000+ 字）。每次触发都消耗大量 context window，导致后续对话很快达到上限。解法：只放「Claude 做决策时必须知道的信息」，参考文档用链接指向外部文件。
忘记写中文触发词
description 全英文，但用户说中文。Claude 的跨语言匹配不是 100% 可靠的。如果你的用户群说中文，description 里必须包含中文关键词。比如 触发词："小红书""文案""种草""爆款"。
Skill 之间互相冲突
两个 Skill 的 description 覆盖了同样的场景，Claude 不知道用哪个。解法：给 Skill 划清边界，在 description 里写明「本 Skill 处理 X，不处理 Y（Y 由另一个 Skill 负责）」。

总结