手册 · Bilibili / Agent Skills 系列

Agent Skills 从入门到实战手册

从概念、目录结构和环境搭建，到编写、调试、复用 Skill 的完整入门手册。

← 返回笔记列表查看原始来源 ↗
来源
原始内容
整理日期
2026-08-31

来源：原始内容 整理日期：2026-08-31

基于 B 站课程《【小白教程】手摸手彻底掌握 Agent Skills！让你少走99%的弯路！》第 1–6 集字幕整理。

课程目标：理解 Agent Skills 的作用与结构，搭建开发环境，手写一个简单 Skill，扩展到调用脚本生成图片，再使用 Skill 创建 Skill，最后学会复用现成 Skill。

0. 先看结论：Skill 到底是什么

可以把 Agent Skill 理解成一个“可复用的任务能力包”：它不只是告诉模型一句话，而是把完成某类任务所需的说明、流程、参考资料、脚本和资源组织起来，让 Agent 在需要时按流程执行。

0.1 与普通提示词的区别

对比项 提示词 Agent Skill
形态 一段文本输入 一个结构化能力模块
适合任务 翻译、摘要、简单问答等单步任务 文档处理、表格处理、生成图片等多步骤流程
可复用性 每次使用可能需要重新调整 封装后可重复触发
外部能力 主要依赖模型自身知识 可以调用 API、脚本、代码、数据源和文件
执行逻辑 通常没有明确的程序流程 可以包含判断、循环、依赖安装和结果校验
加载方式 输入即处理 通常先根据名称和描述匹配，命中后再按需加载详细内容

直观比喻：提示词像向一位专家提问；Skill 像委托一个工作小组完成任务。工作小组可以查资料、写大纲、调用工具、执行代码并交付最终结果。

0.2 课程中反复出现的术语纠正

字幕中因语音识别出现了“scale”“score”“SKYE”等写法，本手册统一按 Skill / Agent Skill 理解；“Cloud Code”等产品名也应以实际产品官方名称和当前文档为准。课程演示中的软件、模型、仓库地址、价格和可用额度可能随时间变化，安装或接入前请重新查看官方文档。

1. Skill 的基本结构

课程用“程序员完成一个项目”来类比 Skill 的组成：

典型目录如下：

my-skill/
├── SKILL.md              # 必需：名称、描述、指令、流程
├── references/           # 可选：补充文档、规则、模板说明
├── scripts/              # 可选：可执行脚本、API 调用代码
└── assets/               # 可选：图片、模板、音视频等静态资源

1.1 哪些是必需的

课程强调：只有 SKILL.md 是必需品。其余目录按任务需要添加：

不要为了“目录看起来完整”而盲目创建所有文件夹；目录应服务于实际工作流。

1.2 SKILL.md 的两部分

课程演示中的 SKILL.md 主要由两部分组成：

  1. Front matter / 元信息
    • Skill 名称
    • Skill 描述
    • 用来说明“这个 Skill 能做什么、什么时候应该被调用”
  2. 指令正文
    • 品牌或业务背景
    • 用户任务
    • 输出格式
    • 具体执行流程
    • 质量要求与细节建议

可以把元信息理解为 Skill 的“目录卡片”，把正文理解为 Skill 的“工作手册”。Agent 通常先通过名称和描述判断是否相关，命中后再读取更详细的指令。

1.3 为什么描述要写清楚

课程以“为餐厅生成物料设计创意”为例。描述越明确，Agent 越容易判断：

建议描述至少包含：适用对象 + 能解决的任务 + 典型触发场景 + 主要输出。

2. 第一步：搭建开发环境

课程演示了 Windows 环境，但核心角色在其他系统上也成立。你可以根据自己的系统、权限和组织规范替换具体软件。

2.1 三类工具

工具角色 课程中的工具 作用
编辑器 VS Code，也可使用熟悉的编辑器 创建目录、编辑 SKILL.md、查看脚本与资源
Agent 宿主 Claude Code 等 Agent 工具 对话式调用 Skill、执行任务和脚本
模型切换工具 CC Switch 等配置工具 配置不同模型供应商或模型

课程表达的重点不是必须使用某一个软件，而是要准备：能编辑 Skill 文件的开发工具、能加载 Skill 的 Agent、能配置可用模型的方式。

