Agent Skills

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 repository under skills/, are Apache-2.0, and ship as one bundle.

• 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.

• mergify-events reads the 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.

• mergify-merge-protections sets up pull request dependencies, delayed merges, and scheduled freezes.

• mergify-ci uploads JUnit test results, detects git refs, and sets Merge Queue Scopes. See CI Insights.

• mergify-stack turns a branch of commits into a stack of pull requests and keeps them rebased.

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.

2. A token is available to it. See 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.

/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.

skills.sh installs the same bundle into Codex, Cursor, Cline, Copilot, and dozens of other agents:

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:

npx skills add Mergifyio/mergify-cli --agent codex --global

Check the result with npx skills list.

The CLI resolves a token in this order: the --token option on the command, then MERGIFY_TOKEN, then GITHUB_TOKEN. Stacks commands fall back once more to gh auth token. Set an environment variable rather than passing --token, so the agent does not have to put a secret on a command line:

export MERGIFY_TOKEN=your_token_here

Which token to use depends on what you want the agent to do.

A GitHub token covers everything except CI result uploads. Stacks needs one specifically, because it creates and updates pull requests through the GitHub API, and the Mergify API accepts a GitHub personal access token too. If you already have the GitHub CLI installed and authenticated, Stacks commands pick up its token on their own and you can skip this.

A Mergify application key covers the commands that call the Mergify API: queue status, Activity Log, freezes, and CI Insights uploads. Create one from your dashboard. It will not work for Stacks.

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 before you hand one to an agent.

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.