Skills 教程

Skills 本质上就是教 AI 按固定流程做事的操作说明书，一旦写好，就能像函数一样反复调用。

我们可以把 Skills 看成把"某类事情应该怎么专业做"这件事，封装成一个可复用、可自动触发的能力模块。

Skills 和传统 Prompt 最大的区别是：按需加载 + 渐进式披露（只在需要时才把厚厚的 SOP 塞进上下文，极大节省 token）。

对比项	普通 Prompt	Skills 机制
每次都要重新描述	是	否（只描述一次）
上下文长度占用	每次全量塞入	渐进式加载（只在触发时才读完整内容）
一致性	依赖每次 prompt 质量	高（固定 SOP + 模板）
复用性	手动复制粘贴	自动匹配 / slash 命令 / 项目共享
维护方式	改一次 prompt 就要重新发	修改 SKILL.md 文件，全局/项目生效

比如我们平时写文章，在没有 Skills 之前，每次都要按以下步骤重复说：

帮我总结文章 → 翻译 → 改成公众号风格 → 加标题 → 输出 Markdown

有了 Skills 之后：

你只需要一句：

使用「技术文章转公众号」Skill

AI 会自动按你设定的步骤执行。

把 AI 想象成一个刚毕业的聪明但没经验的实习生：

普通Prompt = 你每次都要从头教他怎么做事（今天教一遍，明天还得重新教）
Rule / 记忆 = 你给他贴一张"公司行为守则"在工位上（一直生效，但只能管态度和格式）
MCP / Tools = 你给他电脑装了一堆软件和API（他能调用外部工具，但不知道什么时候该用、怎么组合用）
Skills = 你直接给他一整套"岗位培训大礼包"（PDF+流程图+SOP+话术模板+常用脚本），告诉他："当老板让你做这类事情时，就按这个文件夹里的方法来做"

Skills 和传统 Prompt 最大的区别是：按需加载 + 渐进式披露（只在需要时才把厚厚的 SOP 塞进上下文，极大节省 token）。

目前能用 Skills 的主流客户端：

排序	工具名	是否免费使用Skills	推荐人群	技能存放默认路径	备注
1	Claude Code	是（官方）	所有人	~/.claude/skills	标准制定者，生态最全
2	Cursor	是	写代码最常用	~/.cursor/skills	几乎无缝兼容Claude Skills
3	Trae / OpenCode	是	追求性价比	看工具设置	国内用户较多
4	VS Code + 插件	部分支持	已经深度用vscode	插件设置里配置	正在快速跟进
5	扣子/其他国内平台	部分支持	喜欢网页版	平台自带技能市场	有的要会员

Skill 的核心结构

一个 Skill 本质上就是一个 Markdown 文件（文件名固定为 SKILL.md），内容几乎只由下面三段组成：

my-skill/
└── SKILL.md   （唯一必需）

SKILL.md 基本模板:

---
name: your-skill-name
description: What it does and when Claude should use it
---

# Skill Title

## Instructions
Clear, concrete, actionable rules.

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

字段	必需	作用
name	是	唯一标识，小写+连字符
description	是	触发条件（最重要）
allowed-tools	否	限制可用工具
model	否	指定模型
context	否	`fork` = 独立上下文
agent	否	fork 时使用的子代理
hooks	否	Skill 生命周期钩子
user-invocable	否	是否显示在 `/` 菜单

Claude Code Skills

接下来我们以 Claude Code 为例来制作一个简单的 Skill。

Claude Code 按以下顺序查找并加载 Skill（越具体的位置优先级越高）：

级别	路径	生效范围
企业级	通过管理控制台配置（managed settings）	组织内所有用户
个人级	`~/.claude/skills/<skill-name>/SKILL.md`	你所有项目
项目级	`.claude/skills/<skill-name>/SKILL.md`	仅当前项目
插件级	`<plugin>/skills/<skill-name>/SKILL.md`	启用该插件的环境

每个 Skill 就是一个文件夹，文件夹名即技能标识（推荐 kebab-case 小写+连字符）。

最简结构：

~/.claude/skills/
  └── code-comment-expert/          # 技能文件夹名
      └── SKILL.md                  # 唯一必填文件（必须全大写 + .md 小写）

SKILL.md 完整格式：

---                                 #  YAML frontmatter 开始（顶格）
name: code-comment-expert           # 必填：技能名（也是 /slash 命令名）
description: >-                     # 必填：最关键一行！Claude 靠它判断是否加载
  为代码添加专业、清晰的中英双语注释。
  适合缺少文档、可读性差、需要分享审查的代码。
  常见触发场景：加注释、注释一下、加文档、explain this、improve readability

trigger_keywords:                   # 强烈推荐（大幅提升自动触发率）
  - 加注释
  - 注释
  - 加文档
  - explain code
  - document
  - comment this
  - readability

version: 1.0                        # 可选
author: yourname                    # 可选
---                                 # ← YAML 结束

# 这里开始是正文（Markdown）—— Claude 真正执行时的指令

