---
name: skill-guide
description: 技能安装与开发指南。当用户询问"如何添加技能"、"自定义技能"、"安装技能"时立即调用。
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# 技能（Skill）安装与开发指南

## 概述

技能（Skill）是 Agent 的扩展能力模块，存放在 `.agent/skills/` 目录下。

## 技能存放位置

### 方式一：.agent/skills/ 目录

```
项目目录/
└── .agent/
    └── skills/
        └── my-skill/          # 技能文件夹
            ├── SKILL.md        # 必需，技能定义文件
            └── ...             # 其他资源文件（可选）
```

### 方式二：插件目录下

插件目录下的 `SKILL.md` 也会被自动加载为技能：

```
项目目录/
└── .agent/
    └── plugins/
        └── my-plugin/         # 插件文件夹
            ├── index.js        # 插件入口文件
            ├── SKILL.md        # 可选，技能定义文件（自动加载）
            └── ...
```

**规则：**

- 插件目录下的 `SKILL.md` 会被自动发现并加载为技能
- 技能名称与插件名称相同
- 插件启用/重载时会自动更新关联的技能

## SKILL.md 格式

每个技能必须包含 `SKILL.md` 文件，使用 YAML frontmatter 定义元数据：

```yaml
---
name: my-skill # 技能名称（必需，唯一标识）
description: 这是一个自定义技能的描述。当用户说"..."时调用此技能。（必需）
allowed-tools: Read, Write, Edit, Glob, Grep, Bash # 可选，允许使用的工具列表
license: MIT # 可选，许可证
compatibility: v1.0.0 # 可选，兼容版本
---
# 技能标题

这里是技能的详细说明内容，可以使用 Markdown 格式。
```

### frontmatter 字段说明

| 字段            | 必需 | 说明                                             |
| --------------- | ---- | ------------------------------------------------ |
| `name`          | 是   | 技能唯一标识，字母、数字、下划线、横杠，1-64字符 |
| `description`   | 是   | 技能描述，当用户意图匹配时会被调用               |
| `allowed-tools` | 否   | 允许使用的工具列表，逗号分隔                     |
| `license`       | 否   | 许可证类型                                       |
| `compatibility` | 否   | 兼容的框架版本                                   |

### 正文格式

frontmatter 之后是技能的正文内容，支持 Markdown 格式，包含：

- 详细的功能说明
- 使用示例
- 最佳实践
- 注意事项

## 创建自定义技能

1. 在 `.agent/skills/` 下创建技能文件夹
2. 创建 `SKILL.md` 文件，包含完整的 frontmatter
3. 在正文中详细描述技能的功能和使用方法
4. 调用 `reloadSkills` 工具重载所有技能

## 技能重载

创建或修改技能后，需要调用 `reloadSkills` 工具重载：

```json
{
  "tool": "reloadSkills",
  "args": {}
}
```

## 示例：创建天气查询技能

```
.agent/skills/weather/
└── SKILL.md
```

SKILL.md 内容：

```yaml
---
name: weather
description: 查询天气信息。当用户说"天气怎么样"、"今天多少度"时调用。
allowed-tools: Bash, Read
---

# 天气查询技能

## 功能

查询指定城市的天气信息。

## 使用方式

用户发送 "北京天气" 或 "今天上海多少度"

## 注意事项

- 使用免费的天气 API
- 响应需要简洁明了
```
