自学教程

创建第一个 Skill

Skills 教程

本文基于开源仓库 liqiang88/skills‑demo 中的 examples/hello‑world 示例，带你完成第一个最简 Skill。hello‑world 不涉及脚本调用、外部API，仅做文本应答，核心作用是验证本地 Skill 加载环境是否正常，熟悉 SKILL.md 文件格式、目录规范、触发逻辑与渐进式加载原理。

原skills-demo的例子：hello‑world，Cursor Agent 执行结果：

一、前期准备

  1. 安装 VS Code；安装支持 Agent Skills 的AI插件，例如 GitHub Copilot，并开启 Agent（智能体）模式。
  2. 克隆 skills‑demo 仓库到本地，我们直接在该项目中练习：
git clone https://github.com/liqiang88/skills-demo.git
  1. VS Code打开 skills‑demo 项目。

Agent Skills是开放标准，写好的 hello‑world 技能，也可以运行在 Claude Code、Cursor 等兼容Agent Skills的工具。

二、理解示例目录结构

仓库自带示例路径：examples/hello‑world。
Agent Skills有项目默认加载目录：.agents/skills/。

重要强制规范：技能文件夹名称，必须与SKILL.md头部YAML的name字段完全一致，字母、连字符必须完全匹配。

两种使用方式：

  1. 直接使用仓库自带示例：skills‑demo/examples/hello‑world
  2. 将示例复制到默认扫描目录，方便插件自动识别：复制整个 hello‑world 文件夹到 .agents/skills/

复制完成后的目录树：

skills‑demo/
├── examples
│   └── hello‑world
│       └── SKILL.md
└── .agents
    └── skills
        └── hello‑world
            └── SKILL.md

hello‑world属于极简技能，只需要SKILL.md一个文件，不需要examples、templates、scripts等子文件夹。

三、SKILL.md源码解读

打开 hello‑world/SKILL.md，完整参考示例代码如下：

---
name: hello-world
description: Hello‑world最小测试技能，用户输入hello、你好、打招呼、测试技能时触发本技能。
version: 1.0.0
author: skills‑demo
---# Hello‑world 测试技能
## 任务目标
验证Skill是否被正确加载触发，向用户输出提示问候。
## 执行步骤
1. 友好向用户问好；
2. 告知用户 hello‑world 技能已经成功触发；
3. 简单说明Skill的作用。
## 输出规范
- 只做文本输出，不调用终端、脚本；
- 输出友好简洁，参考格式：
> ✋ Hello‑world 技能已成功激活！
> 这是你的第一个Agent Skill，Skill可以将业务流程、经验封装，交给AI智能体自动执行。

文件两大部分

  1. YAML头部元信息（文件最上方，---包裹）
  • name：技能唯一标识符，和文件夹名必须完全一致；
  • description：触发核心，Agent扫描该描述判断是否启用技能，需要覆盖用户提问关键词；
  • version：版本号，用于迭代管理；
  • author：作者标识。
  1. Markdown正文
    技能激活之后，AI需要严格遵守的规则，包含任务目标、执行步骤、输出格式约束。

编辑完成保存文件 Ctrl+S。

四、加载与测试 hello‑world

  1. VS Code打开Copilot Chat面板，底部切换为 Agent智能体模式。
  2. 在聊天框输入 /skills，查看已加载技能列表，确认列表中出现 hello‑world。

如果列表看不到技能，请排查：
① 文件路径，确认文件夹放置在插件扫描目录 .agents/skills/；
② 文件夹名称与YAML中name完全一致；
③ 文件名为大写 SKILL.md，不能小写；
④ 修改文件后，重启会话或者刷新技能列表。

  1. 输入测试提问，例如：你好，测试技能。

✅ 预期行为：Agent匹配描述关键词，自动激活 hello‑world，严格按照输出规范返回问候文本。

❌ 常见问题：

  1. AI没有触发技能，只是普通对话回答：优化description的关键词，刷新技能列表，尝试切换模型；
  2. 输出内容和预期不一样：调整SKILL.md的执行步骤、输出规范，保存后重新测试。

五、底层运行原理：渐进式披露

hello‑world虽然简单，但完整走完Agent Skills的标准三阶段工作流程：

  1. 发现阶段
    会话初始化，Agent扫描技能目录，仅读取所有技能的name和description元信息，不会加载完整SKILL.md，减少Token消耗。
  2. 激活阶段
    用户提问和description描述匹配，此时才将完整的SKILL.md全部加载进入上下文。
  3. 执行阶段
    AI读取任务目标、执行步骤、输出规范，按照文档规则输出结果。

和临时提示词对比：提示词只在单次对话生效；Skill保存在本地文件夹，支持Git版本管理，可重复调用、分享。

六、基于 skills‑demo 的练习拓展

  1. 版本管理，在项目根目录提交修改：
git add .
git commit -m "hello‑world：第一个测试技能"
  1. 修改练习：修改SKILL.md中的问候话术、新增触发关键词，保存重新测试，观察AI输出变化。
  2. 进阶练习：为hello‑world新增examples文件夹，增加输入输出样例，让AI输出行为更加稳定。

小结

hello‑world是Skill的最小原型，掌握3个关键点：

  1. 文件夹名与name字段必须完全一致；
  2. description是技能触发开关；
  3. 文件分为YAML元信息 + Markdown正文；依靠渐进式加载，按需读取完整技能。

成功跑通hello‑world，代表你的Skill开发环境就绪。后续复杂的文档处理、命令调用Skill，都只是在这套基础结构之上，增加模板、脚本、测试用例。

文字流程示意图
用户提问：你好，测试技能
        ↓
Agent扫描目录，读取所有技能name+description【发现阶段】
        ↓
匹配 hello‑world，加载完整 SKILL.md【激活阶段】
        ↓
按照步骤、输出规范返回问候文本【执行阶段】
        ↓
输出：✋ Hello‑world 技能已成功激活！……
标签：

0 条笔记