你现在是「专业代码注释专家」。

## 核心原则
- 只在缺少注释或可读性明显不足处添加
- 优先使用英文 JSDoc / TSDoc 风格
- 复杂逻辑 / 非明显意图处额外加一行中文解释
- 注释精炼，每行不超过 80 字符
- 绝不修改原有逻辑

## 输出格式（严格遵守）
1. 先输出完整修改后的代码块（用 ```语言 包裹）
2. 再用 diff 形式展示只改动注释的部分
3. 最后说明加了哪些注释、理由

现在直接开始处理用户提供的代码，不要闲聊。

进阶文件结构（技能变复杂时推荐）

当技能超过 500–800 行，或需要模板/脚本/参考资料时，推荐以下组织方式：

~/.claude/skills/react-component-review/
  ├── SKILL.md                  # 核心指令 + 元数据（建议控制在 400 行内）
  │
  ├── templates/                # 常用模板（Claude 按需读取）
  │   ├── functional.tsx.md
  │   └── class-component.md
  │
  ├── examples/                 # 优秀/反例（给 Claude 看标准）
  │   ├── good.md
  │   └── anti-pattern.md
  │
  ├── references/               # 规范、规则、禁用词表
  │   ├── hooks-rules.md
  │   └── naming-convention.md
  │
  └── scripts/                  # 可执行脚本（需开启 code execution）
      ├── validate-props.py
      └── check-cycle-deps.sh

在 SKILL.md 中引用方式示例：

Markdown需要给出标准函数组件时，参考 templates/functional.tsx.md 的结构。

如果违反 Hooks 规则，对照 references/hooks-rules.md 第 3–5 条说明。

如需校验 propTypes，可执行 scripts/validate-props.py "{代码片段}"。

Claude 看到路径引用后，会按需加载对应文件，而不是一次性全部塞入上下文，极大节省 token。

第一个 Skill

让我们暂时忘掉复杂的创建过程，先从 使用一个现成的 Skill 开始，感受它带来的便利。

创建 Skill 目录

Skills 存放在 ~/.claude/skills/（个人全局）或项目目录下的 .claude/skills/（项目专用）。

本章节再项目目录下测试，先创建个目录 claude-test:

mkdir claude-test

进入该目录，创建 skills 的目录与文件：

mkdir -p .claude/skills/python-naming-standard

编写配置文件 SKILL.md

在目录下创建 SKILL.md，这是 Skill 的大脑，告诉 Claude 什么时候用它。

---
name: Python 内部命名规范技能
description: 当用户要求重构、审查或编写 Python 代码时，请参考此规范。
---

## 指令
1. 所有的内部辅助函数必须以 `_internal_` 前缀命名。
2. 如果发现不符合此规则的代码，请自动提出修改建议。
3. 在执行 `claude commit` 前，必须检查此规范。

## 参考示例
- 正确：`def _internal_calculate_risk():`
- 错误：`def _calculate_risk():`

字段要求：

name：必须仅使用小写字母、数字和连字符（最多 64 个字符）
description：Skill 的简要描述及其使用时机（最多 1024 个字符）

创建完后文件结构如下：

你的项目现在看起来应该是这样的：

my-project/
├─ src/
│  └─ test.py              # 项目源码
├─ .claude/
│  ├─ skills/
│  │  └─ hello-world/
│  │     ├─ skill.md       # Skill 定义（YAML + Instructions，机器可执行）
│  │     └─ README.md      # Skill 说明（人类阅读，可选）
│  └─ config.yml           # Claude 项目级配置（可选）
├─ .gitignore
└─ README.md               # 项目整体说明

接下来我们再终端执行以下命令启动 Claude Code：

claude

输入任务：

帮我写一个计算用户折扣的函数

Claude 就会会扫描已安装的 Skills，发现你的请求涉及 "Python 代码编写"，匹配了 python-naming-standard。

它会根据 SKILL.md 中的要求，生成如下代码：

def _internal_get_discount(user_score):
    # 计算逻辑...
    return discount

添加资源文件（可选）

另外我们可以在 .claude/skills/ 下添加以下目录：

在同一文件夹添加：

examples/：存放示例文件。
references/：存放参考文档。
scripts/：存放可执行脚本（例如 Python 处理 PDF）。

然后在 SKILL.md 中引用：

查看示例 commit：./examples/good-commit.txt
运行脚本：使用工具执行 ./scripts/process.py

菜鸟教程 -- 学的不仅是技术，更是梦想！

Skills 教程

Skill 的核心结构

Claude Code Skills

进阶文件结构（技能变复杂时推荐）

第一个 Skill

创建 Skill 目录

编写配置文件 SKILL.md

添加资源文件（可选）

点我分享笔记

菜鸟教程 -- 学的不仅是技术，更是梦想！

Skills 教程

Skill 的核心结构

Claude Code Skills

进阶文件结构（技能变复杂时推荐）

第一个 Skill

创建 Skill 目录

编写配置文件 SKILL.md

添加资源文件（可选）

点我分享笔记

微信关注