CircleCI

View saved version →

---
name: chunk
description: Use CircleCI Chunk for AI-assisted CI/CD work through either the Chunk web UI or the chunk-cli. Trigger this skill when users ask to set up Chunk, troubleshoot or fix failing builds with Chunk, configure Chunk environments, schedule/proactively run Chunk tasks, or use chunk-cli commands such as init, validate, build-prompt, auth, sandbox, task, and skill install.
---

# Chunk

## Overview

Use this skill to choose the best Chunk workflow (UI or CLI), then execute it with clear prechecks and safe defaults. Keep responses action-oriented and grounded in verified commands and setup requirements.

## Workflow

1. Classify the request path.
- Use UI path for org setup, model-provider onboarding, fix buttons, or environment selection in the CircleCI app.
- Use CLI path for terminal-based project setup, validation hooks, prompt/context generation, sandbox operations, or scripted task execution.
- Use mixed path when users want UI setup plus CLI execution in the same flow.
2. Gather minimum context.
- Confirm repository/project, branch, and whether GitHub integration is in place.
- Confirm whether the user is using CircleCI-managed model provider or bring-your-own keys.
- For CLI operations, confirm local OS compatibility and required tokens/auth.
3. Execute using the matching reference.
- For UI/setup flows, load [chunk-ui.md](references/chunk-ui.md).
- For CLI flows, load [chunk-cli.md](references/chunk-cli.md).
4. Close with verification.
- State what was configured or run, what remains blocked, and the next safest command or UI action.

## Guardrails

- Treat Chunk features as beta unless the user confirms otherwise.
- Never expose or log secret values (API keys, tokens, bearer credentials).
- Do not invent `chunk` subcommands or flags; stick to documented command families.
- If sandbox features are requested, call out private preview status and any access gate.
- If a task depends on org-level prerequisites (GitHub App install, org toggles, contexts), verify those first.

## Reference Map

- [chunk-ui.md](references/chunk-ui.md): CircleCI app setup, provider onboarding, fix buttons, environment file/setup, and operational troubleshooting.
- [chunk-cli.md](references/chunk-cli.md): Installation, command map, quick-start flows, auth/env variables, and platform constraints.

## Output Contract

Provide:

1. Path chosen (UI, CLI, or mixed) and why.
2. Steps executed with exact command/UI actions.
3. Required prerequisites not yet met.
4. Concrete next action to finish the user’s goal.

Referenced files: 3

View saved version →

---
name: circleci-builds
description: Diagnose and fix failing CircleCI builds quickly and safely. Use when users ask to investigate failed CircleCI jobs, triage flaky pipelines, identify root causes from logs, and implement minimal fixes in configuration, test setup, or build-related code paths.
---

# CircleCI Builds

## Overview

Use this skill to turn failing CircleCI pipelines into actionable fixes with clear evidence. Prioritize fast root-cause isolation, minimal safe patches, and explicit validation criteria.

Read `references/transient-vs-deterministic.md` when deciding whether a failure should be fixed in code/config, retried, mitigated with rerun behavior, or reported as external/transient.
Read `../config/references/test-results-and-splitting.md` when the failure involves missing test metadata, flaky test reruns, test splitting, or JUnit XML setup.

## Inputs To Gather

- Failing pipeline/workflow/job identifier
- Branch and commit SHA
- First failing step and key log lines
- Whether rerun on same commit reproduces failure

## Workflow

1. Identify the primary failing signal.
   - Record the first failing job and step, not every downstream failure.
2. Classify issue type.
   - Config syntax/reference issue
   - Environment/toolchain mismatch
   - Dependency/cache issue
   - Test or build regression
   - External/transient failure
3. Apply the smallest viable fix.
   - Patch only files tied to confirmed root cause.
   - Keep workaround scope narrow.
4. Validate.
   - Run highest-signal local checks when possible.
   - Define expected CircleCI success signals for the rerun.
5. Report residual risk.
   - Call out unverified assumptions and likely follow-up checks.

## Guardrails

- Do not hide deterministic failures with blanket retries.
- Avoid mixing unrelated refactors into incident fixes.
- Treat external service outages as report-and-mitigate unless user asks for deeper redesign.
- Keep confidence levels explicit when logs are incomplete.
- Do not recommend automatic reruns or flaky-test workflows until the failure is classified as plausibly transient.

## Output Contract

Provide:

1. Failure summary (pipeline/workflow/job/step).
2. Root-cause hypothesis with confidence.
3. Applied changes with file list.
4. Validation plan and expected pass signal.
5. Remaining risk.

Referenced files: 1

View saved version →

---
name: circleci-cli
description: Operate and troubleshoot CircleCI using the CircleCI CLI. Use when users ask to authenticate CLI access, inspect pipeline/workflow/job status, validate configuration locally, rerun pipelines/jobs, trigger pipelines, or gather actionable diagnostics from CLI outputs.
---

# CircleCI CLI

## Overview

