# @agent-git/skill

Agent-Git 的 Skill 安装包。

它把 Agent-Git 工作流说明安装到不同 Agent 客户端的项目级 skills 目录中。Skill 本身只包含 Agent 可读的规则和调用约定，不执行 Git 命令，也不包含 `@agent-git/core` 的业务逻辑。

安装后的 Skill 会指导 Agent 通过 `@agent-git/cli` 执行 `status`、`save`、`undo` 和 `squash` 工作流，不调用 MCP tools。

## 前置条件

- 已安装 Node.js 和 `npx`。
- 应在需要安装 Skill 的项目根目录执行命令。
- Agent 运行工作流时还需要 Git 和 `@agent-git/cli`；CLI 默认通过 `npx` 按需运行，无需全局安装。

## 快速安装

安装到 Codex：

```bash
npx -y @agent-git/skill@latest install --target codex
```

安装到 Claude：

```bash
npx -y @agent-git/skill@latest install --target claude
```

安装到 OpenCode：

```bash
npx -y @agent-git/skill@latest install --target opencode
```

安装到所有支持的目标：

```bash
npx -y @agent-git/skill@latest install --target all
```

## 命令与参数

```text
agent-git-skill install [--target opencode|claude|codex|all] [--force]
```

通过 npm 包执行时：

```bash
npx -y @agent-git/skill@latest install [options]
```

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `--target <target>` | enum | 否 | `opencode` | 可选 `opencode`、`claude`、`codex` 或 `all`。 |
| `--force` | 标志 | 否 | `false` | 覆盖目标位置已经存在的 `SKILL.md`。 |
| `--help`、`-h` | 标志 | 否 | — | 显示帮助，不安装文件。 |

省略 `--target` 等价于：

```bash
npx -y @agent-git/skill@latest install --target opencode
```

## 安装位置

安装路径相对于执行命令时的当前目录计算，因此应先进入目标项目根目录。

| target | 安装文件 |
| --- | --- |
| `opencode` | `.opencode/skills/agent-git/SKILL.md` |
| `claude` | `.claude/skills/agent-git/SKILL.md` |
| `codex` | `.codex/skills/agent-git/SKILL.md` |
| `all` | 依次安装以上三个文件。 |

例如：

```bash
cd /path/to/project
npx -y @agent-git/skill@latest install --target codex
```

会创建：

```text
/path/to/project/.codex/skills/agent-git/SKILL.md
```

Windows PowerShell 示例：

```powershell
Set-Location "D:\files\project"
npx -y @agent-git/skill@latest install --target codex
```

## 已有文件与 `--force`

默认安装不会覆盖已有文件。如果目标 `SKILL.md` 已经存在，命令会失败，以免覆盖用户定制内容。

确认可以替换后使用：

```bash
npx -y @agent-git/skill@latest install --target codex --force
```

`--force` 会直接用当前 npm 包内置的模板覆盖目标文件，不会合并已有修改。建议覆盖前先查看差异或备份定制内容。

使用 `--target all --force` 时，三个目标文件都会被覆盖：

```bash
npx -y @agent-git/skill@latest install --target all --force
```

## 检查安装结果

安装成功后，命令会输出目标和绝对路径，例如：

```text
Installed codex skill: /path/to/project/.codex/skills/agent-git/SKILL.md
```

可以打开对应文件，确认其 frontmatter 包含：

```yaml
---
name: agent-git
description: 在 Git 仓库中修改代码时使用：通过 Agent-Git CLI 执行 checkpoint、status、undo 和 squash 工作流。
---
```

随后重新加载或重启 Agent 客户端，使其重新发现项目级 Skill。具体刷新方式取决于客户端。

## 升级 Skill

升级时重新运行带 `--force` 的最新版本安装命令：

```bash
npx -y @agent-git/skill@latest install --target codex --force
```

该操作会替换整个 `SKILL.md`。如果曾经手动定制文件，应先保存修改并在升级后重新合并。

如果需要固定版本，可以将 `latest` 替换成明确版本：

```bash
npx -y @agent-git/skill@1.0.1 install --target codex
```

## 卸载 Skill

安装器当前没有 `uninstall` 命令。卸载时手动删除对应的 `agent-git` Skill 目录，例如：

```text
.codex/skills/agent-git/
```

删除前确认目录中没有需要保留的用户定制内容。卸载 Skill 不会修改 Git 历史，也不会删除 Agent-Git 创建的已有提交。

## 安装后的运行方式

Skill 会要求 Agent 使用以下 CLI：

```bash
npx -y @agent-git/cli@latest status --workspace PATH
npx -y @agent-git/cli@latest save --workspace PATH --message "准备继续修改代码"
npx -y @agent-git/cli@latest undo --workspace PATH --steps 1
npx -y @agent-git/cli@latest squash --workspace PATH --summary "feat: 完成某项能力" --preview
npx -y @agent-git/cli@latest squash --workspace PATH --summary "feat: 完成某项能力"
```

其中：

- `PATH` 应是目标 Git 仓库根目录的绝对路径。
- `save` 保存命令执行时已有的变更；工作区干净时会跳过。
- `undo` 是破坏性硬重置，必须先确认回退范围。
- 正式 `squash` 前必须先执行 `--preview`。
- `squash --preview` 不创建提交，但当前 CLI 实现可能改变暂存区状态。

完整命令参数和安全说明参见 [`@agent-git/cli` 文档](../cli/README.md)。

## Skill 与 MCP 的关系

- Skill 的运行时入口始终是 Agent-Git CLI。
- MCP Server 是支持 MCP tools 客户端的另一种独立入口。
- Skill 不会安装、启动或配置 MCP Server。
- 同一个工作流步骤不要同时通过 CLI 和 MCP 执行。

如果希望客户端直接调用结构化 MCP tools，而不是安装工作流说明，请使用 [`@agent-git/mcp`](../mcp/README.md)。

## 常见问题

### 为什么安装到了错误目录？

安装路径基于当前工作目录，而不是自动探测 Git 仓库根目录。进入正确的项目根目录后重新安装，并删除错误位置的文件。

### 为什么提示文件已经存在？

默认模式用于保护已有文件。确认允许覆盖后加 `--force`，或者先手动比较现有文件和新模板。

### 为什么安装 Skill 后没有 `agent-git` 全局命令？

Skill 包只安装 Markdown 工作流说明，不全局安装 CLI。Skill 中使用 `npx -y @agent-git/cli@latest` 按需运行 CLI。

### 为什么 Agent 没有使用 Skill？

确认文件位于对应客户端支持的项目级 skills 目录，并重新加载客户端。不同客户端的 Skill 发现和触发机制可能不同。

## 包边界

- 不执行 Git 命令。
- 不调用 MCP SDK 或 MCP tools。
- 不复制 `@agent-git/core` 的业务逻辑。
- 只维护 Agent 可读的工作流说明和安装路径。