如何从零开发 AI 编程助手 Skill 可运行自定义技能

一、本章前言 & 学习前置说明

doubao_image_1_1781855219192.png

1.1 本篇定位

本章是整套 Skill 系列教程的首个落地实战章节，承接前三篇所有理论基础（核心概念、目录规范、YAML 语法规则），摒弃空洞理论，全程采用手把手实操教学。零基础读者只需跟随步骤复刻操作，即可搭建出第一个可正常触发、稳定运行的专属 AI 技能，顺利完成「理论认知 → 落地实操」的核心跨越。

1.2 前置准备（必看）

正式开始实操前，请务必完成以下准备工作，从根源规避操作报错、技能失效等问题：

  • 安装主流 AI 编程助手，支持 Claude Code、CodeBuddy、Cursor 任意一款工具
  • 掌握 Skill 两类部署路径的区别，新手优先选择用户级全局路径（全项目生效）
  • 配备任意文本编辑器，推荐 VS Code，记事本、Typora 等工具均可使用
  • 熟练基础文件操作，包含新建文件夹、创建 Markdown 文件、修改文件后缀等操作

1.3 本章学习目标

完成本章全部实操学习后，你将熟练掌握全套新手核心能力，具体如下：

  • 熟练套用标准化 SKILL.md 正文通用模板，适配多数新手场景
  • 独立完成「创建目录文件 → 编写 YAML 配置 → 撰写技能正文 → 补充实战示例」全流程
  • 吃透 Before/After 对比示例、分步检查点的落地使用规范
  • 掌握 自动触发、手动触发两种 Skill 测试方式，适配不同使用场景
  • 快速排查技能不触发、执行异常、输出不规范等基础常见问题

二、零基础通用 SKILL.md 标准正文模板

doubao_image_4_1781855228942.png

结合前文理论知识点，我们总结出一套小白通用、高适配、高识别度的 SKILL.md 正文标准模板，可覆盖 90% 新手简易技能场景，后续所有实战案例均可直接复用，大幅降低创作成本。

模板由 7 大核心模块组成，逻辑闭环、层级清晰，能有效提升 AI 解析准确率，彻底避免 AI 自由发挥：

  1. 技能概述：简洁说明技能核心功能、解决的痛点与使用价值
  2. 前置条件：明确技能运行所需的环境、文件、项目基础要求
  3. 适用/不适用场景：划定技能使用边界，杜绝误触发、错执行问题
  4. 分步执行步骤：采用编号祈使句指令，逻辑清晰、无歧义，约束 AI 执行流程
  5. Before/After 示例：提供直观参考标准，强制 AI 1:1 复刻规范格式
  6. 检查点校验：分步校验执行结果，实现“错即停”，降低排错成本
  7. 最终验证方式：全流程收尾校验，确认技能完整生效、无异常

以下为可直接复制使用的完整空白模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 技能名称
## 一、技能概述
简单说明本技能的核心功能、解决的问题、使用价值。

## 二、前置条件
1. 执行本技能需要满足的环境/文件基础条件
2. 对应项目/文件类型要求

## 三、适用与不适用场景
✅ 适用场景：明确哪些需求可以使用本技能
❌ 不适用场景：明确哪些需求禁止使用本技能

## 四、分步执行步骤
### Step 1：第一步操作
清晰直白的祈使句指令，明确AI需要执行的动作
**检查点**：执行对应命令/操作，验证本步骤是否完成

### Step 2：第二步操作
清晰直白的祈使句指令，明确AI需要执行的动作
**检查点**：执行对应命令/操作，验证本步骤是否完成