2.2 环境搭建流程

  1. 从软件官方渠道下载编辑器并完成安装。
  2. 打开编辑器，按需要安装中文语言包；习惯英文则可以跳过。
  3. 安装 Agent 宿主，按照当前官方文档完成登录、授权和基础验证。
  4. 安装模型切换工具，添加你实际拥有权限和额度的模型供应商。
  5. 创建或选择一个工作目录，用于存放项目和 Skill。
  6. 在 Agent 宿主中确认能正常对话，并确认当前使用的模型。

2.3 模型供应商配置的通用步骤

课程以 API Key 和模型选择为例，通用流程如下：

  1. 在供应商官方开放平台创建 API Key。
  2. 将 Key 写入 Agent 工具要求的安全配置位置，不要提交到 Git，不要写进 SKILL.md。
  3. 检查账户余额、调用额度和模型权限。
  4. 填写正确的请求地址与当前仍受支持的模型名称。
  5. 保存配置并启用该供应商。
  6. 回到 Agent 对话窗口，询问“当前使用的模型是什么”，验证配置是否生效。

安全提醒：不要复制课程演示中的 API Key；不要在聊天记录、截图、代码仓库或公开 Skill 中暴露凭证。模型名称、接口地址和额度以供应商当前文档为准。

2.4 环境验收清单

3. 第二步：手写第一个简单 Skill

课程案例是餐厅创意物料 Skill。它只生成设计创意文本，不直接生成图片，适合用来理解最小可用结构。

3.1 创建目录

下面是抽象后的目录流程：

项目目录/
└── skills/
    └── restaurant-creative/
        └── SKILL.md

操作原则：

  1. 先确定 Agent 能扫描到的 Skill 目录。
  2. 在该目录下创建 skills/。
  3. 每个 Skill 使用独立子目录。
  4. 在 Skill 子目录中创建大写文件名 SKILL.md。
  5. 先只创建必需文件，后续有需要再添加 references/、scripts/ 和 assets/。

3.2 一个最小可用的 SKILL.md

下面的示例保留课程思路，但将品牌名和内容改成可替换模板：

---
name: restaurant-creative
 description: 为餐厅生成符合品牌调性的海报、易拉宝、工服和包装盒设计创意。
---

# 餐厅创意物料 Skill

## 品牌核心元素

- 品牌名：示例餐厅
- 品牌风格：温暖、年轻、轻松
- IP 形象：猫咪
- 主色调：暖橙色与深棕色
- Slogan：把每次见面都变成好味道

## 任务

当用户要求制作海报、易拉宝、工服或包装盒时，生成对应物料的设计创意。

## 输出格式

1. 物料类型
2. 创意主题
3. 视觉风格
4. 画面构成
5. 文案建议
6. 细节与落地建议

注意：上面只展示课程思想的模板，具体 front matter 字段、目录位置和加载规则应以你正在使用的 Agent 官方规范为准。示例中的 description 前多余空格也应在实际文件中修正为规范 YAML。

3.3 测试流程

  1. 保存 SKILL.md。
  2. 如果 Agent 没有立即识别新 Skill，关闭并重新启动编辑器或 Agent，让它重新扫描目录。
  3. 使用斜杠命令、Skill 列表或当前 Agent 支持的触发方式搜索 Skill 名称。
  4. 直接触发 Skill，例如：
帮我设计一张周末啤酒免费的餐厅海报，只需要输出设计创意。
  1. 检查输出是否包含主题、风格、构图、文案和细节建议。
  2. 如果结果不稳定，回到 SKILL.md 增加品牌约束、输出格式和判断条件。

3.4 为什么“详细描述”很重要

“帮我做一张海报”信息不足，Agent 很难稳定产出；以下信息越清楚，结果越可控：

但不要把所有内容无条件塞进一个文件。可复用或只在特定任务中需要的内容，适合拆到 references/ 或其他资源文件中。

4. 第三步：从文本创意扩展到生成图片

这一集的核心是：让 Skill 不仅输出创意描述，还能根据用户选择调用图片生成脚本。

4.1 为什么要拆分文件

如果把海报、包装盒、工服、品牌规范和生图流程全部写入 SKILL.md，文件会越来越长，维护困难。更好的做法是：

这样既能按需加载，也能降低主文件的臃肿程度。

4.2 推荐的流程设计

用户提出物料需求
        ↓
确认物料类型和内容
        ↓
输出创意描述
        ↓
询问：只看创意，还是继续生成图片？
        ├── 只看创意 → 返回文本
        └── 生成图片
                ↓
        询问输出路径
                ↓
        是否有参考图？
                ├── 有 → 分析风格、Logo、构图等元素
                └── 无 → 使用品牌规范构建提示词
                ↓
        调用图片生成脚本
                ↓
        创建不存在的输出目录
                ↓
        保存图片并返回路径

