---
title: "CircleCI agent skills"
description: "Install CircleCI agent skills in Claude Code, Cursor, Codex, or Copilot to debug builds, optimize config, and onboard projects."
doc_version: "unversioned"
last_updated: "2026-09-09"
---

> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# CircleCI agent skills

CircleCI agent skills give your AI coding agent reusable workflows for common CircleCI tasks. Install the CircleCI plugin once, then ask your agent to debug a failed build, optimize config, or onboard a project.

## Introduction

Skills are instruction files that your AI agent follows. They tell the agent which CircleCI commands to run, which files to inspect, and how to report results.

CircleCI publishes these skills as a plugin in the [CircleCI Public Skills](https://github.com/CircleCI-Public/skills) repository.

Skills are not the same as CircleCI MCP servers. MCP servers give your agent live tools for CircleCI. Skills give your agent a workflow to follow. You can use either, or both. See the [CircleCI MCP Overview](https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/) page.

The `chunk` skill in this plugin helps you set up Chunk. Chunk is CircleCI validation for agentic development. Sidecars run lightweight checks in a clean cloud environment while your agent is still working, so you catch failures before the push. See [Compare skills with other CircleCI AI tools](#compare-skills-with-other-ai-tools).

## Prerequisites

Before you install CircleCI agent skills, set up the following:

*   An AI coding agent, for example, Claude Code, Cursor, Codex, or GitHub Copilot.
    
*   A CircleCI account with access to the projects you want to work on. You can sign up for a free account at [CircleCI](https://circleci.com/signup).
    
*   It is a good idea to install the CircleCI CLI, and authenticate for your CircleCI account. See [The CircleCI CLI](https://circleci.com/docs/guides/toolkit/circleci-cli/). Installing the CLI is optional, but most skills make use of it.
    

## Available CircleCI agent skills

The CircleCI plugin currently includes the following seven skills. Your agent picks a skill from your request, or you can invoke a skill by name.

| Skill | What it does | Example prompt |
| --- | --- | --- |
| `circleci-builds` | Diagnoses failing CircleCI jobs, classifies the failure, and applies a minimal fix. | Diagnose and fix build failures for the current branch. |
| `circleci-cli` | Runs the day-to-day CLI loop: validate config, watch a run, read logs, and rerun jobs. | Watch the CircleCI run for my current branch and report the results. |
| `circleci-config` | Optimizes your CircleCI config YAML for speed, reliability, and maintainability. | Review the CircleCI configuration for this project and suggest improvements. |
| `onboarding` | Walks through first-time CircleCI setup for a new repository. | Onboard my project to CircleCI. |
| `chunk` | Sets up either/or/both Chunk for the CircleCI web app (cloud based CI/CD assistant) or the Chunk CLI (local CI/CD development tooling). For more information on Chunk, see the [Chunk Overview and Setup](https://circleci.com/docs/guides/toolkit/chunk-setup-and-overview/) page and the [Install and Configure the Chunk CLI](https://circleci.com/docs/guides/toolkit/install-and-configure-the-chunk-cli/) page. | Set up Chunk sidecars for this project. |
| `circleci-testsuite` | Get set up for Smarter Testing by using `.circleci/test-suites.yml` and switch tests to `circleci testsuite run`. The manual setup is described on the [Getting Started With Smarter Testing](https://circleci.com/docs/guides/test/getting-started-with-smarter-testing/) page. | Set up a testsuite for this project. |
| `circleci-smarter-testing` | Enables Smarter Testing features: test impact analysis, dynamic test splitting, and auto-rerun of failed tests. Smarter Testing is in beta. Using this skill, your agent asks you to confirm which of the Smarter Testing features you want to set up. | Set up CircleCI Smarter Testing for running tests in this project. |

## Install CircleCI agent skills

CircleCI distributes the skills as the `circleci` plugin in the `CircleCI-Public/skills` marketplace. Add the marketplace, then install the plugin.

<Tabs>
<Tab title="Claude Code">

1.  In Claude Code, add the CircleCI marketplace:
    
    ```shell
    /plugin marketplace add CircleCI-Public/skills
    ```
    
2.  Install the CircleCI plugin:
    
    ```shell
    /plugin install circleci@circleci-public-skills
    ```
    
3.  Reload plugins if Claude Code prompts you to, then start a new session.
    

For more information on plugin marketplaces, see the [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins).

</Tab>
<Tab title="Cursor">

To install CircleCI agent skills in Cursor, copy the skill folders into your Cursor skills directory:

```console
$ git clone https://github.com/CircleCI-Public/skills.git
$ mkdir -p ~/.cursor/skills
$ cp -R skills/plugins/circleci/skills/* ~/.cursor/skills/
```

To limit the skills to one project, copy the folders into `.cursor/skills/` in that repository instead.

1.  Restart Cursor, or run **Developer: Reload Window**.
    
2.  Open **Customize** and confirm the CircleCI skills appear.
    

For more information on Cursor skills, see the [Cursor plugin documentation](https://cursor.com/docs/plugins).

</Tab>
<Tab title="Codex">

CircleCI publishes the skills as a plugin in the [CircleCI Public Skills](https://github.com/CircleCI-Public/skills) repository.

Install that plugin with Codex’s marketplace and plugin workflow. For setup steps, see the [Codex plugin documentation](https://developers.openai.com/codex/plugins) and the [Codex skills documentation](https://developers.openai.com/codex/skills).

</Tab>
<Tab title="GitHub Copilot">

CircleCI publishes the skills as a plugin in the [CircleCI Public Skills](https://github.com/CircleCI-Public/skills) repository.

Install that plugin with GitHub Copilot’s marketplace and plugin workflow. For setup steps, see the [GitHub Copilot CLI plugin documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing).

</Tab>
</Tabs>

## Keep CircleCI agent skills up to date

CircleCI publishes skill updates in the [CircleCI Public Skills](https://github.com/CircleCI-Public/skills) repository. How you pick up those updates depends on how you installed the skills.

<Tabs>
<Tab title="Claude Code">

Claude Code caches the marketplace catalog. Refresh it, then load the new plugin version:

```shell
/plugin marketplace update circleci-public-skills
```

Third-party marketplaces do not auto-update by default. To have Claude Code refresh this marketplace and its installed plugins in the background, run `/plugin`, open **Marketplaces**, select the CircleCI marketplace, and enable auto-update.

Reload plugins when Claude Code prompts you, or start a new session. For more information, see the [Claude Code auto-update documentation](https://code.claude.com/docs/en/discover-plugins#configure-auto-updates).

</Tab>
<Tab title="Cursor">

Copied Cursor skills are a snapshot of the repository at install time. Cursor does not update them for you.

To refresh them, copy the skill folders again from `CircleCI-Public/skills`, then restart Cursor or run **Developer: Reload Window**.

</Tab>
<Tab title="Codex">

Use Codex’s marketplace and plugin update workflow. For current commands, see the [Codex plugin documentation](https://developers.openai.com/codex/plugins).

</Tab>
<Tab title="GitHub Copilot">

Use GitHub Copilot’s plugin update workflow. For current commands, see the [GitHub Copilot CLI plugin documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing).

</Tab>
</Tabs>

## Use CircleCI agent skills

After install, ask your agent for the outcome you want. Name the branch, project, or file when you can. The agent selects the matching skill.

You can also invoke a skill by name. In Claude Code and Cursor, type `circleci-builds`. In Codex and GitHub Copilot, use each product’s skill invocation flow.

Example requests:

*   Diagnose and fix build failures for the current branch.
    
*   Watch the CircleCI run for my current branch and report the results.
    
*   Review the CircleCI configuration for this project and suggest improvements.
    
*   Onboard my project to CircleCI.
    
*   Set up Chunk sidecars for this project.
    
*   Set up a testsuite for this project.
    
*   Set up CircleCI Smarter Testing for running tests in this project.
    

## Compare skills with other CircleCI AI tools

CircleCI agent skills, MCP servers, and Chunk work together in an agentic CI/CD loop. Use this page to install the plugin skills. Use the pages below for live CircleCI tools and for Chunk validation.

| Tool | What it is | Where to start |
| --- | --- | --- |
| CircleCI agent skills | Workflows your coding agent follows for CircleCI tasks. | This page. |
| CircleCI MCP servers | Live tools your agent can call to inspect and act on CircleCI runs. | [CircleCI MCP Overview](https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/) |
| Chunk | Validation that keeps up with your agents. Sidecars run lightweight checks in a clean cloud environment while your agent works. Chunk Tasks monitors and repairs CI. | [Chunk Overview and Setup](https://circleci.com/docs/guides/toolkit/chunk-setup-and-overview/) and [Install and Configure the Chunk CLI](https://circleci.com/docs/guides/toolkit/install-and-configure-the-chunk-cli/) |

## Next steps

*   [CircleCI MCP Overview](https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/)
    
*   [Connecting to the CircleCI MCP Server](https://circleci.com/docs/guides/toolkit/connecting-to-the-circleci-mcp-server/)
    
*   [Chunk Overview and Setup](https://circleci.com/docs/guides/toolkit/chunk-setup-and-overview/)
    
*   [Install and Configure the Chunk CLI](https://circleci.com/docs/guides/toolkit/install-and-configure-the-chunk-cli/)
    
*   [Getting Started With Smarter Testing](https://circleci.com/docs/guides/test/getting-started-with-smarter-testing/)
    
*   [CircleCI Public Skills repository](https://github.com/CircleCI-Public/skills)