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. One more skill sets up Test Engine in a repository. They live in the Mergifyio/mergify-cli repository under skills/ and ship as one bundle. Like the CLI, they are proprietary and free to use with Mergify under the license shipped with them. Install the bundle in Claude Code, in Codex, or in any agent skills.sh supports.

• 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-test-engine-setup wires a repository up to Test Engine: it reads the repository to find the test frameworks, the CI provider and the jobs that run tests, installs the matching Mergify plugin or a JUnit upload step, passes MERGIFY_TOKEN from the CI secret store, and opens the pull request. It then checks the pull request’s CI runs to see that every job it changed sends its results.

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

• mergify-cli-upgrade compares the installed CLI against the latest release and upgrades it through whichever channel installed it. The other skills follow the latest release, so this is what the agent reaches for when mergify rejects a command or flag one of them names. See the CLI installation guide.

Every skill but mergify-test-engine-setup shells out to mergify, so two things have to be true before they are 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. It is authenticated. See Authentication below.

Those 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 they do nothing there.

The bundle is the same whichever way you install it. Pick the path for your agent:

Inside Claude Code, enter:

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

Inside Codex, enter:

/plugins

That opens the plugin directory. Search it for Mergify, install the Mergify listing, then start a new Codex session so the skills load.

Codex and ChatGPT share one plugin directory, and the listing needs somewhere to run the binary: Codex, or ChatGPT desktop with local execution. The skills shell out to mergify, so a browser-only ChatGPT session cannot use them.

Codex is also a skills.sh agent, so the command in the next section works for it too, if you would rather install every agent the same way.

In your terminal, from the project you want the skills in, run:

npx skills add Mergifyio/mergify-cli

skills.sh installs the same bundle into Cursor, Cline, Copilot, Codex, and dozens of other agents. 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 cursor --global

Check the result with npx skills list.

To set up Test Engine once, without installing anything, have the agent load the skill for the current task:

npx skills use Mergifyio/mergify-cli --skill mergify-test-engine-setup

It prints the skill’s instructions and downloads its reference files to a temporary directory, outside the repository, so nothing ends up in the setup pull request. It always loads the current version of the skill, even when your agent’s plugin marketplace still installs an older copy of the bundle.

Most of what the skills do goes through the Mergify API. Sign in once and every skill inherits the credential:

mergify auth login

That stores 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 for both paths.

mergify auth login opens the approval page in your browser. On a machine without one, pass --no-browser and open the URL it prints on another machine.

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, run gh auth login, and Stacks commands pick up its token on their own.

A Mergify application key is the alternative when the agent runs unattended and cannot complete an interactive sign-in. Create one from your dashboard and export it, so the agent does not have to put a secret on a command line:

export MERGIFY_TOKEN=your_token_here

An admin key covers queue status, the Activity Log, freezes, and browsing or quarantining tests; CI and test result uploads, Merge Queue Scopes, and the mid-run flaky-detection and test-selection reads 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, which the note above does not touch: only the Mergify API stopped taking a GitHub token as a credential. Exporting GITHUB_TOKEN is not enough on its own, though. Stacks commands read --token, then MERGIFY_TOKEN, then GITHUB_TOKEN, so an agent that already has an application key in MERGIFY_TOKEN hands that key to GitHub and the push fails. Pass the GitHub token as --token on the Stacks commands, or keep the application key out of MERGIFY_TOKEN. See GitHub token for Stacks for the full resolution order.

Application keys come with either the admin scope or the ci scope, and neither is read-only. admin covers the API except CI and test result uploads, Merge Queue Scopes, and the mid-run flaky-detection and test-selection reads, all of 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.”
• “Set up Mergify Test Engine in this repository.”

The agent picks the skill that matches and runs the CLI itself.