--- title: Agent Skills description: Install the Mergify Agent Skills in Claude Code, Codex, or any skills.sh agent, so your coding agent can drive the Mergify CLI for you. --- Mergify ships Agent Skills that teach an AI coding agent how to use the Mergify CLI: how to read the merge queue, how to find out why a pull request was dequeued, what belongs in a `.mergify.yml`, how to push a stack. They live in the [`Mergifyio/mergify-cli`](https://github.com/Mergifyio/mergify-cli) repository under `skills/`, are Apache-2.0, and ship as one bundle. :::caution The skills drive the `mergify` command. They are instructions for using the CLI, not a standalone API client, so an agent that cannot run a shell cannot use them. Install and authenticate the CLI first (see the [CLI installation guide](/cli/usage)), or every skill fails on its first command. ::: ## What the bundle contains - **`mergify-merge-queue`** queues and dequeues pull requests, reads queue status, works out why a pull request left the queue and which check failed, and pauses or resumes merging. See [Merge Queue](/merge-queue). - **`mergify-events`** reads the [Activity Log](/api/activity-log) for one pull request or for a whole repository, and reconstructs a pull request's queue lifecycle. - **`mergify-config`** validates a `.mergify.yml` against the schema, and simulates what your rules would do on a real pull request. See [Configuration File](/configuration/file-format). - **`mergify-merge-protections`** sets up pull request dependencies, delayed merges, and [scheduled freezes](/merge-protections/freeze). - **`mergify-ci`** uploads JUnit test results, detects git refs, and sets [Merge Queue Scopes](/merge-queue/scopes). See [CI Insights](/ci-insights). - **`mergify-stack`** turns a branch of commits into [a stack of pull requests](/stacks) and keeps them rebased. ## Before you install Every skill shells out to `mergify`, so two things have to be true before any of them is useful: 1. The CLI is installed and on the agent's `PATH`. On macOS, `brew install mergifyio/tap/mergify-cli`. For Linux, Windows, and CI runners, see the [CLI installation guide](/cli/usage). 2. It is authenticated. See [Authentication](#authentication) below. These skills only work in a terminal agent that can run the binary, such as Claude Code, Codex, or Cursor. A browser-only chat cannot run it, so the skills do nothing there. ## Install ### Claude Code ```text /plugin install mergify@claude-plugins-official ``` The `claude-plugins-official` marketplace ships with Claude Code, so there is nothing to add first. You can also run `/plugin` on its own, open **Discover**, and search for `mergify`. ### Codex and other skills.sh agents [skills.sh](https://skills.sh) installs the same bundle into Codex, Cursor, Cline, Copilot, and dozens of other agents: ```bash npx skills add Mergifyio/mergify-cli ``` It detects the agent it is running under and writes the skills where that agent looks for them. To pick the target yourself, or to install once for every project instead of only the current one: ```bash npx skills add Mergifyio/mergify-cli --agent codex --global ``` Check the result with `npx skills list`. ## Authentication Most of what the skills do goes through the Mergify API. Sign in once and every skill inherits the credential: ```bash mergify auth login ``` That stores a [Mergify user token](/api/usage#using-a-mergify-user-token) outside the agent's reach, so no secret has to go on a command line or into the project. Where the operating system has no credential store, which is the usual case in a container, the CLI writes a restricted file in your configuration directory instead. See [Authentication](/cli/usage#authentication) for both paths. Stacks is the exception. It creates and updates pull requests through the GitHub API, so it needs a GitHub token of its own. Install the [GitHub CLI](https://cli.github.com/), run `gh auth login`, and Stacks commands pick up its token on their own. :::caution Letting the CLI authenticate to the Mergify API with a GitHub token is deprecated. `GITHUB_TOKEN` and the `gh auth token` fallback still work, and the CLI warns when it uses one, but run `mergify auth login` instead. Stacks is unaffected: it needs a GitHub token either way. ::: **A Mergify application key** is the alternative when the agent runs unattended and cannot complete an interactive sign-in. Create one from your [dashboard](https://dashboard.mergify.com) and export it, so the agent does not have to put a secret on a command line: ```bash export MERGIFY_TOKEN=your_token_here ``` An `admin` key covers queue status, the Activity Log, and freezes; CI Insights uploads and Merge Queue Scopes need a `ci` key instead. No single key covers both, so pick the one that matches what you want the agent to do. An application key does not work for Stacks. An unattended agent that pushes stacks needs a GitHub token in `GITHUB_TOKEN`, which is not deprecated: the deprecation above is only about using a GitHub token to reach the Mergify API. Application keys come with either the `admin` scope or the `ci` scope, and neither is read-only. `admin` covers the API except result uploads and Merge Queue Scopes, which need a `ci` key, so one key does not cover every command either. A key also belongs to a GitHub account rather than to a single repository, so it reaches every repository that account can see. Read [Application Key Scopes](/api/usage#application-key-scopes) before you hand one to an agent. ## Try it With the CLI installed and the skills in place, ask for what you want in plain language: - "Why did pull request #1234 leave the merge queue?" - "Validate this .mergify.yml, then show me what it would do on #1234." - "Freeze the queue until Monday morning." - "Turn these four commits into a stack and push it." The agent picks the skill that matches and runs the CLI itself. :::tip Want to hand your agent a single URL instead? Point it at [docs.mergify.com/stacks/agents](/stacks/agents), a page written for the agent to read, which walks it through installing the CLI and setting up Stacks on its own. :::