Skills快速入门

理论说够了，这一篇直接动手写一个 Skill，并在 Claude 中实际使用它。

1. Skill 存放位置

不同 Claude 产品的 Skill 目录略有不同：

产品	个人 Skill 目录	项目 Skill 目录
Claude Code	`~/.claude/skills/`	`<project>/.claude/skills/`
Claude.ai 桌面	（通过界面上传/管理）	-
API / SDK	任意目录，启动时指定	-

本篇以 Claude Code 为例（命令行工具，最方便测试）。

2. 创建第一个 Skill

我们写一个简单的 Skill：自动给 Python 函数加文档字符串。

创建目录

mkdir -p ~/.claude/skills/python-docstring
cd ~/.claude/skills/python-docstring

写 SKILL.md

touch SKILL.md

填入内容：

---
name: python-docstring
description: 当用户要求为 Python 函数生成或补全 docstring 时使用，按照 Google 风格生成详细的文档字符串
---

# Python Docstring 生成器

当用户要求生成或补全 Python 函数的文档字符串时，请按以下规范生成。

## 风格

使用 **Google 风格**的 docstring，结构如下：

```python
def function_name(param1: int, param2: str) -> bool:
    """简短的一句话描述函数功能。

    更详细的多行描述（可选），解释函数做什么、为什么、注意事项。

    Args:
        param1: 参数说明，简洁有力。
        param2: 参数说明。

    Returns:
        返回值说明。

    Raises:
        ValueError: 什么情况下会抛出。
    """
```

## 要点

1. **第一行**：祈使句开头，不超过 80 字符
2. **空一行**后写详细说明（如果需要）
3. **Args / Returns / Raises** 三段式
4. 类型已经在签名里的，不要在 docstring 重复写类型
5. 简单函数（< 5 行）可以省略详细说明，只保留一行总结

## 输出

- 直接输出补全 docstring 后的完整函数代码
- 不要解释你做了什么修改
- 如果函数已经有 docstring，根据规范优化它

3. 在 Claude Code 中验证

启动 Claude Code：

claude

新建一个测试文件 test.py：

def calculate_discount(price, discount_rate, max_discount=None):
    if discount_rate < 0 or discount_rate > 1:
        raise ValueError("Discount rate must be between 0 and 1")
    discount = price * discount_rate
    if max_discount is not None:
        discount = min(discount, max_discount)
    return price - discount

向 Claude 发送：

帮我给这个 calculate_discount 函数加上 docstring

Claude 会：

识别这是 Python docstring 任务
找到 python-docstring Skill
读取 SKILL.md 详细内容
按照规范生成 docstring

输出类似：

def calculate_discount(price, discount_rate, max_discount=None):
    """计算商品折扣后的价格。

    Args:
        price: 商品原价。
        discount_rate: 折扣率，0~1 之间，0.2 表示打 8 折。
        max_discount: 最大折扣金额，超过则按此金额封顶。默认无上限。

    Returns:
        折扣后的最终价格。

    Raises:
        ValueError: 当 discount_rate 不在 [0, 1] 范围内。
    """
    if discount_rate < 0 or discount_rate > 1:
        raise ValueError("Discount rate must be between 0 and 1")
    discount = price * discount_rate
    if max_discount is not None:
        discount = min(discount, max_discount)
    return price - discount

完美。

4. 理解 frontmatter

SKILL.md 顶部的 yaml 是关键：

---
name: python-docstring
description: 当用户要求为 Python 函数生成或补全 docstring 时使用，按照 Google 风格生成详细的文档字符串
---

字段	说明
`name`	Skill 唯一标识，用 kebab-case
`description`	关键字段，Claude 用它判断什么时候启用这个 Skill

description 必须清晰说明使用场景。模型只看 description 决定是否加载完整 SKILL.md，写得越精准，触发越准确。

✅ 好的 description

当用户要求生成或补全 Python 函数的 docstring 时使用，按 Google 风格输出

❌ 差的 description

Python 文档工具

后者太模糊，模型不知道什么时候该用。

5. 写第二个 Skill：Git Commit Message

继续添加一个 Skill，让 Claude 帮我们写规范的 commit message：

