AI 原生开放教材

外观

Claude Code & OpenClaw & Codex & WorkBuddy 中文教程课时教程·中文原文 ↗原件 ↓仓库 ↗

第二部分：5分钟快速开始（立即见效） ​

本节目的：用最快速度创建第一个Skill，让你立即看到效果！

⏱️ 预计时间：5-10分钟

2.1 创建你的第一个Skill ​

为什么选这个示例？

  • ✅ 最简单，只需要1个文件夹 + 1个SKILL.md
  • ✅ 效果直观，立即看到输出
  • ✅ 无依赖，不需要安装任何东西
  • ✅ 支持Hot Reloading（修改后自动生效）

目标：创建一个"代码注释生成器"Skill，自动为代码添加中文注释。

步骤1：创建Skill文件夹 ​

这一步要做什么：创建Skill的文件夹（文件夹名必须与skill名称一致）

Windows系统（PowerShell）：

powershell
# 进入你的项目目录
cd C:\你的项目路径

# 创建Skill文件夹（名称必须小写，用连字符）
New-Item -ItemType Directory -Path ".claude\skills\code-commenter" -Force

macOS/Linux系统：

bash
# 进入你的项目目录
cd ~/你的项目路径

# 创建Skill文件夹
mkdir -p .claude/skills/code-commenter

💡 命名规范：

  • 文件夹名必须与YAML中的name字段一致
  • 只能使用小写字母、数字、连字符（-）
  • 不能有空格、下划线或特殊字符

步骤2：创建SKILL.md文件 ​

这一步要做什么：创建Skill的核心定义文件（YAML Frontmatter + Markdown Body）

创建文件 .claude/skills/code-commenter/SKILL.md：

Windows（PowerShell）：

powershell
@'
---
name: code-commenter
description: 当用户要求"添加注释"、"代码注释"或"注释代码"时，自动为代码添加清晰的中文注释
---

# 代码注释生成器

## 角色定义
你是一位经验丰富的代码审查专家，擅长编写清晰、准确、有价值的代码注释。

## 何时激活
当用户说以下内容时激活本Skill：
- "帮我添加注释"
- "给这段代码加注释"
- "代码注释"
- "comment this code"

## 注释原则

### 1. 解释"为什么"而不是"是什么"
（示例代码：Python注释对比）
# ❌ 差的注释：循环遍历列表
for item in items:
    process(item)

# ✅ 好的注释：过滤掉已过期的订单，避免重复发货
for item in items:
    process(item)

### 2. 注释格式规范
- **函数/方法**：说明功能、参数、返回值、异常
- **复杂逻辑**：解释业务背景和设计决策
- **魔法数字**：说明数值含义（如：86400秒 = 24小时）

### 3. 语言要求
- 使用简洁的中文
- 避免废话和自明的注释
- 专业术语保持英文（如API、JWT、JSON）

## 输出格式
直接输出添加注释后的完整代码，不要额外解释或对话。
'@ | Out-File -FilePath ".claude\skills\code-commenter\SKILL.md" -Encoding utf8

macOS/Linux：

bash
cat > .claude/skills/code-commenter/SKILL.md <<'EOF'
# 粘贴上方 Windows 示例中 @' 和 '@ 之间的完整 SKILL.md 内容
EOF

这里不再把同一份 SKILL.md 重写一遍。跨平台差异只在“怎么把文本写入文件”，Skill 本体内容应该完全一致，否则后面排查时会分不清是平台问题还是内容问题。

💡 SKILL.md结构说明：

  • YAML Frontmatter（---包裹）：
    • name：小写、无空格、可用连字符（如code-commenter）
    • description：清晰描述触发场景，Claude用此判断是否激活
  • Markdown Body：详细指令，只在Skill被激活后加载
  • 这实现了"渐进式披露"：元数据常驻内存，指令按需加载

步骤3：验证Skill配置 ​

验证文件结构：

bash
# 查看Skill目录结构
tree .claude/skills/code-commenter/
# 或者用ls
ls -la .claude/skills/code-commenter/

# 预期输出：
# .claude/skills/code-commenter/
# └── SKILL.md

验证YAML格式：

bash
# 查看SKILL.md前几行（YAML部分）
head -n 10 .claude/skills/code-commenter/SKILL.md

# 应该显示：
# ---
# name: code-commenter
# description: 当用户要求"添加注释"...
# ---

步骤4：测试Skill（利用Hot Reloading） ​

Windows（PowerShell）：

powershell
@'
# 代码注释生成规范

## 角色定义
你是一位经验丰富的代码审查专家，擅长编写清晰、准确、有价值的代码注释。

## 注释原则

### 1. 解释"为什么"而不是"是什么"
（示例代码：Python注释对比）
# ❌ 差的注释：循环遍历列表
for item in items:

# ✅ 好的注释：过滤掉已过期的订单，避免重复发货
for item in items:

### 2. 注释格式规范
- **函数/方法**：说明功能、参数、返回值
- **复杂逻辑**：解释业务背景和设计决策
- **魔法数字**：说明数值含义

### 3. 语言要求
- 使用简洁的中文
- 避免废话和重复
- 专业术语保持英文（如API、JSON）

## 输出格式
直接输出添加注释后的完整代码，不要额外解释。
'@ | Out-File -FilePath ".claude\skills\code-commenter\SKILL.md" -Encoding utf8

macOS/Linux：

bash
cat > .claude/skills/code-commenter/SKILL.md << 'EOF'
# 粘贴上方 Windows 示例中 @' 和 '@ 之间的完整 SKILL.md 内容
EOF

步骤5：确认修改被读取 ​

前面已经验证过目录结构，这里只确认文件头还在，避免刚才覆盖时把 YAML frontmatter 写丢：

bash
# 查看SKILL.md前几行（YAML部分）
head -n 10 .claude/skills/code-commenter/SKILL.md

步骤6：测试Skill ​

启动Claude Code：

bash
claude

测试触发：

你：帮我给这段代码添加注释

def calculate_discount(price, user_level):
    if user_level == "vip":
        return price * 0.8
    elif user_level == "svip":
        return price * 0.7
    else:
        return price

预期响应：

python
def calculate_discount(price, user_level):
    """
    根据用户等级计算折扣后的价格

    Args:
        price: 原始价格
        user_level: 用户等级（vip/svip/普通）

    Returns:
        折扣后的价格
    """
    # VIP用户享受8折优惠
    if user_level == "vip":
        return price * 0.8
    # SVIP用户享受7折优惠
    elif user_level == "svip":
        return price * 0.7
    # 普通用户无折扣
    else:
        return price

🎯 Hot Reloading体验：修改SKILL.md后，无需重启Claude Code，下次对话时修改会自动生效！

2.2 验证Skill工作正常 ​

完整验证清单：

  • [ ] .claude/skills/code-commenter/ 目录存在
  • [ ] SKILL.md 文件格式正确（YAML Frontmatter + Markdown Body）
  • [ ] 说"添加注释"等关键词时Claude能识别
  • [ ] 生成的注释符合规范
  • [ ] 修改SKILL.md后自动生效（Hot Reloading）

2.3 恭喜完成！ ​

如果上面的测试都成功了，你已经创建了第一个可用的Skill！

下一步建议：

  • 继续学习第三部分，了解完整的目录结构
  • 尝试为你的工作领域创建专属Skill