# 技能

Skills 是可复用 Markdown 文档，用于给 Agent 增加特定领域的指令或工作流。元数据存放在 `skills.yaml`，内容存放在 `~/.agentteam/skills/` 下。

## 元数据

Skill Markdown 可以包含 YAML front matter：

```markdown
---
id: code-review
name: Code Review
description: Review code changes for correctness and maintainability
version: "1.0"
author: team
tags: [review, quality]
---

# Code Review

Instructions for the agent...
```

必填元数据是 `id` 和 `name`。如果缺失，dashboard 和 CLI 会从 Markdown 标题、源文件名或 skill 目录自动推导。没有 front matter description 时，会从正文第一段推导简短描述。

## 支持的导入来源

| 来源 | 支持 |
|------|------|
| Markdown | `.md`、`.markdown` |
| 压缩包 | `.zip`、`.tar`、`.tar.gz`、`.tgz` |
| URL | `http://` 或 `https://` Markdown/压缩包 URL |
| 仓库 URL | 可解析为压缩包的 GitHub 或 GitLab URL |

压缩包会扫描一个或多个 `SKILL.md`。发现一个 skill 时按单个 skill 导入；发现多个 skill 时按批量导入处理。受管理仓库导入要求每个 `SKILL.md` 开头包含带 `name` 和 `description` 的 YAML front matter。`name` 是展示名称，可以包含大写字母、空格和非 ASCII 文本，但不能包含 `/`、`\`、`..` 或控制字符；AgentTeam 会在导入时内部推导路径安全的目录名。

## Dashboard 工作流

技能页可以：

- 按名称、标签或创建时间排序
- 从 URL 导入
- 一次导入一个或多个本地 Markdown 文件，或导入本地压缩包
- 导入时自动推导缺失的 `id`、`name` 和描述
- 编辑名称、描述和 tags
- 删除 skill 及其内容文件

dashboard 导入接口接收 multipart form data，其中可以提供一个或多个 `file` 字段，或提供一个 `url`，并可附带可选 metadata 字段和用于覆盖的 `force=true`。metadata 字段只在单个来源需要覆盖自动推导值时使用。

## CLI

```bash
agentteam skill list
agentteam skill list -f json
agentteam skill get <id>
agentteam skill import ./code-review.md
agentteam skill import ./skills.zip
agentteam skill import https://github.com/openai/superpowers
agentteam skill import ./custom.md --id custom --name "Custom Skill"
agentteam skill import ./custom.md --force
agentteam skill delete <id>
agentteam skill rm <id>
```

导入参数：

| 参数 | 含义 |
|------|------|
| `--id` | front matter 未提供时的 skill ID |
| `--name` | front matter 未提供时的显示名称 |
| `--description` | 描述覆盖 |
| `--version` | 版本 |
| `--author` | 作者 |
| `--tags` | 逗号分隔标签 |
| `--force` / `-f` | 不确认直接覆盖已有 skill |

`skill list` 和 `skill get` 支持 `--format/-f table|json|jsonc|yaml|toml`。

## 存储

删除 skill 会移除其元数据和已存储的 Markdown 内容。导入的压缩包会解包到受管理的 skill 内容路径；原始上传文件或临时下载文件不会保留。