Agents Skills for resolving GitLab pipeline failures

Each CI/CD platform MCP server comes with dozens of tools. For example, at the time of writing this article MCP servers for GitHub has 44, Azure DevOps has 89, GitLab has 15 tools. Each tool definition you have in your set up increases context usage. Agent skills help reduce these by providing a way to progressively load context for a given skill when needed.

Customers can build an agent skill to teach an agent the steps you typically perform when analyzing and resolving pipeline failures. Instead of the agent performing reasoning repetitively to figure out how to check build status, retrieve logs, identify failures etc. skills can provide the CLI commands to use for each of these steps. This way the agent can consistently use the same method to perform investigations.

How to create the skill

Agent skills specification follows a directory structure which contains a SKILL.md file with YAML front-matter for the skill to help AI agents decide when to activate this skill, followed by the markdown content. In this case the SKILL.md is the only file for this skill.

Create the file .skills/aws-iam-permission-boundary/SKILL.md with the following content for a starter skill to work with GitLab CI/CD using GitLab CLI.

---
name: glab-ci
description: Monitor and troubleshoot GitLab CI/CD pipelines using the glab CLI. Check pipeline status, view job logs, retry failed jobs, and diagnose build failures.
---

## Overview

Use the `glab ci` CLI to inspect pipelines, trace job logs, and retry failed jobs. All commands below are non-interactive and safe to run programmatically.

## Important

Avoid `glab ci status` — it prompts for interactive input (view logs menu). Use `glab ci list` instead for pipeline status.

## Prerequisites — always run first

Before any `glab` command, verify authentication is working:

```sh
glab auth status 2>&1
```

If the output contains `403`, or `error`, authentication has expired. Tell the user to authenticate and wait for them to confirm before proceeding.

## Steps
### 1. Check pipeline status (non-interactive)

Use `glab ci list` to see recent pipeline statuses without interactive prompts:

```sh
# Latest pipeline for main branch
glab ci list --per-page 1 --ref main
# Recent failed pipelines
glab ci list --status=failed
# All recent pipelines
glab ci list --per-page 10
```

### 2. View job logs

Use `glab ci trace` with the job name to see the full log output. This is the primary way to diagnose failures.

```sh
# Trace by job name (non-interactive when name is provided)
glab ci trace <job-name>
# Trace a job from a specific branch
glab ci trace <job-name> --branch main
# Trace a job from a specific pipeline
glab ci trace <job-name> --pipeline-id <pipeline-id>
```

Pipe through `tail` to focus on the error:

```sh
glab ci trace <job-name> 2>&1 | tail -40
```

### 3. Retry a failed job

```sh
# Retry by job name
glab ci retry <job-name>
# Retry by job name on a specific branch
glab ci retry <job-name> --branch main
```

### 4. Cancel a running pipeline

```sh
glab ci cancel
```

### 5. Run a new pipeline

```sh
glab ci run --branch main
```

## Troubleshooting workflow
When a pipeline fails:
1. Run `glab ci list --per-page 1 --ref main` to see the latest pipeline status
2. Run `glab ci trace <failed-job-name>` to read the logs
3. Pipe through `tail -50` if the output is long
4. Fix the issue locally
5. Push the fix, or retry the job with `glab ci retry <job-name>` if it was transient

For best results, iterate with your AI agent to refine this skill to add specific information about your organization/project, and cover more of your workflows. This way your agent improves as you keep working with it and updating skills coverage.