Use this skill when the fastest path is CircleCI CLI-driven operations rather than editing config first. Prioritize safe, read-first diagnostics, then run targeted mutating commands only after confirming scope.

## Inputs To Gather

- Repository path and target branch
- CircleCI project slug (if needed)
- Whether objective is inspect, rerun, trigger, or validate
- Required token/auth state and org permissions

## Workflow

1. Verify CLI and auth state.
   - Confirm `circleci` is installed and version is available.
   - Confirm token/auth before issuing remote CircleCI commands.
2. Run read-only diagnostics first.
   - Inspect available pipeline/project/trigger state and capture concrete identifiers.
   - Extract first failing scope and step details from supported command output before rerun/trigger actions.
3. Validate config locally when relevant.
   - Run config validation/processing commands before committing risky edits.
4. Run targeted mutation commands.
   - Rerun only required workflow/job scope.
   - Trigger pipelines with explicit parameters and branch context.
5. Report results and next action.
   - Provide exact command results, remaining blockers, and safest follow-up.

## Guardrails

- Prefer read-only commands before rerun/trigger/cancel operations.
- Confirm organization/project scope before mutating pipeline state.
- Never print raw secret values from environment variables or tokens.
- If permissions fail, report exact auth/scope gap and safest remediation.
- Respect installed CLI capabilities and avoid inventing commands.
- Do not use `circleci api`, `circleci workflow`, or other unavailable legacy commands unless `circleci help` confirms they exist.

## Installed CLI Compatibility

For newer `circleci` builds that expose domain subcommands (for example `pipeline`, `project`, `trigger`) but not `api`:

- Verify available commands first with `circleci help`.
- Use only discovered subcommands from help output.
- Prefer `circleci pipeline list|create|run` and `circleci trigger ...` for pipeline operations.
- For cloud job logs, use supported platform tools (CircleCI app/UI or connected CircleCI MCP tooling) if the CLI does not expose a logs command.

## Output Contract

Provide:

1. Commands run and purpose.
2. Key outputs (pipeline/workflow/job ids, status, failing step).
3. Actions taken (rerun/trigger/validate) and why.
4. Remaining blockers and next recommended CLI command.

View saved version →

---
name: circleci-config
description: Optimize CircleCI configuration for speed, reliability, and maintainability. Use when users ask to improve `.circleci/config.yml`, reduce CI runtime, tune caching/workspaces/parallelism, remove pipeline waste, or fix flaky pipeline behavior caused by configuration choices.
---

# CircleCI Config

## Overview

Use this skill to improve CircleCI performance and stability without changing product behavior. Focus on measured bottlenecks first, then implement the smallest safe config changes with clear validation criteria.

Read `references/cache-optimization.md` when the request involves `save_cache`, `restore_cache`, `persist_to_workspace`, `attach_workspace`, cache key design, dependency caching, lockfiles, or complaints about low cache hit rates, oversized caches, or wasted persistence steps.
Read `references/persisting-data.md` when the request involves choosing between caches, workspaces, and artifacts, or when data is being moved between jobs inefficiently.
Read `references/test-results-and-splitting.md` when the request involves slow test jobs, parallelism, flaky test visibility, missing JUnit XML, or `circleci tests run`.
Read `references/patterns.md` when the request involves approvals, branch/tag filters, schedules, deploy flow structure, or environment promotion patterns.

## Inputs To Gather

- `.yaml` and `.yml` files in `.circleci/` and any reusable config fragments
- Current pain points: duration, flakiness, cost, or maintainability
- Baseline metrics: slowest jobs, most frequent retries/failures, queue and run times
- Risk tolerance for structural changes

## Workflow

1. Build a baseline.
   - Identify top 1-3 longest jobs and top flaky jobs.
   - Capture before metrics (duration, pass rate, retries).
2. Remove pipeline waste.
   - Eliminate duplicate jobs/workflows.
   - Tighten branch/tag filters and workflow triggers.
3. Improve dependency and artifact flow.
   - Fix cache keys to include deterministic lockfile checks.
   - Use workspaces/artifacts to avoid rebuilding identical outputs.
   - Prefer cache scopes that are narrow, reproducible, and cheap to restore.
4. Apply safe parallelism.
   - Parallelize only proven bottlenecks.
   - Keep fan-out/fan-in readable and deterministic.
5. Validate impact.
   - Define expected metric changes and acceptance criteria before finalizing.

## Guardrails

- Prefer configuration fixes before proposing application code changes.
- Do not add blanket retries to hide deterministic failures.
- Preserve deployment safety gates while optimizing build/test stages.
- Keep changes incremental and easy to revert.
- Prefer language-specific cache directories over broad project snapshots.
- Avoid cache keys that rotate every run unless the user explicitly wants effectively write-only caches.

## Output Contract

Provide:

1. Baseline bottleneck summary.
2. Proposed or applied config changes with rationale.
3. Expected runtime/reliability impact.
4. Validation plan and rollback note.

Referenced files: 4