跳到主要内容

创建自定义 Skill

你可以为任意重复性工作流创建专属 skill，让 AI 始终遵循你的流程、标准与输出格式。

Skill 文件格式​

一个 skill 由 SKILL.md 文件定义。文件使用 YAML front matter 描述元数据，随后是给 AI 的完整执行指令：

---
name: my-skill           # Skill 名称（缺省时取目录名）
description: 一句话描述 skill 的作用以及何时应当使用
version: "1.0"           # 可选
author: Your Name        # 可选
tags: [tag1, tag2]       # 可选，便于分类
---

# Skill 标题

## 任务目标

明确 skill 的目标与边界。

## 步骤

1. 步骤一：...
2. 步骤二：...
3. 步骤三：...

## 输出格式

定义期望的输出结构...

description 字段是关键的触发信号。AI 决定是否激活某个 skill 时，主要依赖该描述。清晰说明 skill 做什么、何时使用，AI 才能更准确地匹配用户意图。

创建你的第一个 Skill​

第 1 步：创建 skill 目录​

mkdir -p ~/.aiagent/skills/my-skill

第 2 步：编写 SKILL.md​

创建 ~/.aiagent/skills/my-skill/SKILL.md：

---
name: api-tester
description: 测试 REST API 端点，自动发送请求并校验响应结构与状态码。当用户需要测试 API 端点时使用。
version: "1.0"
author: DevTeam
tags: [api, testing, rest]
---

# API 测试助手

## 任务目标

系统化地测试 REST API 端点，包括请求构造、响应校验与问题诊断。

## 步骤

### 1. 收集 API 信息

向用户确认：
- Base URL 与端点路径
- HTTP 方法（GET/POST/PUT/DELETE）
- 请求头（Authorization、Content-Type 等）
- 请求体（用于 POST/PUT）
- 期望的状态码与响应结构

### 2. 构造并执行请求

```bash
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "email": "[email protected]"}' \
  -w "\nHTTP Status: %{http_code}\n"

3. 校验响应​

检查：

  • HTTP 状态码是否符合预期
  • 响应体结构是否完整
  • 必填字段是否存在且类型正确
  • 错误响应是否清晰、可操作

4. 输出结果​

项目结果
状态码✅ 201 Created
响应耗时245ms
必填字段✅ 全部存在
数据格式✅ 符合规范

### 第 3 步：确认加载成功

重启 Agent（或等待自动重载），然后让 AI 触发该 skill：

```text
"帮我测试一下这个 API 端点"
"用 api-tester 检查一下登录 API"

使用辅助文件​

skill 目录可以包含任意数量的辅助文件。AI 通过工具按需读取它们，而不是一次性全部加载，因此你可以放心地包含大型参考资料：

~/.aiagent/skills/release-checklist/
  SKILL.md                  ← 主指令
  checklist.md              ← 详细发布清单
  rollback-steps.md         ← 回滚手册
  environments/
    staging.env.md          ← staging 环境配置参考
    production.env.md

在 SKILL.md 中告知 AI 何时读取这些文件：

## 参考资料

执行发布清单前，先调用 `list_skill_files` 查看可用文件，
再对 `checklist.md` 调用 `read_skill_file` 获取完整清单。
若需要回滚，请阅读 `rollback-steps.md`。

如何写出高质量的 Skill​

让 description 足够准确，便于触发​

# ❌ 太宽泛，AI 难以匹配
description: 帮助处理开发工作

# ✅ 明确说明做什么、何时使用
description: 通过分析代码并提取端点定义生成符合 OpenAPI 规范的 API 文档。当用户需要编写或更新 API 文档时使用。

用步骤化指令降低歧义​

相比松散的描述性段落，明确的过程化步骤让 AI 更可靠。把工作流拆成具体步骤，并说明做什么、怎么做、如何校验。

定义清晰的输出格式​

如果你需要特定的输出格式（表格、Markdown、JSON 等），就在 skill 中明确定义，让 AI 严格遵循：

## 输出格式

请使用以下 Markdown 表格汇报审查结果：

| 文件 | 问题类型 | 严重程度 | 建议 |
|------|----------|----------|------|
| ... | ... | 🔴 严重 / 🟡 警告 / 🔵 提示 | ... |

提前规划异常分支​

明确定义异常处理方式，比让 AI 在运行时即兴决定要可靠得多：

## 异常处理

- 找不到目标文件：报告文件不存在，列出当前目录内容并询问下一步操作
- API 返回 401：提示用户校验认证 token，不要自动重试
- 发现敏感信息（密钥、密码）：立即停止、警告用户，且不再继续处理

元数据字段参考​

字段必填说明
name否唯一 skill 标识；缺省时取目录名
description是核心触发信号；必须清晰说明用途与适用场景
version否用于变更跟踪的语义化版本号
author否创建者名称
tags否用于分类的标签

调试 Skill​

如果 skill 没有按预期触发或执行：

  1. 检查 description 是否足够明确
    你可以直接在对话中说"使用 skill-name skill"以强制激活。

  2. 确认文件路径
    确认文件存在于 ~/.aiagent/skills/<skill-name>/SKILL.md。

  3. 检查 YAML 格式
    YAML front matter 对缩进与语法敏感，请仔细校验格式。

  4. 查看后端日志
    macOS 桌面端日志位于：

    ~/Library/Application Support/com.example.agentui/flutter_logs.txt

下一步​