mkdir -p ~/.claude/skills/git-commit-message
cd ~/.claude/skills/git-commit-message

SKILL.md：

---
name: git-commit-message
description: 当用户要求生成、撰写或改进 git commit message 时使用，按 Conventional Commits 规范生成
---

# Git Commit Message 生成器

按 [Conventional Commits](https://www.conventionalcommits.org/) 规范生成 commit message。

## 格式

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

<body>

<footer>
```

## type 类型

| type | 用于 |
|---|---|
| `feat` | 新功能 |
| `fix` | bug 修复 |
| `docs` | 文档变更 |
| `style` | 代码格式（不影响逻辑） |
| `refactor` | 重构（既非新功能也非 bug 修复） |
| `perf` | 性能优化 |
| `test` | 增加或修改测试 |
| `chore` | 构建过程或辅助工具变动 |

## subject 要求

- 50 字符以内
- 祈使句（"add", "fix", "update"，不是 "added", "fixed"）
- 首字母小写
- 末尾不加句号

## body 要求

- 每行 72 字符以内
- 解释**做了什么**和**为什么**，而不是"怎么做"
- 与 subject 之间空一行

## footer 要求

- 引用相关 issue：`Refs: #123` 或 `Closes: #456`
- breaking change 用 `BREAKING CHANGE:` 开头说明

## 输出

- 只输出 commit message，不要其他文字
- 如果用户提供了 git diff，直接根据 diff 写
- 如果信息不够，主动问用户补充

6. 触发 Skill 测试

git diff

把 diff 复制给 Claude：

帮我根据下面的 diff 写 commit message：

diff --git a/auth.py b/auth.py
-    return user.password == password
+    return bcrypt.checkpw(password.encode(), user.password_hash)

Claude 会调用 git-commit-message Skill，输出：

fix(auth): replace plaintext password comparison with bcrypt

Plain comparison made the system vulnerable to timing attacks
and required storing passwords in cleartext. Switch to bcrypt
to hash on storage and use constant-time comparison.

7. 列出已有 Skills

Claude Code 提供命令查看：

claude skills list

或在 Claude Code 中直接问：

列出我有哪些 skills

Claude 会读取 ~/.claude/skills/ 列出所有可用 Skill。

8. 个人 Skill vs 项目 Skill

个人级（`~/.claude/skills/`）

跟着用户走，所有项目都可以用。适合：

通用习惯（commit message 风格、docstring 风格）
个人工具（自己常用的检查清单）

项目级（`<project>/.claude/skills/`）

跟着项目走，只在该项目下生效。适合：

项目特定的代码规范
业务领域知识
团队共享（提交到 git）

如果同名 Skill 都存在，项目级优先，可以覆盖个人级。

9. 调试技巧

验证 frontmatter

YAML 格式错了 Skill 不会加载。可以用：

python -c "import yaml; print(yaml.safe_load(open('SKILL.md').read().split('---')[1]))"

看 Claude 是否加载了 Skill

直接问：

你看到了哪些 skills？请列出每个的 name 和 description。

如果回答中没有你的 Skill，可能是路径错了或 frontmatter 有问题。

强制使用某个 Skill

测试时可以显式让 Claude 用：

用 git-commit-message skill 帮我写

10. 常见错误

错误 1：description 写得太通用

description: 帮助处理代码

模型不知道什么时候用，可能完全不触发。

错误 2：放错位置

skills 必须在 ~/.claude/skills/<skill-name>/SKILL.md，不是 ~/.claude/SKILL.md。

错误 3：文件名错误

必须是 SKILL.md（全大写），不是 skill.md 或 Skill.md。

错误 4：YAML 缩进错

frontmatter 严格要求 YAML 格式，缩进、引号、缺少 : 都会导致整个 Skill 加载失败。

总结

Claude Code 的 Skills 目录：个人 ~/.claude/skills/、项目 <project>/.claude/skills/
一个 Skill 是一个文件夹，至少包含 SKILL.md（文件名严格大写）
frontmatter.description 是关键字段，决定 Claude 何时加载这个 Skill
用清晰的"什么场景下使用"语句作为 description
项目级 Skill 优先于个人级，适合团队共享
调试：用问 Claude 列出 skills 来验证是否加载成功