4.3 SKILL.md 中应明确的判断逻辑

建议把以下规则写进指令：

  1. 用户说“做海报”时，先确定物料类型和活动内容。
  2. 先生成详细创意描述。
  3. 询问用户是否需要继续生成图片。
  4. 如果用户只要创意，停止并返回文本。
  5. 如果用户要图片，把创意转换为生图提示词。
  6. 如果有参考图，先分析需要继承的元素，例如色调、Logo、构图和主体风格。
  7. 询问输出路径；未指定时使用约定的默认目录。
  8. 调用脚本时使用完整路径，避免 Agent 因当前工作目录变化而找不到脚本。
  9. 脚本负责创建不存在的目录，并返回成功或失败信息。
  10. 生成失败时说明失败原因，不要假装已经生成成功。

4.4 脚本的职责边界

图片生成脚本应负责机械执行，不应把完整业务决策都藏在代码中。一个清晰的脚本接口至少需要：

示意命令：

python scripts/generate_image.py \
  --prompt "根据品牌规范生成周末啤酒促销海报" \
  --reference assets/logo.png \
  --output images/weekend-beer.png

课程中使用了某个支持文生图和图生图的模型作为演示。实际使用时应替换成你有权限、有额度且当前仍可用的图片模型，并把 API Key 放在环境变量或安全凭证管理中，而不是写在脚本正文里。

5. 第四步：让 Skill 创建 Skill

当 Skill 的目录、指令、参考文档和脚本逐渐复杂后，手写成本会上升。课程介绍了一个“创建 Skill 的 Skill”，通过对话和选择题收集需求，再生成一个新的 Skill。

5.1 它解决什么问题

用户可能知道自己想要的能力，但不知道：

“Skill 创建器”把这些设计工作变成一个向导流程。

5.2 推荐的需求访谈顺序

  1. 目标任务：这个 Skill 要帮你完成什么工作？
  2. 触发方式：用户会说什么话来触发它？
  3. 输入形式：一句话、文件、表格、图片还是多种输入？
  4. 输出形式：文本、Markdown、图片、表格、代码还是文件？
  5. 核心标准：什么结果才算做得好？
  6. 使用频率：偶尔使用，还是高频重复使用？
  7. 执行方式：一步完成，还是分步骤执行？
  8. 作用域：只在当前项目使用，还是全局复用？
  9. 依赖资源：需要参考文档、脚本、模板或参考图片吗？
  10. 测试样例：给出一到三个真实请求，用于验证生成结果。

5.3 课程案例的关键选择

课程用“根据一句话灵感生成现代言情/穿越重生爽文”为例，演示了这些决策：

其中“一次性生成”适合课堂快速演示；真实生产任务通常更适合“先大纲、再章节、再审校”的分阶段流程，便于控制质量、成本和上下文长度。

5.4 生成后的验收

Skill 创建器生成文件后，不要直接视为完成，应检查：

6. 第五步：复用现成 Skill

课程最后强调：大多数情况下不需要从零创建 Skill。对于常见任务，可以先找现成能力，再根据自己的工作流改造。

6.1 课程列举的常见类型

6.2 安装与使用的通用流程

  1. 从可信来源找到 Skill。
  2. 阅读名称、描述、许可证和使用说明。
  3. 检查 SKILL.md、脚本、依赖和网络请求。
  4. 确认它不会读取或上传不必要的敏感文件。
  5. 下载或复制 Skill 到 Agent 可扫描的 skills/ 目录。
  6. 重启或刷新 Agent，让它重新识别。
  7. 先用无敏感数据的样例测试。
  8. 确认输出和副作用后，再接入真实工作流。

6.3 表格 Skill 的课程案例

课程演示了一个表格处理 Skill：

  1. 把 Skill 复制到 Agent 的 Skill 目录。
  2. 让 Agent 找到桌面上的 Excel 文件。
  3. 先将成绩排名改为倒序。
  4. 再把排名前三的整行标红。
  5. 首次运行时等待依赖安装和文件处理。
  6. 如果文件正被 Excel 打开，先关闭文件，避免无法写入。
  7. 处理完成后重新打开文件检查结果。

这个案例体现了使用文件型 Skill 时的三个要点：路径要明确、文件占用要处理、结果要打开复核。

6.4 开源 Skill 集合的使用原则

