手环的小星球
手环的小星球
如何编写一个 GitLab Skill 让 AI Agent 帮你创建 MR

如何编写一个 GitLab Skill 让 AI Agent 帮你创建 MR

更新时间
Last updated January 31, 2026
AI 占比
Tags
效率
description
作为一名前端开发者，每天都要和 GitLab 打交道：创建分支、提交代码、创建 MR、处理 fork 仓库的跨仓库 MR... 这些操作虽然不复杂，但重复且繁琐。于是我想：能不能让 AI Agent 帮我完成这些工作？
答案是可以的。通过编写一个 GitLab Skill，我成功让 Claude Code 成为了我的 GitLab 助手。

什么是 Skill？

在 Claude Code 中，Skill 是一种让 AI Agent 获得特定领域知识和能力的机制。你可以把它理解为给 AI 的"说明书"——当用户提到相关关键词时，Agent 会自动加载这份说明书，然后按照说明书上的步骤来执行任务。

为什么需要 GitLab Skill？

虽然 Claude Code 已经支持 GitHub 的各种操作（通过 gh 命令），但对于使用私有 GitLab 实例的团队来说，有几个痛点：
  1. 命令记不住：glab mr create 的参数太多，每次都要查文档
  1. 跨仓库 MR 很复杂：从 fork 仓库创建 MR 到 upstream 的命令更加复杂
  1. 容易出错：忘记推送分支、忘记检查认证状态等问题经常发生
  1. 重复工作：每次都要手动写 MR 描述，格式不统一

Skill 的目录结构

我的 GitLab Skill 采用了模块化的结构：
.agents/skills/gitlab/
├── SKILL.md                    # 主入口文件
└── references/
    ├── create-mr-guide.md      # 创建 MR 的详细指南
    ├── fork-to-upstream.md     # 跨仓库 MR 指南
    ├── git-push-guide.md       # Git 推送注意事项
    └── troubleshooting.md      # 故障排除指南

为什么要分成多个文件？

  1. 按需加载：Agent 可以根据具体任务只读取需要的文档，节省 token
  1. 易于维护：每个场景独立维护，更新时不会互相影响
  1. 可扩展性：新增场景只需要添加新文件，不需要修改主文件

SKILL.md 的编写要点

1. 元数据定义

---
name: gitlab
description: 使用 glab CLI 与 GitLab 仓库、合并请求和 API 交互
triggers:
  - gitlab
  - git
  - mr
  - merge request
---
  • name：Skill 的唯一标识
  • description：简短描述，帮助 Agent 理解何时使用这个 Skill
  • triggers：触发词列表，当用户消息中包含这些词时会激活 Skill

2. 引导 Agent 读取参考文档

## 重要：先读取参考文档

**在执行任何 GitLab 操作之前，必须先读取相关的参考文档！**

根据操作类型，读取对应文档：
- 创建 MR → 读取 `references/create-mr-guide.md`
- Fork 到 Upstream 的 MR → 读取 `references/fork-to-upstream.md`
- 遇到问题 → 读取 `references/troubleshooting.md`
这一点非常重要！通过明确的指引，Agent 可以在执行前获取必要的上下文信息。

3. 前置检查清单

## 前置检查

### 1. 检查 glab 是否安装
glab 会自动使用 `GITLAB_TOKEN` 环境变量

### 2. 检查认证状态
glab auth status --hostname gitlab.xsky.com
把容易忘记的检查步骤写成清单，确保 Agent 每次都会执行。

4. 常用命令速查

## 常用命令

# 查看当前分支的 MR
glab mr list --source-branch=$(git branch --show-current)

# 创建 MR（fork -> upstream）
glab mr create --title "feat: 功能描述" --target-branch master --repo front-end/afsui
提供常用命令模板，Agent 可以直接使用或稍作修改。

参考文档的编写技巧

分步骤指南

以 create-mr-guide.md 为例，采用清晰的步骤化结构：
## 步骤 1：前置检查
检查 glab 和认证状态

## 步骤 2：收集信息
分析变更以创建好的 MR 标题和描述

## 步骤 3：确保分支已推送到远程
检查并推送分支

## 步骤 4：检查是否已有 MR
避免重复创建

## 步骤 5：创建 MR
执行创建命令

## 步骤 6：返回 MR URL
将结果反馈给用户

提供可执行的代码示例

每个步骤都附带可直接执行的命令：
# 并行运行这些命令以收集上下文信息
git status
git diff master...HEAD --stat
git log master..HEAD --oneline

处理边界情况

在 fork-to-upstream.md 中专门处理了跨仓库 MR 这个复杂场景：
## 参数说明

| 参数 | 说明 |
|------|------|
| `--repo` | 目标仓库路径（upstream 的 namespace/project） |
| `--target-branch` | 目标分支，通常是 master 或 main |
| `--source-branch` | 源分支（默认为当前分支） |

故障排除指南

troubleshooting.md 收集了常见问题和解决方案：
## 问题 1：glab 未安装
brew install glab

## 问题 2：认证失败
检查 GITLAB_TOKEN 环境变量

## 问题 3：MR 已存在
检查并更新现有 MR

实际使用效果

编写好 Skill 后，我只需要对 Claude Code 说：
"帮我创建一个 MR，把当前的改动提交到主仓库"
Agent 会自动：
  1. 读取 GitLab Skill 和相关参考文档
  1. 检查 glab 安装和认证状态
  1. 分析当前的代码变更
  1. 生成合适的 MR 标题和描述
  1. 检查是否已有 MR
  1. 创建 MR 并返回链接
整个过程完全自动化，我只需要确认最后的结果。

编写 Skill 的最佳实践

基于这次经验，总结几点编写 Skill 的最佳实践：

1. 结构化组织

  • 主入口文件保持简洁，只包含概述和导航
  • 详细内容放在 references/ 目录下
  • 按场景拆分文档，方便按需加载

2. 明确的指令

 
  • 用"必须"、"绝不要"等明确措辞
  • 提供清晰的步骤顺序

3. 可执行的示例

  • 每个命令都应该可以直接复制执行
  • 使用变量替换 $(git branch --show-current) 而不是占位符
  • 注释说明命令的作用

4. 错误处理

  • 预想可能出错的场景
  • 提供故障排除指南
  • 告诉 Agent 如何判断成功或失败

5. 安全考虑

  • 明确禁止危险操作（如直接推送到 master）
  • 提醒检查认证状态
  • 避免在日志中暴露 token

总结

通过编写 GitLab Skill，我把日常繁琐的 GitLab 操作完全交给了 AI Agent。这个过程让我体会到：
  1. Skill 是知识的载体：把团队的最佳实践固化成 Skill，新人也能快速上手
  1. 模块化设计很重要：合理拆分文档，既节省 token 又便于维护
  1. 细节决定体验：前置检查、错误处理、明确指令，这些细节让 Agent 更可靠
如果你的团队也在使用 GitLab，不妨试试编写自己的 GitLab Skill。相信我，一旦用上了，你就再也不想手动创建 MR 了。
本文由 Claude Code 协助完成