## 五、代码示例（Before / After）
### 常规场景
**修改前（Before）**
```代码类型
原有代码/文本内容

修改后（After）

1
规范修改后的代码/文本内容

执行以下命令/操作，确认整体任务完成、无异常：

三、5分钟实战：从零制作首个 Skill（Go 单元测试生成）

doubao_image_6_1781855371374.png
本次实战选用Go 语言单元测试自动生成技能作为案例，该场景通俗易懂、逻辑简洁、落地效果直观，是新手入门 Skill 开发的最优场景之一。全程严格遵循「创建目录 → 编写 YAML 配置 → 撰写技能正文 → 补充实战示例」的标准化开发流程。

3.1 第一步：创建标准 Skill 目录与文件

1、进入用户级全局 Skill 目录（全局生效，适配所有项目，新手首选）：

  • CodeBuddy 默认路径：~/.codebuddy/skills/
  • Claude Code 默认路径：~/.claude/skills/

2、新建技能专属文件夹，严格遵循官方命名规范：小写英文+连字符，文件夹名称统一为go-test-gen。

3、进入该文件夹，创建技能核心配置文件，命名为 SKILL.md（文件名、后缀固定不可修改，禁止使用 txt 等其他格式）。

新手最简标准目录结构如下：

1
2
go-test-gen/
└── SKILL.md  # 技能核心配置与逻辑文件

3.2 第二步：编写 YAML 头部配置（核心触发规则）

YAML 头部是 Skill 的核心「身份标识」，直接决定技能识别、触发、匹配规则。直接复制下方完整配置，粘贴至SKILL.md 文件顶部即可，无需手动调整格式。

本配置核心优势：关键词精准、触发范围清晰、自带排他规则，可大幅提升自动触发准确率，减少误匹配问题。

1
2
3
4
5
6
7
8
9
10
---
name: go-test-gen
description: >
  为Go语言函数自动生成标准表驱动风格单元测试。
  当用户提出编写单测、生成测试用例、补充函数测试代码、完善单元测试等需求时自动触发。
  仅适用于Go语言项目，不处理其他编程语言的测试生成需求。
metadata:
  version: "1.0"
  author: "新手实战"
---

新手核心知识点解读：

  • name：技能唯一标识，必须与文件夹名称完全一致，否则工具无法识别加载
  • description：核心触发规则，写入用户高频口语化指令，精准锁定使用场景，同时明确排他边界
  • YAML 语法强制规范：禁止使用 Tab 缩进，全程使用空格缩进，避免格式解析失败

3.3 第三步：撰写完整 Skill 正文（套用通用模板）

在 YAML 头部配置下方，粘贴以下完整正文内容。正文严格复用前文通用模板结构，全覆盖场景说明、分步流程、校验规则、实战示例四大核心模块，可直接落地使用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
# Go 单元测试自动生成技能
## 一、技能概述
本技能可快速为[Go语言](https://go.dev/)自定义函数生成行业标准的**表驱动风格单元测试**代码，统一团队测试代码格式，覆盖**常规、边界、异常全量测试场景**，解决新手手写单测不规范、场景缺失、重复编码的痛点，大幅提升Go项目测试开发效率。

## 二、前置条件
1. 当前项目为标准Go语言项目，可正常编译、运行，无环境报错
2. 待测试的Go函数代码完整、语法正确，可独立调用执行
3. 本地已配置完整Go开发环境，原生支持 [`testing` 标准库](https://pkg.go.dev/testing)

## 三、适用与不适用场景
✅ 适用场景：为Go自定义函数编写单元测试、补充缺失测试用例、优化完善现有单测代码
❌ 不适用场景：代码Bug修复、业务逻辑优化、文档编写、其他编程语言测试代码生成

## 四、分步执行步骤
### Step 1：解析目标函数
读取用户指定的Go文件与目标函数，精准梳理函数入参、出参、核心业务逻辑，明确本次测试的覆盖范围与核心校验点。
**检查点**：成功定位目标函数，无文件匹配、函数识别错误

### Step 2：规范生成测试代码
严格遵循Go官方单元测试规范生成代码，强制执行以下标准：
1. 仅使用原生 [`testing` 标准库](https://pkg.go.dev/testing)，不引入任何第三方测试框架
2. 测试函数命名统一规范为 `Test+原函数名`
3. 采用官方推荐 **`t.Run` 子测试 + 表驱动**标准化写法
4. 强制覆盖**正常输入、边界极值、异常输入**三类核心测试场景
**检查点**：生成代码格式规范、场景完整、无语法错误、符合Go编码标准

### Step 3：整理输出内容
自动格式化生成的测试代码，保留完整用例注释与场景说明，输出可直接复制运行、无需二次修改的完整代码。
**检查点**：输出代码可直接在项目中执行，无需手动调整格式与逻辑

## 五、代码示例（Before / After）
### 常规数值函数测试示例
**修改前（待测试原函数 Before）**
```go
func Add(a, b int) int {
    return a + b
}

修改后（生成的单元测试 After）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
func TestAdd(t *testing.T) {
	tests := []struct {
		name string
		a, b int
		want int
	}{
		{"正数正常相加", 1, 2, 3},
		{"零值相加", 0, 0, 0},
		{"负数相加", -1, -2, -3},
		{"正负混合相加", -1, 1, 0},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if got := Add(tt.a, tt.b); got != tt.want {
				t.Errorf("Add(%d, %d) = %d, 预期结果 %d", tt.a, tt.b, got, tt.want)
			}
		})
	}
}

六、最终全量验证

测试代码生成完成后，在项目终端执行以下命令，批量验证测试用例可用性：

1

验证标准：终端无报错、所有测试用例全部通过，即代表技能执行成功、效果达标。

