Documentation structure for LLMs (llms.txt)
CircleCI Logo

CircleCI agent skills

1 day ago · 10 min read
Cloud

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

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.

  • It is a good idea to install the CircleCI CLI, and authenticate for your CircleCI account. See The 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 page and the 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 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.

  • Claude Code

  • Cursor

  • Codex

  • GitHub Copilot

  1. In Claude Code, add the CircleCI marketplace:

    /plugin marketplace add CircleCI-Public/skills

  2. Install the CircleCI plugin:

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

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

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

CircleCI publishes the skills as a plugin in the CircleCI Public Skills repository.

Install that plugin with Codex’s marketplace and plugin workflow. For setup steps, see the Codex plugin documentation and the Codex skills documentation.

CircleCI publishes the skills as a plugin in the 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.

Keep CircleCI agent skills up to date

CircleCI publishes skill updates in the CircleCI Public Skills repository. How you pick up those updates depends on how you installed the skills.

  • Claude Code

  • Cursor

  • Codex

  • GitHub Copilot

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

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

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.

Use Codex’s marketplace and plugin update workflow. For current commands, see the Codex plugin documentation.

Use GitHub Copilot’s plugin update workflow. For current commands, see the GitHub Copilot CLI plugin documentation.

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

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 and Install and Configure the Chunk CLI

Next steps