课程提到过若干 Skill 集合或目录，并展示了大量开源 Skill。数量多不等于质量高，使用前应重点审查：

不要只因为“下载量高”就直接用于生产环境；先在隔离项目和非敏感数据上验证。

7. 从零制作一个业务 Skill：可复制模板

下面是一套适合真实项目的设计顺序。

7.1 先写需求卡

Skill 名称：
解决的问题：
典型触发语句：
输入：
输出：
必须遵守的规则：
禁止做的事情：
需要调用的工具：
需要的参考资料：
需要的静态资源：
验收标准：

7.2 再画执行流程

接收请求
  ↓
判断是否属于本 Skill
  ↓
收集缺失输入
  ↓
加载相关参考资料
  ↓
执行核心步骤
  ↓
调用脚本或外部工具
  ↓
校验结果
  ↓
按约定格式输出

7.3 最后拆目录

8. 质量检查与常见问题

8.1 Agent 找不到新 Skill

排查顺序：

  1. 确认目录是否放在 Agent 实际扫描的位置。
  2. 确认目录名和文件名是否符合规范。
  3. 确认 SKILL.md 使用了正确的大写文件名。
  4. 检查 front matter 是否有格式错误。
  5. 重启编辑器或 Agent 触发重新加载。
  6. 使用当前 Agent 支持的 Skill 列表或斜杠命令搜索。

8.2 Skill 被错误触发

通常是描述太宽泛。改进方式：

8.3 输出格式不稳定

不要只写“输出高质量结果”，而要写成可检查的结构：

输出必须包含：
1. 结论
2. 依据
3. 风险
4. 下一步

缺少必要信息时：
- 先列出缺失字段；
- 不要自行编造；
- 说明需要用户补充什么。

8.4 脚本执行失败

检查：

8.5 Skill 越写越大

把内容按“核心流程”和“按需资料”拆开：

同时删除重复规则，避免同一要求在多个文件中互相冲突。

9. 安全与工程化注意事项

  1. 凭证不进 Skill：API Key、Cookie、Token 和密码使用环境变量或凭证管理。
  2. 先审查再安装：阅读 Skill 的脚本、依赖和网络请求。
  3. 最小权限：只给 Agent 完成任务所需的目录和权限。
  4. 敏感数据脱敏：先用虚拟文件和非敏感数据测试。
  5. 外部调用可追踪：记录调用的服务、模型、输入文件和输出路径。
  6. 失败必须显式：脚本报错、额度不足或生成失败时，不要返回“已完成”。
  7. 结果要复核：尤其是表格、文档、图片和代码，必须打开或运行检查。
  8. 版本固定：生产使用时记录 Skill 版本、脚本版本和依赖版本。
  9. 作用域明确：区分当前项目 Skill 与全局 Skill，避免污染其他项目。
  10. 控制副作用：涉及删除、覆盖、发送、发布、上传等操作时，应先确认目标和范围。

10. 练习路线

练习 1：文本型 Skill

创建一个“测试用例整理 Skill”：输入需求描述，输出功能点、前置条件、步骤、预期结果和优先级。

验收：同一需求重复运行时，输出字段稳定，缺失信息会被明确标出。

练习 2：引用型 Skill

为练习 1 增加 references/，放入测试用例命名规范和优先级规则。

验收：Skill 能按规则输出，而不是只依赖模型临时发挥。

练习 3：脚本型 Skill

增加一个脚本，将生成的 Markdown 测试用例转换为 CSV 或 Excel。

验收：脚本能处理正常输入、空输入、非法字段和输出目录不存在四种情况。

练习 4：资源型 Skill

增加 assets/，放入统一模板、示例图片或项目 Logo。

验收：生成结果能使用指定模板和品牌元素，且不会把资源路径写死在不可迁移的位置。

练习 5：Skill 创建 Skill

用一个现成的 Skill 创建器生成练习 1 的初稿，再人工检查和修改。

验收：理解“自动生成目录”与“真正可用的业务能力”之间的区别，能补齐触发条件、错误处理和测试用例。

11. 一页复习卡

来源与边界

本手册的课程事实主要来自第 1–6 集字幕；章节标题、目录结构归纳、模板示例、质量检查和安全建议是基于字幕内容的学习整理，不等同于视频官方逐字稿。视频中提到的具体软件、模型、仓库数量、版本、价格和额度可能已经变化，使用前请以对应官方文档为准。

完整字幕、元数据、时间轴和获取边界说明见：字幕副产物索引。