# Agent Skill 安装说明

Bifrost 提供 `SKILL.md` 技能文件，可以让 AI 编程助手（Claude Code、Codex、Trae、Cursor、GitHub Copilot 等）自动掌握 bifrost CLI 的完整操作能力；同时也兼容更多遵循通用 Agent Skills 目录约定的运行时。

## 快速安装（推荐）

使用 `bifrost install-skill` 命令一键安装到所有支持的 AI 编程工具：

```bash
bifrost install-skill -y
```

每次执行都会从 GitHub 主干（main 分支）下载最新的 SKILL.md，覆盖式安装到目标目录。

### 安装到指定工具

```bash
bifrost install-skill -t claude-code -y   # 仅 Claude Code
bifrost install-skill -t codex -y         # Codex + 通用 .agents/skills 目录
bifrost install-skill -t trae -y          # 仅 Trae
bifrost install-skill -t cursor -y        # 仅 Cursor
bifrost install-skill -t github-copilot -y # 仅 GitHub Copilot
bifrost install-skill -t universal -y     # 仅通用 Agent Skills 目录
```

### 安装到当前项目目录

```bash
bifrost install-skill --cwd -y            # 安装到当前目录（所有工具）
bifrost install-skill --cwd -t trae -y    # 安装到当前目录（仅 Trae）
```

### 安装到自定义目录

```bash
bifrost install-skill -d /custom/path -y
```

### 支持的工具与默认路径

所有工具统一使用 `skills/bifrost/SKILL.md` 目录结构：

| 工具 | 别名 | 全局安装路径 | 项目级安装路径（--cwd） |
| --- | --- | --- | --- |
| Claude Code | `claude-code`, `claude` | `~/.claude/skills/bifrost/SKILL.md` | `./.claude/skills/bifrost/SKILL.md` |
| Codex | `codex`, `openai-codex` | `~/.codex/skills/bifrost/SKILL.md` + `~/.agents/skills/bifrost/SKILL.md` | `./.codex/skills/bifrost/SKILL.md` + `./.agents/skills/bifrost/SKILL.md` |
| Trae | `trae` | `~/.trae/skills/bifrost/SKILL.md` + `~/.trae-cn/skills/bifrost/SKILL.md` | `./.trae/skills/bifrost/SKILL.md` |
| Cursor | `cursor` | `~/.cursor/skills/bifrost/SKILL.md` | `./.cursor/skills/bifrost/SKILL.md` |
| GitHub Copilot | `github-copilot`, `copilot` | `~/.copilot/skills/bifrost/SKILL.md` | `./.github/skills/bifrost/SKILL.md` |
| Universal Agent Skills | `universal` | `~/.agents/skills/bifrost/SKILL.md` | `./.agents/skills/bifrost/SKILL.md` |

> **注意**：
> - Trae 在全局模式下会同时安装到 `.trae` 和 `.trae-cn` 两个目录（适配国内外版本），项目级安装（`--cwd`）仅安装到 `.trae`
> - `codex` 目标会保留历史 `.codex/skills` 路径，同时补充标准 `.agents/skills` 目录，方便兼容更多 agent
> - `universal` 目标仅安装到 `.agents/skills`，适合遵循通用 Agent Skills 规范的运行时

安装的文件始终是从远端下载的原始 SKILL.md 内容（含标准 YAML frontmatter），不做任何额外包装或修改。SKILL.md 源文件自带 `name` 和 `description` frontmatter 字段，兼容所有工具的 skill 自动发现机制。

### 参数说明

| 参数 | 说明 |
| --- | --- |
| `-t, --tool <TOOL>` | 目标工具：`claude-code`、`codex`、`trae`、`cursor`、`github-copilot`、`universal`、`all`（默认 `all`） |
| `-d, --dir <PATH>` | 自定义安装目录（覆盖默认路径，与 `--cwd` 互斥） |
| `--cwd` | 安装到当前目录（项目级别，与 `--dir` 互斥） |
| `-y, --yes` | 跳过确认提示 |

### 错误处理

安装过程中可能遇到的错误及处理建议：

| 错误类型 | 常见原因 | 处理建议 |
| --- | --- | --- |
| 网络错误 | DNS 解析失败、连接超时、GitHub 不可达 | 检查网络连接和 DNS 设置，确认可以访问 github.com |
| HTTP 错误 | 404（文件不存在）、403（被限流）、5xx（服务端故障） | 稍后重试，或检查 GitHub 状态 |
| 权限错误 | 目标目录无写入权限 | 使用 `sudo` 或通过 `--dir` 指定其他目录 |
| 写入失败 | 磁盘空间不足、路径过长 | 清理磁盘空间或使用 `--dir` 指定较短路径 |

## 手动安装

如果不想使用 `install-skill` 命令，也可以手动复制：

```bash
# Claude Code
mkdir -p ~/.claude/skills/bifrost && cp ./SKILL.md ~/.claude/skills/bifrost/SKILL.md

# Codex
mkdir -p ~/.codex/skills/bifrost && cp ./SKILL.md ~/.codex/skills/bifrost/SKILL.md
mkdir -p ~/.agents/skills/bifrost && cp ./SKILL.md ~/.agents/skills/bifrost/SKILL.md

# Trae (国际版 + 国内版)
mkdir -p ~/.trae/skills/bifrost && cp ./SKILL.md ~/.trae/skills/bifrost/SKILL.md
mkdir -p ~/.trae-cn/skills/bifrost && cp ./SKILL.md ~/.trae-cn/skills/bifrost/SKILL.md

# Cursor
mkdir -p ~/.cursor/skills/bifrost && cp ./SKILL.md ~/.cursor/skills/bifrost/SKILL.md

# GitHub Copilot
mkdir -p ~/.copilot/skills/bifrost && cp ./SKILL.md ~/.copilot/skills/bifrost/SKILL.md
```

## 安装后验证

安装完成后，在对应工具中启动新对话，输入与 bifrost 相关的指令（如"启动代理"、"查看流量"），如果 AI 能正确识别并调用 `bifrost` CLI，说明安装成功。

## 更新技能文件

技能文件会随 bifrost 版本迭代更新。建议定期执行：

```bash
bifrost install-skill -y
```

每次执行都会从远端主干拉取最新版本并覆盖安装，确保 AI 编程工具始终掌握最新的 CLI 能力。