四、核心功能精讲：Before/After 与检查点用法

doubao_image_12_1781855387112.png

Before/After 示例、分步检查点是新手编写高质量 Skill 的两大核心关键，可从根本上解决 AI 自由发挥、执行逻辑混乱、输出格式不统一等常见问题，是标准化 Skill 开发的必备能力。

4.1 Before/After 示例基础用法

核心设计逻辑：摒弃冗长的文字描述，通过「修改前原始代码 + 修改后规范代码」的直观对比，给 AI 明确的复刻标准，让 AI 严格按照示例格式与逻辑执行任务，是新手最好掌握、落地效果最优的写法。

新手强制使用规范：

  • 所有核心代码修改、生成类操作，必须配套一组完整的 Before/After 对比示例
  • 示例优先选用通用常规场景，逻辑简单、辨识度高，降低 AI 理解成本
  • 所有代码块必须精准标注对应编程语言，保证工具格式识别准确

4.2 检查点基础用法

核心设计逻辑：分步校验、错即停止、逐段闭环，每完成一步操作就校验执行结果，避免全流程执行完毕后才发现问题，大幅降低新手排错难度。

新手强制使用规范：

  • 技能内每一个 Step 执行步骤，必须配置对应的专属检查点
  • 优先使用可直接执行的终端命令作为校验依据，结果客观无歧义
  • 无终端命令可校验的场景，需用清晰文字明确「成功/失败」的判断标准

五、双模式测试：自动触发 + 手动触发实操

doubao_image_13_1781855395950.png

Skill 开发完成后，必须通过测试验证可用性。本章讲解两种官方标准触发测试方式，覆盖日常使用、问题排查全场景。测试前需保存全部文件，并重启 AI 编程助手，确保新技能配置正常加载生效。

5.1 自动触发测试（日常主力用法）

触发原理：AI 自动读取 Skill YAML 头部的 description 描述，通过语义匹配用户指令，无需手动干预，自动调用对应技能执行任务，是日常使用的主流方式。

直接复制以下测试指令即可验证：

帮我为项目中的 Add 函数生成标准的单元测试

✅ 正常生效效果：AI 精准识别用户需求，**go-test-gen**自动触发 技能，严格按照预设规则、示例、流程生成标准化单测代码，无自由发挥内容。

5.2 手动触发测试（精准兜底用法）

触发原理：用户主动输入专属命令，强制调用指定 Skill，无视语义匹配规则，可有效解决多技能冲突、自动匹配失误、触发不灵敏等问题，是问题排查、精准执行的兜底方案。

通用手动触发固定格式：/skill 技能文件夹名

本次实操专属测试指令：

/skill go-test-gen 帮我补充函数单元测试用例

✅ 正常生效效果：工具直接强制启用当前技能，严格按照预设流程执行任务，不受其他技能、语义匹配影响。

六、新手基础排错：常见问题与快速解决方案

doubao_image_7_1781855414372.png

汇总新手首次开发 Skill 的高频报错问题，配套极简排查流程与落地解决方案，无需复杂调试，新手可快速自主修复。

问题1：完全不触发 Skill

高频原因 & 对应解决方案：

  • 文件路径错误：检查技能文件夹是否直接放置在 skills 根目录，无多余嵌套层级
  • 文件名称错误：确认核心文件严格命名为 SKILL.md，大小写、后缀完全合规
  • YAML 格式错误：检查头部--- 首尾完整，无 Tab 缩进、无特殊乱码、无多余空行
  • 描述过于笼统：补充用户高频口语触发关键词，细化使用场景与边界规则

问题2：触发成功，但输出格式不标准

  • 核心原因：技能示例场景单一、执行规则描述模糊、无强制格式约束
  • 解决方案：补充多场景 Before/After 示例，细化每一步执行规则，增加格式强制约束语句

问题3：验证命令执行报错

  • 核心原因：本地未配置完整 Go 环境、当前项目非标准 Go 项目、项目文件缺失
  • 解决方案：完善本地 Go 开发环境，在合法可编译的 Go 项目目录下执行验证命令

七、本章总结

doubao_image_12_1781855422780.png

本章完成了 Skill 从理论认知到落地实操的完整闭环，你已熟练掌握新手核心实操技能：能够灵活套用标准化正文模板、独立完成 Skill 全流程开发、熟练使用双模式测试技能、自主排查基础运行问题。本次开发的 Go 单元测试生成技能，可直接应用于日常开发，真正实现 AI 自动化编码提效。

后续章节将在此基础上，持续优化 Skill 编写质量、拓展复杂场景功能，带你从「会写基础技能」稳步进阶为「能开发企业级高质量技能」。