AI 知识课程

Appearance

2.1 第一个技能包——从 5 行开始 ​

什么是技能包？ ​

技能包是 AI 编程工具的可复用能力单元。它解决的核心问题是：

每次和 AI 对话都要重复说明同样的要求——代码风格、审查标准、部署流程……能不能把这些"一次性说清楚，后续自动应用"？

技能包的本质：

  • 一次定义：把重复的指令写成一个配置文件
  • 自动加载：AI 在合适的时机自动读取并应用
  • 按需触发：通过命令或对话触发特定能力

各工具的技能包实现 ​

工具实现方式文件结构触发方式
Claude CodeSkills 目录.claude/skills/name/SKILL.md/name 命令或自动发现
CursorCustom Commands设置 → Commands → 自定义快捷键或手动调用
WindsurfCascade Rules.windsurfrules 内规则块Cascade 自动匹配文件路径
ClineCustom Instructions.clinerules 或设置配置自动或手动
CopilotChat PromptsVS Code 设置手动调用

📋 课程说明

本节以 Claude Code 为详细示例（因其功能最完整、语法最直观），但核心概念适用于所有工具。如果你使用其他工具，请参考上表理解等效实现方式。

小王的第一个技能包（Claude Code 示例） ​

小王决定动手了。他打开编辑器，在项目下创建了一个文件：

.claude/skills/hello/SKILL.md

5 分钟后，他在 Claude Code 中输入 /hello——Claude 向他打招呼，并告诉他当前时间。

这就是技能包。 没有安装命令，没有编译步骤，没有配置文件。一个 Markdown 文件，就能给 AI 装上新的能力。

创建你的第一个技能包（Claude Code 详细教程） ​

Step 1：创建目录 ​

bash
mkdir -p .claude/skills/hello

Step 2：写入 SKILL.md ​

markdown
---
name: hello
description: 向用户打招呼并报告当前时间
---

你好！当前时间是：

!`date`

请向用户打招呼，并告诉他们当前时间。

Step 3：测试 ​

在 Claude Code 中输入 /hello。

如果你看到了 Claude 的问候和当前时间——恭喜，你已经创建了第一个技能包！

这 5 行做了什么？ ​

逐行拆解：

markdown
---                         ← 配置块起始标记
name: hello                 ← 技能包的名字（决定 /hello 命令名）
description: 向用户打招呼... ← Claude 用它判断何时自动加载
---                         ← 配置块结束标记

你好！当前时间是：           ← 正文：Claude 看到的指令
!`date`                     ← 动态注入：执行 date 命令，结果替换占位符
请向用户打招呼...           ← 正文：Claude 执行的具体任务

三个关键点：

  1. name 决定命令名：目录名是 hello，所以命令是 /hello。也可以通过 name 字段覆盖。
  2. description 决定是否自动加载：Claude 在会话开始时读取所有技能包的 description，判断哪些可能和当前对话相关。
  3. !command`` 是预处理：在 Claude 看到内容之前执行，Claude 看到的是命令输出，不是命令本身。

让技能包自动触发 ​

现在只有手动输入 /hello 才能用。让 Claude 在合适的时机自动调用：

markdown
---
name: hello
description: 向用户打招呼并报告当前时间。当用户说"你好"、"hello"、"几点了"时使用
---

测试：不说 /hello，直接说"你好"或"现在几点了？"——Claude 应该自动加载并使用这个技能包。

💡 描述要"pushy"

Claude 倾向于不自动触发技能包。所以描述可以比直觉更主动一些——明确列出触发短语："当用户说 X、Y、Z 时使用"。

其他工具用户怎么办？ ​

Cursor 用户 ​

  • 在设置中创建 Custom Command
  • 输入相同的 Markdown 内容作为 Prompt 模板
  • 分配快捷键或手动调用
  • Cursor 没有等价的自动触发功能，需手动执行

Windsurf 用户 ​

  • 在 .windsurfrules 中添加规则块：
yaml
hello-command:
  instructions: |
    向用户打招呼并报告当前时间。
    使用命令获取时间并输出。
  • Windsurf 没有等价的 /命令 触发方式，需通过 Cascade 自动分析触发

Cline/Copilot 用户 ​

  • 在插件设置中配置 Custom Instructions
  • 各插件实现方式不同，请参考插件文档

添加参数（Claude Code 特性） ​

让技能包支持自定义问候对象：

markdown
---
name: hello
description: 向用户打招呼并报告当前时间
argument-hint: "[name]"
arguments:
  - name
---

向 $name 打招呼！当前时间是：

!`date`

请热情地向 $name 问好，并告诉他们当前时间。

测试：输入 /hello 小明，Claude 会向小明打招呼。

参数系统（Claude Code 特性）：

  • arguments 定义命名参数的顺序
  • $name 在正文中引用参数值
  • argument-hint 在自动补全时显示提示（如 [name]）
  • 也可以用 $ARGUMENTS（全部参数）或 $0、$1（按索引）

⚠️ 参数是 Claude Code 特有功能

Cursor、Windsurf 等工具的参数传递方式不同，通常需要在 Prompt 中手动描述参数占位符。

变量替换速查（Claude Code） ​

变量含义示例
$ARGUMENTS所有参数/fix 123 urgent → "123 urgent"
$0、$1按索引的参数/fix 123 urgent → $0 = 123
$name命名参数arguments: [issue-num] → $issue-num
${CLAUDE_SESSION_ID}当前会话 ID用于日志记录
${CLAUDE_SKILL_DIR}技能包所在目录用于引用脚本路径

本节小结 ​

📌 本节核心要点

  • 技能包是可复用能力单元：一次定义、自动加载、按需触发——所有 AI 编程工具都有类似机制
  • 5 行就能创建：目录 + 配置文件，无需安装或编译（Claude Code 示例）
  • 三个核心要素：name（命令名）、description（触发依据）、正文（执行指令）
  • 动态注入是预处理：Claude 看到的是命令输出，不是命令本身（Claude Code 特性）
  • 描述决定自动触发：写好触发短语，AI 才知道何时调用
  • 参数传递方式各异：Claude Code 有 $name 语法，其他工具有不同实现

思考题 ​

  1. （Claude Code 用户）修改你的 /hello 技能包，让它同时显示当前 git 分支名。（提示：用 !git branch --show-current``）
  2. 如果你的 description 只写了"打招呼"，会出现什么问题？你会怎么改进？
  3. 为什么动态命令注入（如 !command``）是预处理而不是让 AI 自己执行？这样做有什么好处？
  4. （其他工具用户）你使用的工具如何实现"打招呼"这个能力？动手尝试创建。

下一节预告 ​

5 行技能包跑通了，接下来看看技能包的完整结构——目录、配置字段和辅助文件。你不需要每次都把所有内容塞进一个文件里。

→ 下一节：结构与配置——各工具的技能文件规范